# Cheese Store This is a fictional API contract used to demonstrate documentation generated by [Sourcey](https://github.com/sourcey/sourcey). The Cheese Store service, accounts, keys, and endpoints are examples; there is no live cheese-ordering service behind this reference. The Cheese Store API is organized around [REST](https://en.wikipedia.org/wiki/Representational_state_transfer). It uses resource-oriented URLs, standard HTTP methods, and returns JSON responses. All requests are authenticated using an API key or OAuth2 token. ## Getting Started Read the endpoints and schemas as examples. If you adapt this contract for a real API, issue your own credentials and send them in the `X-API-Key` header. ## Rate Limiting | Plan | Requests/hour | Burst | |------------|---------------|-------| | Free | 100 | 10 | | Pro | 10,000 | 100 | | Enterprise | Unlimited | 1,000 | When you exceed the rate limit, the API returns `429 Too Many Requests` with a `Retry-After` header. ## Pagination List endpoints return paginated results. Use `cursor` and `limit` query parameters: ```json { "items": [...], "nextCursor": "eyJpZCI6NDJ9", "hasMore": true } ``` Version: 2.0.0 Authentication: - api_key: apiKey, header X-API-Key. API key authentication. Include your API key in the `X-API-Key` header. This is an example scheme. Supply credentials from your own service when adapting this contract. - cheesy_oauth: oauth2. OAuth2 authentication for full API access - bearer_auth: http (bearer). JWT token obtained from the `/customer/login` endpoint ## GET /cheeses List all cheeses Returns a paginated list of cheeses in the store. Results can be filtered by status and sorted by name or creation date. The response includes cursor-based pagination. Use the `nextCursor` value from the response as the `cursor` parameter in subsequent requests. Authentication (security requirement alternatives): ```json [ { "api_key": [] }, { "cheesy_oauth": [ "read:cheeses" ] } ] ``` - api_key: apiKey, header X-API-Key. API key authentication. Include your API key in the `X-API-Key` header. This is an example scheme. Supply credentials from your own service when adapting this contract. - cheesy_oauth: oauth2. OAuth2 authentication for full API access; scopes: read:cheeses Parameters: - `cursor` (query, string, optional) - Pagination cursor from a previous response Type: string - `limit` (query, integer, optional) - Maximum number of cheeses to return Type: integer default: 20 minimum: 1 maximum: 100 - `status` (query, string, optional) - Filter by availability status Type: string enum: ["available","pending","sold"] - `sort` (query, string, optional) - Sort order for results Type: string default: "name" enum: ["name","-name","createdAt","-createdAt"] Responses: - 200: A paginated list of cheeses Content type: application/json Type: object Paginated list of cheeses Schema: [CheeseList](https://sourcey.com/examples/docs-showcase/reference/api/schemas/cheeselist-06d8bd48db.md) - `items` (optional) Type: array Items: Reference: [Cheese](https://sourcey.com/examples/docs-showcase/reference/api/schemas/cheese-6e5a59d4fd.md); Type: object - `nextCursor` (optional) Type: string; nullable Cursor for the next page (null if no more results) - `hasMore` (optional) Type: boolean Whether there are more results - `total` (optional) Type: integer Total number of matching cheeses - 429: Rate limit exceeded Content type: application/json Type: object Schema: [Error](https://sourcey.com/examples/docs-showcase/reference/api/schemas/error-54a0e8c17e.md) - `code` (required) Type: integer, int32 Example: ```json 404 ``` - `type` (optional) Type: string Example: ```json "Not found" ``` - `message` (required) Type: string Example: ```json "Your cheese has already been eaten" ``` ```json { "code": 429, "type": "Rate limited", "message": "Too many requests, please try again later" } ``` ## Examples ### cURL ```bash curl -X GET 'https://cheese.example.com/v2/cheeses' ``` ### TypeScript ```typescript const response = await fetch('https://cheese.example.com/v2/cheeses', { method: 'GET', }); const data: Record = await response.json(); ``` ### Python ```python import requests response = requests.get('https://cheese.example.com/v2/cheeses') data = response.json() ``` ### Go ```go package main import ( "fmt" "io" "net/http" ) func main() { req, _ := http.NewRequest("GET", "https://cheese.example.com/v2/cheeses", nil) resp, _ := http.DefaultClient.Do(req) defer resp.Body.Close() data, _ := io.ReadAll(resp.Body) fmt.Println(string(data)) } ``` ### Rust ```rust use reqwest; #[tokio::main] async fn main() -> Result<(), reqwest::Error> { let client = reqwest::Client::new(); let response = client.get("https://cheese.example.com/v2/cheeses") .send() .await? .text() .await?; println!("{}", response); Ok(()) } ``` ## POST /cheeses Add a new cheese Add a new cheese to the store inventory. The cheese name must be unique within its category. Authentication (security requirement alternatives): ```json [ { "cheesy_oauth": [ "write:cheeses" ] } ] ``` - cheesy_oauth: oauth2. OAuth2 authentication for full API access; scopes: write:cheeses Request body: application/json (required) Cheese object to add to the store Type: object Schema: [CheeseInput](https://sourcey.com/examples/docs-showcase/reference/api/schemas/cheeseinput-4479830925.md) - `name` (required) Type: string minLength: 1 maxLength: 100 - `category` (optional) Type: object - `name` (optional) Type: string - `photoUrls` (optional) Type: array Items: Type: string, uri - `tags` (optional) Type: array Items: Type: object - `name` (optional) Type: string - `status` (optional) Type: string default: "available" enum: ["available","pending","sold"] - `origin` (optional) Type: string; nullable - `pricePerKg` (optional) Type: number, float minimum: 0 exclusiveMinimum: true - `ageMonths` (optional) Type: integer minimum: 0 maximum: 120 - `organic` (optional) Type: boolean default: false ```json { "name": "Gorgonzola", "category": { "name": "Blue cheese" }, "origin": "Italy", "pricePerKg": 28.5 } ``` Responses: - 201: Cheese created successfully Content type: application/json Type: object Schema: [Cheese](https://sourcey.com/examples/docs-showcase/reference/api/schemas/cheese-6e5a59d4fd.md) - `id` (required) Type: integer, int64 Unique identifier Example: ```json 42 ``` - `name` (required) Type: string Name of the cheese minLength: 1 maxLength: 100 Example: ```json "Gorgonzola" ``` - `category` (optional) Reference: [Category](https://sourcey.com/examples/docs-showcase/reference/api/schemas/category-292c06f004.md); Type: object - `photoUrls` (optional) Type: array URLs of cheese photos Example: ```json [ "https://wannabechef.com/gorgonzola.jpg" ] ``` Items: Type: string, uri - `tags` (optional) Type: array Classification tags Items: Reference: [Tag](https://sourcey.com/examples/docs-showcase/reference/api/schemas/tag-1503916a2a.md); Type: object - `status` (required) Type: string Availability status in the store enum: ["available","pending","sold"] Example: ```json "available" ``` - `origin` (optional) Type: string; nullable Country of origin (null if unknown) Example: ```json "Italy" ``` - `pricePerKg` (optional) Type: number, float Price per kilogram in USD minimum: 0 exclusiveMinimum: true Example: ```json 28.5 ``` - `ageMonths` (optional) Type: integer Aging period in months minimum: 0 maximum: 120 Example: ```json 12 ``` - `organic` (optional) Type: boolean Whether the cheese is certified organic default: false - `createdAt` (optional) Type: string, date-time When the cheese was added to the store - `updatedAt` (optional) Type: string, date-time When the cheese was last updated - 409: A cheese with this name already exists in the category Content type: application/json Type: object Schema: [Error](https://sourcey.com/examples/docs-showcase/reference/api/schemas/error-54a0e8c17e.md) - `code` (required) Type: integer, int32 Example: ```json 404 ``` - `type` (optional) Type: string Example: ```json "Not found" ``` - `message` (required) Type: string Example: ```json "Your cheese has already been eaten" ``` - 422: The request body failed validation Content type: application/json Type: object Schema: [ValidationError](https://sourcey.com/examples/docs-showcase/reference/api/schemas/validationerror-bdfaef14be.md) - `code` (optional) Type: integer, int32 Example: ```json 422 ``` - `type` (optional) Type: string Example: ```json "Validation error" ``` - `message` (optional) Type: string Example: ```json "Your cheese is not mouldy enough" ``` - `errors` (optional) Type: array Individual field validation errors Items: Type: object - `field` (optional) Type: string The field that failed validation - `message` (optional) Type: string Human-readable error message ```json { "code": 422, "type": "Validation error", "message": "Your cheese is not mouldy enough", "errors": [ { "field": "name", "message": "Name is required" }, { "field": "status", "message": "Must be one of available, pending, sold" } ] } ``` ## Examples ### cURL ```bash curl -X POST 'https://cheese.example.com/v2/cheeses' \ -H 'Content-Type: application/json' \ -d '{ "name": "Gorgonzola", "category": { "name": "Blue cheese" }, "origin": "Italy", "pricePerKg": 28.5 }' ``` ### TypeScript ```typescript const response = await fetch('https://cheese.example.com/v2/cheeses', { method: 'POST', headers: { 'Content-Type': 'application/json', }, body: JSON.stringify({ "name": "Gorgonzola", "category": { "name": "Blue cheese" }, "origin": "Italy", "pricePerKg": 28.5 }), }); const data: Record = await response.json(); ``` ### Python ```python import requests payload = { "name": "Gorgonzola", "category": { "name": "Blue cheese" }, "origin": "Italy", "pricePerKg": 28.5 } response = requests.post('https://cheese.example.com/v2/cheeses', json=payload) data = response.json() ``` ### Go ```go package main import ( "fmt" "io" "net/http" "strings" ) func main() { body := strings.NewReader(`{ "name": "Gorgonzola", "category": { "name": "Blue cheese" }, "origin": "Italy", "pricePerKg": 28.5 }`) req, _ := http.NewRequest("POST", "https://cheese.example.com/v2/cheeses", body) req.Header.Set("Content-Type", "application/json") resp, _ := http.DefaultClient.Do(req) defer resp.Body.Close() data, _ := io.ReadAll(resp.Body) fmt.Println(string(data)) } ``` ### Rust ```rust use reqwest; #[tokio::main] async fn main() -> Result<(), reqwest::Error> { let client = reqwest::Client::new(); let body = serde_json::json!({ "name": "Gorgonzola", "category": { "name": "Blue cheese" }, "origin": "Italy", "pricePerKg": 28.5 }); let response = client.post("https://cheese.example.com/v2/cheeses") .json(&body) .send() .await? .text() .await?; println!("{}", response); Ok(()) } ``` ## PUT /cheeses Update an existing cheese Replace an existing cheese with updated data. The cheese ID in the body must match an existing cheese. Authentication (security requirement alternatives): ```json [ { "cheesy_oauth": [ "write:cheeses" ] } ] ``` - cheesy_oauth: oauth2. OAuth2 authentication for full API access; scopes: write:cheeses Request body: application/json (required) Cheese object with updated fields Type: object Schema: [Cheese](https://sourcey.com/examples/docs-showcase/reference/api/schemas/cheese-6e5a59d4fd.md) - `id` (required) Type: integer, int64 Unique identifier Example: ```json 42 ``` - `name` (required) Type: string Name of the cheese minLength: 1 maxLength: 100 Example: ```json "Gorgonzola" ``` - `category` (optional) Reference: [Category](https://sourcey.com/examples/docs-showcase/reference/api/schemas/category-292c06f004.md); Type: object - `photoUrls` (optional) Type: array URLs of cheese photos Example: ```json [ "https://wannabechef.com/gorgonzola.jpg" ] ``` Items: Type: string, uri - `tags` (optional) Type: array Classification tags Items: Reference: [Tag](https://sourcey.com/examples/docs-showcase/reference/api/schemas/tag-1503916a2a.md); Type: object - `status` (required) Type: string Availability status in the store enum: ["available","pending","sold"] Example: ```json "available" ``` - `origin` (optional) Type: string; nullable Country of origin (null if unknown) Example: ```json "Italy" ``` - `pricePerKg` (optional) Type: number, float Price per kilogram in USD minimum: 0 exclusiveMinimum: true Example: ```json 28.5 ``` - `ageMonths` (optional) Type: integer Aging period in months minimum: 0 maximum: 120 Example: ```json 12 ``` - `organic` (optional) Type: boolean Whether the cheese is certified organic default: false - `createdAt` (optional) Type: string, date-time When the cheese was added to the store - `updatedAt` (optional) Type: string, date-time When the cheese was last updated Responses: - 200: Cheese updated successfully Content type: application/json Type: object Schema: [Cheese](https://sourcey.com/examples/docs-showcase/reference/api/schemas/cheese-6e5a59d4fd.md) - `id` (required) Type: integer, int64 Unique identifier Example: ```json 42 ``` - `name` (required) Type: string Name of the cheese minLength: 1 maxLength: 100 Example: ```json "Gorgonzola" ``` - `category` (optional) Reference: [Category](https://sourcey.com/examples/docs-showcase/reference/api/schemas/category-292c06f004.md); Type: object - `photoUrls` (optional) Type: array URLs of cheese photos Example: ```json [ "https://wannabechef.com/gorgonzola.jpg" ] ``` Items: Type: string, uri - `tags` (optional) Type: array Classification tags Items: Reference: [Tag](https://sourcey.com/examples/docs-showcase/reference/api/schemas/tag-1503916a2a.md); Type: object - `status` (required) Type: string Availability status in the store enum: ["available","pending","sold"] Example: ```json "available" ``` - `origin` (optional) Type: string; nullable Country of origin (null if unknown) Example: ```json "Italy" ``` - `pricePerKg` (optional) Type: number, float Price per kilogram in USD minimum: 0 exclusiveMinimum: true Example: ```json 28.5 ``` - `ageMonths` (optional) Type: integer Aging period in months minimum: 0 maximum: 120 Example: ```json 12 ``` - `organic` (optional) Type: boolean Whether the cheese is certified organic default: false - `createdAt` (optional) Type: string, date-time When the cheese was added to the store - `updatedAt` (optional) Type: string, date-time When the cheese was last updated - 404: The requested resource was not found Content type: application/json Type: object Schema: [Error](https://sourcey.com/examples/docs-showcase/reference/api/schemas/error-54a0e8c17e.md) - `code` (required) Type: integer, int32 Example: ```json 404 ``` - `type` (optional) Type: string Example: ```json "Not found" ``` - `message` (required) Type: string Example: ```json "Your cheese has already been eaten" ``` ```json { "code": 404, "type": "Not found", "message": "Your cheese has already been eaten" } ``` - 422: The request body failed validation Content type: application/json Type: object Schema: [ValidationError](https://sourcey.com/examples/docs-showcase/reference/api/schemas/validationerror-bdfaef14be.md) - `code` (optional) Type: integer, int32 Example: ```json 422 ``` - `type` (optional) Type: string Example: ```json "Validation error" ``` - `message` (optional) Type: string Example: ```json "Your cheese is not mouldy enough" ``` - `errors` (optional) Type: array Individual field validation errors Items: Type: object - `field` (optional) Type: string The field that failed validation - `message` (optional) Type: string Human-readable error message ```json { "code": 422, "type": "Validation error", "message": "Your cheese is not mouldy enough", "errors": [ { "field": "name", "message": "Name is required" }, { "field": "status", "message": "Must be one of available, pending, sold" } ] } ``` ## Examples ### cURL ```bash curl -X PUT 'https://cheese.example.com/v2/cheeses' \ -H 'Content-Type: application/json' \ -d '{ "id": 42, "name": "Gorgonzola", "category": { "id": 1, "name": "Italian Cheese" }, "photoUrls": [ "https://wannabechef.com/gorgonzola.jpg" ], "tags": [ { "id": 1, "name": "blue" } ], "status": "available", "origin": "Italy", "pricePerKg": 28.5, "ageMonths": 12, "organic": false, "createdAt": "2024-01-15T09:30:00Z", "updatedAt": "2024-01-15T09:30:00Z" }' ``` ### TypeScript ```typescript const response = await fetch('https://cheese.example.com/v2/cheeses', { method: 'PUT', headers: { 'Content-Type': 'application/json', }, body: JSON.stringify({ "id": 42, "name": "Gorgonzola", "category": { "id": 1, "name": "Italian Cheese" }, "photoUrls": [ "https://wannabechef.com/gorgonzola.jpg" ], "tags": [ { "id": 1, "name": "blue" } ], "status": "available", "origin": "Italy", "pricePerKg": 28.5, "ageMonths": 12, "organic": false, "createdAt": "2024-01-15T09:30:00Z", "updatedAt": "2024-01-15T09:30:00Z" }), }); const data: Record = await response.json(); ``` ### Python ```python import requests payload = { "id": 42, "name": "Gorgonzola", "category": { "id": 1, "name": "Italian Cheese" }, "photoUrls": [ "https://wannabechef.com/gorgonzola.jpg" ], "tags": [ { "id": 1, "name": "blue" } ], "status": "available", "origin": "Italy", "pricePerKg": 28.5, "ageMonths": 12, "organic": False, "createdAt": "2024-01-15T09:30:00Z", "updatedAt": "2024-01-15T09:30:00Z" } response = requests.put('https://cheese.example.com/v2/cheeses', json=payload) data = response.json() ``` ### Go ```go package main import ( "fmt" "io" "net/http" "strings" ) func main() { body := strings.NewReader(`{ "id": 42, "name": "Gorgonzola", "category": { "id": 1, "name": "Italian Cheese" }, "photoUrls": [ "https://wannabechef.com/gorgonzola.jpg" ], "tags": [ { "id": 1, "name": "blue" } ], "status": "available", "origin": "Italy", "pricePerKg": 28.5, "ageMonths": 12, "organic": false, "createdAt": "2024-01-15T09:30:00Z", "updatedAt": "2024-01-15T09:30:00Z" }`) req, _ := http.NewRequest("PUT", "https://cheese.example.com/v2/cheeses", body) req.Header.Set("Content-Type", "application/json") resp, _ := http.DefaultClient.Do(req) defer resp.Body.Close() data, _ := io.ReadAll(resp.Body) fmt.Println(string(data)) } ``` ### Rust ```rust use reqwest; #[tokio::main] async fn main() -> Result<(), reqwest::Error> { let client = reqwest::Client::new(); let body = serde_json::json!({ "id": 42, "name": "Gorgonzola", "category": { "id": 1, "name": "Italian Cheese" }, "photoUrls": [ "https://wannabechef.com/gorgonzola.jpg" ], "tags": [ { "id": 1, "name": "blue" } ], "status": "available", "origin": "Italy", "pricePerKg": 28.5, "ageMonths": 12, "organic": false, "createdAt": "2024-01-15T09:30:00Z", "updatedAt": "2024-01-15T09:30:00Z" }); let response = client.put("https://cheese.example.com/v2/cheeses") .json(&body) .send() .await? .text() .await?; println!("{}", response); Ok(()) } ``` ## GET /cheeses/findByStatus Find cheeses by status Multiple status values can be provided as comma-separated strings. Returns all cheeses matching any of the given statuses. Authentication (security requirement alternatives): ```json [ { "cheesy_oauth": [ "read:cheeses" ] } ] ``` - cheesy_oauth: oauth2. OAuth2 authentication for full API access; scopes: read:cheeses Parameters: - `status` (query, array, required) - Status values to filter by Type: array Items: Type: string default: "available" enum: ["available","pending","sold"] Responses: - 200: Matching cheeses Content type: application/json Type: array Items: Reference: [Cheese](https://sourcey.com/examples/docs-showcase/reference/api/schemas/cheese-6e5a59d4fd.md); Type: object - 400: Invalid status value provided Content type: application/json Type: object Schema: [Error](https://sourcey.com/examples/docs-showcase/reference/api/schemas/error-54a0e8c17e.md) - `code` (required) Type: integer, int32 Example: ```json 404 ``` - `type` (optional) Type: string Example: ```json "Not found" ``` - `message` (required) Type: string Example: ```json "Your cheese has already been eaten" ``` ## Examples ### cURL ```bash curl -X GET 'https://cheese.example.com/v2/cheeses/findByStatus' ``` ### TypeScript ```typescript const response = await fetch('https://cheese.example.com/v2/cheeses/findByStatus', { method: 'GET', }); const data: Record = await response.json(); ``` ### Python ```python import requests response = requests.get('https://cheese.example.com/v2/cheeses/findByStatus') data = response.json() ``` ### Go ```go package main import ( "fmt" "io" "net/http" ) func main() { req, _ := http.NewRequest("GET", "https://cheese.example.com/v2/cheeses/findByStatus", nil) resp, _ := http.DefaultClient.Do(req) defer resp.Body.Close() data, _ := io.ReadAll(resp.Body) fmt.Println(string(data)) } ``` ### Rust ```rust use reqwest; #[tokio::main] async fn main() -> Result<(), reqwest::Error> { let client = reqwest::Client::new(); let response = client.get("https://cheese.example.com/v2/cheeses/findByStatus") .send() .await? .text() .await?; println!("{}", response); Ok(()) } ``` ## GET /cheeses/findByTags Find cheeses by tags Multiple tags can be provided as comma-separated strings (e.g. `?tags=blue,italian,aged`). **Deprecated:** Use `GET /cheeses?tags=blue,italian` query parameter instead. Deprecated. Authentication (security requirement alternatives): ```json [ { "cheesy_oauth": [ "read:cheeses" ] } ] ``` - cheesy_oauth: oauth2. OAuth2 authentication for full API access; scopes: read:cheeses Parameters: - `tags` (query, array, required) - Tags to filter by Type: array Items: Type: string Responses: - 200: Matching cheeses Content type: application/json Type: array Items: Reference: [Cheese](https://sourcey.com/examples/docs-showcase/reference/api/schemas/cheese-6e5a59d4fd.md); Type: object - 400: Invalid tag value Content type: application/json Type: object Schema: [Error](https://sourcey.com/examples/docs-showcase/reference/api/schemas/error-54a0e8c17e.md) - `code` (required) Type: integer, int32 Example: ```json 404 ``` - `type` (optional) Type: string Example: ```json "Not found" ``` - `message` (required) Type: string Example: ```json "Your cheese has already been eaten" ``` ## Examples ### cURL ```bash curl -X GET 'https://cheese.example.com/v2/cheeses/findByTags' ``` ### TypeScript ```typescript const response = await fetch('https://cheese.example.com/v2/cheeses/findByTags', { method: 'GET', }); const data: Record = await response.json(); ``` ### Python ```python import requests response = requests.get('https://cheese.example.com/v2/cheeses/findByTags') data = response.json() ``` ### Go ```go package main import ( "fmt" "io" "net/http" ) func main() { req, _ := http.NewRequest("GET", "https://cheese.example.com/v2/cheeses/findByTags", nil) resp, _ := http.DefaultClient.Do(req) defer resp.Body.Close() data, _ := io.ReadAll(resp.Body) fmt.Println(string(data)) } ``` ### Rust ```rust use reqwest; #[tokio::main] async fn main() -> Result<(), reqwest::Error> { let client = reqwest::Client::new(); let response = client.get("https://cheese.example.com/v2/cheeses/findByTags") .send() .await? .text() .await?; println!("{}", response); Ok(()) } ``` ## GET /cheeses/{cheeseId} Get cheese by ID Returns detailed information about a specific cheese, including its category, tags, and current availability status. Authentication (security requirement alternatives): ```json [ { "api_key": [] } ] ``` - api_key: apiKey, header X-API-Key. API key authentication. Include your API key in the `X-API-Key` header. This is an example scheme. Supply credentials from your own service when adapting this contract. Parameters: - `cheeseId` (path, integer, int64, required) - Unique identifier for the cheese Type: integer, int64 minimum: 1 Responses: - 200: Cheese details Content type: application/json Type: object Schema: [Cheese](https://sourcey.com/examples/docs-showcase/reference/api/schemas/cheese-6e5a59d4fd.md) - `id` (required) Type: integer, int64 Unique identifier Example: ```json 42 ``` - `name` (required) Type: string Name of the cheese minLength: 1 maxLength: 100 Example: ```json "Gorgonzola" ``` - `category` (optional) Reference: [Category](https://sourcey.com/examples/docs-showcase/reference/api/schemas/category-292c06f004.md); Type: object - `photoUrls` (optional) Type: array URLs of cheese photos Example: ```json [ "https://wannabechef.com/gorgonzola.jpg" ] ``` Items: Type: string, uri - `tags` (optional) Type: array Classification tags Items: Reference: [Tag](https://sourcey.com/examples/docs-showcase/reference/api/schemas/tag-1503916a2a.md); Type: object - `status` (required) Type: string Availability status in the store enum: ["available","pending","sold"] Example: ```json "available" ``` - `origin` (optional) Type: string; nullable Country of origin (null if unknown) Example: ```json "Italy" ``` - `pricePerKg` (optional) Type: number, float Price per kilogram in USD minimum: 0 exclusiveMinimum: true Example: ```json 28.5 ``` - `ageMonths` (optional) Type: integer Aging period in months minimum: 0 maximum: 120 Example: ```json 12 ``` - `organic` (optional) Type: boolean Whether the cheese is certified organic default: false - `createdAt` (optional) Type: string, date-time When the cheese was added to the store - `updatedAt` (optional) Type: string, date-time When the cheese was last updated ```json { "id": 42, "name": "Gorgonzola", "category": { "id": 1, "name": "Italian Cheese" }, "status": "available", "photoUrls": [ "https://wannabechef.com/gorgonzola.jpg" ], "tags": [ { "id": 1, "name": "blue" }, { "id": 2, "name": "italian" } ] } ``` - 404: The requested resource was not found Content type: application/json Type: object Schema: [Error](https://sourcey.com/examples/docs-showcase/reference/api/schemas/error-54a0e8c17e.md) - `code` (required) Type: integer, int32 Example: ```json 404 ``` - `type` (optional) Type: string Example: ```json "Not found" ``` - `message` (required) Type: string Example: ```json "Your cheese has already been eaten" ``` ```json { "code": 404, "type": "Not found", "message": "Your cheese has already been eaten" } ``` ## Examples ### cURL ```bash curl -X GET 'https://cheese.example.com/v2/cheeses/{cheeseId}' ``` ### TypeScript ```typescript const response = await fetch('https://cheese.example.com/v2/cheeses/{cheeseId}', { method: 'GET', }); const data: Record = await response.json(); ``` ### Python ```python import requests response = requests.get('https://cheese.example.com/v2/cheeses/{cheeseId}') data = response.json() ``` ### Go ```go package main import ( "fmt" "io" "net/http" ) func main() { req, _ := http.NewRequest("GET", "https://cheese.example.com/v2/cheeses/{cheeseId}", nil) resp, _ := http.DefaultClient.Do(req) defer resp.Body.Close() data, _ := io.ReadAll(resp.Body) fmt.Println(string(data)) } ``` ### Rust ```rust use reqwest; #[tokio::main] async fn main() -> Result<(), reqwest::Error> { let client = reqwest::Client::new(); let response = client.get("https://cheese.example.com/v2/cheeses/{cheeseId}") .send() .await? .text() .await?; println!("{}", response); Ok(()) } ``` ## POST /cheeses/{cheeseId} Update cheese with form data Updates specific fields of a cheese using form data. Only provided fields are updated. Authentication (security requirement alternatives): ```json [ { "cheesy_oauth": [ "write:cheeses" ] } ] ``` - cheesy_oauth: oauth2. OAuth2 authentication for full API access; scopes: write:cheeses Parameters: - `cheeseId` (path, integer, int64, required) - Unique identifier for the cheese Type: integer, int64 minimum: 1 - `name` (query, string, optional) - Updated name of the cheese Type: string - `status` (query, string, optional) - Updated status of the cheese Type: string enum: ["available","pending","sold"] Responses: - 200: Cheese updated Content type: application/json Type: object Schema: [Cheese](https://sourcey.com/examples/docs-showcase/reference/api/schemas/cheese-6e5a59d4fd.md) - `id` (required) Type: integer, int64 Unique identifier Example: ```json 42 ``` - `name` (required) Type: string Name of the cheese minLength: 1 maxLength: 100 Example: ```json "Gorgonzola" ``` - `category` (optional) Reference: [Category](https://sourcey.com/examples/docs-showcase/reference/api/schemas/category-292c06f004.md); Type: object - `photoUrls` (optional) Type: array URLs of cheese photos Example: ```json [ "https://wannabechef.com/gorgonzola.jpg" ] ``` Items: Type: string, uri - `tags` (optional) Type: array Classification tags Items: Reference: [Tag](https://sourcey.com/examples/docs-showcase/reference/api/schemas/tag-1503916a2a.md); Type: object - `status` (required) Type: string Availability status in the store enum: ["available","pending","sold"] Example: ```json "available" ``` - `origin` (optional) Type: string; nullable Country of origin (null if unknown) Example: ```json "Italy" ``` - `pricePerKg` (optional) Type: number, float Price per kilogram in USD minimum: 0 exclusiveMinimum: true Example: ```json 28.5 ``` - `ageMonths` (optional) Type: integer Aging period in months minimum: 0 maximum: 120 Example: ```json 12 ``` - `organic` (optional) Type: boolean Whether the cheese is certified organic default: false - `createdAt` (optional) Type: string, date-time When the cheese was added to the store - `updatedAt` (optional) Type: string, date-time When the cheese was last updated - 404: The requested resource was not found Content type: application/json Type: object Schema: [Error](https://sourcey.com/examples/docs-showcase/reference/api/schemas/error-54a0e8c17e.md) - `code` (required) Type: integer, int32 Example: ```json 404 ``` - `type` (optional) Type: string Example: ```json "Not found" ``` - `message` (required) Type: string Example: ```json "Your cheese has already been eaten" ``` ```json { "code": 404, "type": "Not found", "message": "Your cheese has already been eaten" } ``` - 422: The request body failed validation Content type: application/json Type: object Schema: [ValidationError](https://sourcey.com/examples/docs-showcase/reference/api/schemas/validationerror-bdfaef14be.md) - `code` (optional) Type: integer, int32 Example: ```json 422 ``` - `type` (optional) Type: string Example: ```json "Validation error" ``` - `message` (optional) Type: string Example: ```json "Your cheese is not mouldy enough" ``` - `errors` (optional) Type: array Individual field validation errors Items: Type: object - `field` (optional) Type: string The field that failed validation - `message` (optional) Type: string Human-readable error message ```json { "code": 422, "type": "Validation error", "message": "Your cheese is not mouldy enough", "errors": [ { "field": "name", "message": "Name is required" }, { "field": "status", "message": "Must be one of available, pending, sold" } ] } ``` ## Examples ### cURL ```bash curl -X POST 'https://cheese.example.com/v2/cheeses/{cheeseId}' ``` ### TypeScript ```typescript const response = await fetch('https://cheese.example.com/v2/cheeses/{cheeseId}', { method: 'POST', }); const data: Record = await response.json(); ``` ### Python ```python import requests response = requests.post('https://cheese.example.com/v2/cheeses/{cheeseId}') data = response.json() ``` ### Go ```go package main import ( "fmt" "io" "net/http" ) func main() { req, _ := http.NewRequest("POST", "https://cheese.example.com/v2/cheeses/{cheeseId}", nil) resp, _ := http.DefaultClient.Do(req) defer resp.Body.Close() data, _ := io.ReadAll(resp.Body) fmt.Println(string(data)) } ``` ### Rust ```rust use reqwest; #[tokio::main] async fn main() -> Result<(), reqwest::Error> { let client = reqwest::Client::new(); let response = client.post("https://cheese.example.com/v2/cheeses/{cheeseId}") .send() .await? .text() .await?; println!("{}", response); Ok(()) } ``` ## DELETE /cheeses/{cheeseId} Delete a cheese Permanently removes a cheese from the store. This action cannot be undone. Any pending orders for this cheese will be cancelled. Authentication (security requirement alternatives): ```json [ { "cheesy_oauth": [ "write:cheeses" ] } ] ``` - cheesy_oauth: oauth2. OAuth2 authentication for full API access; scopes: write:cheeses Parameters: - `cheeseId` (path, integer, int64, required) - Unique identifier for the cheese Type: integer, int64 minimum: 1 - `X-Confirm-Delete` (header, boolean, required) - Must be set to `true` to confirm deletion Type: boolean const: true Responses: - 204: Cheese deleted successfully - 404: The requested resource was not found Content type: application/json Type: object Schema: [Error](https://sourcey.com/examples/docs-showcase/reference/api/schemas/error-54a0e8c17e.md) - `code` (required) Type: integer, int32 Example: ```json 404 ``` - `type` (optional) Type: string Example: ```json "Not found" ``` - `message` (required) Type: string Example: ```json "Your cheese has already been eaten" ``` ```json { "code": 404, "type": "Not found", "message": "Your cheese has already been eaten" } ``` - 409: Cheese has active orders and cannot be deleted Content type: application/json Type: object Schema: [Error](https://sourcey.com/examples/docs-showcase/reference/api/schemas/error-54a0e8c17e.md) - `code` (required) Type: integer, int32 Example: ```json 404 ``` - `type` (optional) Type: string Example: ```json "Not found" ``` - `message` (required) Type: string Example: ```json "Your cheese has already been eaten" ``` ## Examples ### cURL ```bash curl -X DELETE 'https://cheese.example.com/v2/cheeses/{cheeseId}' ``` ### TypeScript ```typescript const response = await fetch('https://cheese.example.com/v2/cheeses/{cheeseId}', { method: 'DELETE', }); const data: Record = await response.json(); ``` ### Python ```python import requests response = requests.delete('https://cheese.example.com/v2/cheeses/{cheeseId}') data = response.json() ``` ### Go ```go package main import ( "fmt" "io" "net/http" ) func main() { req, _ := http.NewRequest("DELETE", "https://cheese.example.com/v2/cheeses/{cheeseId}", nil) resp, _ := http.DefaultClient.Do(req) defer resp.Body.Close() data, _ := io.ReadAll(resp.Body) fmt.Println(string(data)) } ``` ### Rust ```rust use reqwest; #[tokio::main] async fn main() -> Result<(), reqwest::Error> { let client = reqwest::Client::new(); let response = client.delete("https://cheese.example.com/v2/cheeses/{cheeseId}") .send() .await? .text() .await?; println!("{}", response); Ok(()) } ``` ## POST /cheeses/{cheeseId}/uploadImage Upload a cheese image Upload a photo of the cheese. Supports JPEG, PNG, and WebP formats. Maximum file size is 10MB. Authentication (security requirement alternatives): ```json [ { "cheesy_oauth": [ "write:cheeses" ] } ] ``` - cheesy_oauth: oauth2. OAuth2 authentication for full API access; scopes: write:cheeses Parameters: - `cheeseId` (path, integer, int64, required) - ID of cheese to upload image for Type: integer, int64 Request body: multipart/form-data (required) Type: object - `file` (required) Type: string, binary Image file (JPEG, PNG, or WebP, max 10MB) - `caption` (optional) Type: string Optional caption for the image maxLength: 200 - `isPrimary` (optional) Type: boolean Set as the primary display image default: false Responses: - 200: Image uploaded successfully Content type: application/json Type: object - `imageUrl` (optional) Type: string, uri - `thumbnailUrl` (optional) Type: string, uri - `size` (optional) Type: integer File size in bytes - 413: File too large (max 10MB) Content type: application/json Type: object Schema: [Error](https://sourcey.com/examples/docs-showcase/reference/api/schemas/error-54a0e8c17e.md) - `code` (required) Type: integer, int32 Example: ```json 404 ``` - `type` (optional) Type: string Example: ```json "Not found" ``` - `message` (required) Type: string Example: ```json "Your cheese has already been eaten" ``` - 415: Unsupported media type Content type: application/json Type: object Schema: [Error](https://sourcey.com/examples/docs-showcase/reference/api/schemas/error-54a0e8c17e.md) - `code` (required) Type: integer, int32 Example: ```json 404 ``` - `type` (optional) Type: string Example: ```json "Not found" ``` - `message` (required) Type: string Example: ```json "Your cheese has already been eaten" ``` ## Examples ### cURL ```bash curl -X POST 'https://cheese.example.com/v2/cheeses/{cheeseId}/uploadImage' \ -H 'Content-Type: multipart/form-data' \ -d '{ "file": "", "caption": "string", "isPrimary": false }' ``` ### TypeScript ```typescript const response = await fetch('https://cheese.example.com/v2/cheeses/{cheeseId}/uploadImage', { method: 'POST', headers: { 'Content-Type': 'multipart/form-data', }, body: JSON.stringify({ "file": "", "caption": "string", "isPrimary": false }), }); const data: Record = await response.json(); ``` ### Python ```python import requests payload = { "file": "", "caption": "string", "isPrimary": False } response = requests.post('https://cheese.example.com/v2/cheeses/{cheeseId}/uploadImage', json=payload) data = response.json() ``` ### Go ```go package main import ( "fmt" "io" "net/http" "strings" ) func main() { body := strings.NewReader(`{ "file": "", "caption": "string", "isPrimary": false }`) req, _ := http.NewRequest("POST", "https://cheese.example.com/v2/cheeses/{cheeseId}/uploadImage", body) req.Header.Set("Content-Type", "application/json") resp, _ := http.DefaultClient.Do(req) defer resp.Body.Close() data, _ := io.ReadAll(resp.Body) fmt.Println(string(data)) } ``` ### Rust ```rust use reqwest; #[tokio::main] async fn main() -> Result<(), reqwest::Error> { let client = reqwest::Client::new(); let body = serde_json::json!({ "file": "", "caption": "string", "isPrimary": false }); let response = client.post("https://cheese.example.com/v2/cheeses/{cheeseId}/uploadImage") .json(&body) .send() .await? .text() .await?; println!("{}", response); Ok(()) } ``` ## GET /store/inventory Get store inventory Returns a map of cheese status codes to quantities, representing the current inventory levels. Authentication (security requirement alternatives): ```json [ { "api_key": [] } ] ``` - api_key: apiKey, header X-API-Key. API key authentication. Include your API key in the `X-API-Key` header. This is an example scheme. Supply credentials from your own service when adapting this contract. Responses: - 200: Inventory counts by status Content type: application/json Type: object Additional properties: Type: integer, int32 ```json { "available": 256, "pending": 34, "sold": 1089 } ``` ## Examples ### cURL ```bash curl -X GET 'https://cheese.example.com/v2/store/inventory' ``` ### TypeScript ```typescript const response = await fetch('https://cheese.example.com/v2/store/inventory', { method: 'GET', }); const data: Record = await response.json(); ``` ### Python ```python import requests response = requests.get('https://cheese.example.com/v2/store/inventory') data = response.json() ``` ### Go ```go package main import ( "fmt" "io" "net/http" ) func main() { req, _ := http.NewRequest("GET", "https://cheese.example.com/v2/store/inventory", nil) resp, _ := http.DefaultClient.Do(req) defer resp.Body.Close() data, _ := io.ReadAll(resp.Body) fmt.Println(string(data)) } ``` ### Rust ```rust use reqwest; #[tokio::main] async fn main() -> Result<(), reqwest::Error> { let client = reqwest::Client::new(); let response = client.get("https://cheese.example.com/v2/store/inventory") .send() .await? .text() .await?; println!("{}", response); Ok(()) } ``` ## POST /store/order Place a cheese order Place an order to purchase cheese from the store. The cheese must be in `available` status. Orders are processed asynchronously. Use the returned order ID to check status via `GET /store/order/{orderId}`. Authentication (security requirement alternatives): ```json [ { "cheesy_oauth": [ "write:orders" ] } ] ``` - cheesy_oauth: oauth2. OAuth2 authentication for full API access; scopes: write:orders Request body: application/json (required) Order details Type: object Schema: [OrderInput](https://sourcey.com/examples/docs-showcase/reference/api/schemas/orderinput-fdf8fed0b2.md) - `items` (required) Type: array minItems: 1 maxItems: 50 Items: Type: object - `cheeseId` (required) Type: integer, int64 - `quantity` (required) Type: integer minimum: 1 maximum: 100 - `shippingAddress` (required) Reference: [Address](https://sourcey.com/examples/docs-showcase/reference/api/schemas/address-56ef8f2095.md); Type: object - `notes` (optional) Type: string; nullable maxLength: 500 ```json { "items": [ { "cheeseId": 42, "quantity": 3 }, { "cheeseId": 17, "quantity": 1 } ], "shippingAddress": { "street": "123 Cheese Lane", "city": "Cheddarville", "state": "WI", "zipCode": "53001", "country": "US" }, "notes": "Please wrap each wheel separately" } ``` Responses: - 201: Order placed successfully Content type: application/json Type: object Schema: [Order](https://sourcey.com/examples/docs-showcase/reference/api/schemas/order-6be090825c.md) Example: ```json { "id": 1001, "items": [ { "cheeseId": 42, "cheeseName": "Gorgonzola", "quantity": 3, "pricePerKg": 28.5 }, { "cheeseId": 17, "cheeseName": "Brie", "quantity": 1, "pricePerKg": 22 } ], "shippingAddress": { "street": "123 Cheese Lane", "city": "Cheddarville", "state": "WI", "zipCode": "53001", "country": "US" }, "status": "placed", "notes": "Please wrap each wheel separately", "total": 114.5, "shipDate": null, "createdAt": "2026-03-10T14:30:00Z", "updatedAt": "2026-03-10T14:30:00Z" } ``` - `id` (optional) Type: integer, int64 Example: ```json 1001 ``` - `items` (optional) Type: array Items: Reference: [OrderItem](https://sourcey.com/examples/docs-showcase/reference/api/schemas/orderitem-6b56cf7850.md); Type: object - `shippingAddress` (optional) Reference: [Address](https://sourcey.com/examples/docs-showcase/reference/api/schemas/address-56ef8f2095.md); Type: object - `status` (optional) Type: string Order lifecycle status enum: ["placed","approved","shipped","delivered","cancelled"] Example: ```json "placed" ``` - `notes` (optional) Type: string; nullable Special instructions for the order - `total` (optional) Type: number, float Order total in USD Example: ```json 114.5 ``` - `shipDate` (optional) Type: string, date-time; nullable Estimated ship date (null if not yet scheduled) - `createdAt` (optional) Type: string, date-time - `updatedAt` (optional) Type: string, date-time - 422: The request body failed validation Content type: application/json Type: object Schema: [ValidationError](https://sourcey.com/examples/docs-showcase/reference/api/schemas/validationerror-bdfaef14be.md) - `code` (optional) Type: integer, int32 Example: ```json 422 ``` - `type` (optional) Type: string Example: ```json "Validation error" ``` - `message` (optional) Type: string Example: ```json "Your cheese is not mouldy enough" ``` - `errors` (optional) Type: array Individual field validation errors Items: Type: object - `field` (optional) Type: string The field that failed validation - `message` (optional) Type: string Human-readable error message ```json { "code": 422, "type": "Validation error", "message": "Your cheese is not mouldy enough", "errors": [ { "field": "name", "message": "Name is required" }, { "field": "status", "message": "Must be one of available, pending, sold" } ] } ``` ## Examples ### cURL ```bash curl -X POST 'https://cheese.example.com/v2/store/order' \ -H 'Content-Type: application/json' \ -d '{ "items": [ { "cheeseId": 42, "quantity": 3 }, { "cheeseId": 17, "quantity": 1 } ], "shippingAddress": { "street": "123 Cheese Lane", "city": "Cheddarville", "state": "WI", "zipCode": "53001", "country": "US" }, "notes": "Please wrap each wheel separately" }' ``` ### TypeScript ```typescript const response = await fetch('https://cheese.example.com/v2/store/order', { method: 'POST', headers: { 'Content-Type': 'application/json', }, body: JSON.stringify({ "items": [ { "cheeseId": 42, "quantity": 3 }, { "cheeseId": 17, "quantity": 1 } ], "shippingAddress": { "street": "123 Cheese Lane", "city": "Cheddarville", "state": "WI", "zipCode": "53001", "country": "US" }, "notes": "Please wrap each wheel separately" }), }); const data: Record = await response.json(); ``` ### Python ```python import requests payload = { "items": [ { "cheeseId": 42, "quantity": 3 }, { "cheeseId": 17, "quantity": 1 } ], "shippingAddress": { "street": "123 Cheese Lane", "city": "Cheddarville", "state": "WI", "zipCode": "53001", "country": "US" }, "notes": "Please wrap each wheel separately" } response = requests.post('https://cheese.example.com/v2/store/order', json=payload) data = response.json() ``` ### Go ```go package main import ( "fmt" "io" "net/http" "strings" ) func main() { body := strings.NewReader(`{ "items": [ { "cheeseId": 42, "quantity": 3 }, { "cheeseId": 17, "quantity": 1 } ], "shippingAddress": { "street": "123 Cheese Lane", "city": "Cheddarville", "state": "WI", "zipCode": "53001", "country": "US" }, "notes": "Please wrap each wheel separately" }`) req, _ := http.NewRequest("POST", "https://cheese.example.com/v2/store/order", body) req.Header.Set("Content-Type", "application/json") resp, _ := http.DefaultClient.Do(req) defer resp.Body.Close() data, _ := io.ReadAll(resp.Body) fmt.Println(string(data)) } ``` ### Rust ```rust use reqwest; #[tokio::main] async fn main() -> Result<(), reqwest::Error> { let client = reqwest::Client::new(); let body = serde_json::json!({ "items": [ { "cheeseId": 42, "quantity": 3 }, { "cheeseId": 17, "quantity": 1 } ], "shippingAddress": { "street": "123 Cheese Lane", "city": "Cheddarville", "state": "WI", "zipCode": "53001", "country": "US" }, "notes": "Please wrap each wheel separately" }); let response = client.post("https://cheese.example.com/v2/store/order") .json(&body) .send() .await? .text() .await?; println!("{}", response); Ok(()) } ``` ## GET /store/order/{orderId} Get order by ID Retrieve details of a specific order. For testing, use order IDs between 1 and 10. Authentication (security requirement alternatives): ```json [ { "api_key": [] } ] ``` - api_key: apiKey, header X-API-Key. API key authentication. Include your API key in the `X-API-Key` header. This is an example scheme. Supply credentials from your own service when adapting this contract. Parameters: - `orderId` (path, integer, int64, required) - ID of the order Type: integer, int64 minimum: 1 Responses: - 200: Order details Content type: application/json Type: object Schema: [Order](https://sourcey.com/examples/docs-showcase/reference/api/schemas/order-6be090825c.md) Example: ```json { "id": 1001, "items": [ { "cheeseId": 42, "cheeseName": "Gorgonzola", "quantity": 3, "pricePerKg": 28.5 }, { "cheeseId": 17, "cheeseName": "Brie", "quantity": 1, "pricePerKg": 22 } ], "shippingAddress": { "street": "123 Cheese Lane", "city": "Cheddarville", "state": "WI", "zipCode": "53001", "country": "US" }, "status": "placed", "notes": "Please wrap each wheel separately", "total": 114.5, "shipDate": null, "createdAt": "2026-03-10T14:30:00Z", "updatedAt": "2026-03-10T14:30:00Z" } ``` - `id` (optional) Type: integer, int64 Example: ```json 1001 ``` - `items` (optional) Type: array Items: Reference: [OrderItem](https://sourcey.com/examples/docs-showcase/reference/api/schemas/orderitem-6b56cf7850.md); Type: object - `shippingAddress` (optional) Reference: [Address](https://sourcey.com/examples/docs-showcase/reference/api/schemas/address-56ef8f2095.md); Type: object - `status` (optional) Type: string Order lifecycle status enum: ["placed","approved","shipped","delivered","cancelled"] Example: ```json "placed" ``` - `notes` (optional) Type: string; nullable Special instructions for the order - `total` (optional) Type: number, float Order total in USD Example: ```json 114.5 ``` - `shipDate` (optional) Type: string, date-time; nullable Estimated ship date (null if not yet scheduled) - `createdAt` (optional) Type: string, date-time - `updatedAt` (optional) Type: string, date-time - 404: The requested resource was not found Content type: application/json Type: object Schema: [Error](https://sourcey.com/examples/docs-showcase/reference/api/schemas/error-54a0e8c17e.md) - `code` (required) Type: integer, int32 Example: ```json 404 ``` - `type` (optional) Type: string Example: ```json "Not found" ``` - `message` (required) Type: string Example: ```json "Your cheese has already been eaten" ``` ```json { "code": 404, "type": "Not found", "message": "Your cheese has already been eaten" } ``` ## Examples ### cURL ```bash curl -X GET 'https://cheese.example.com/v2/store/order/{orderId}' ``` ### TypeScript ```typescript const response = await fetch('https://cheese.example.com/v2/store/order/{orderId}', { method: 'GET', }); const data: Record = await response.json(); ``` ### Python ```python import requests response = requests.get('https://cheese.example.com/v2/store/order/{orderId}') data = response.json() ``` ### Go ```go package main import ( "fmt" "io" "net/http" ) func main() { req, _ := http.NewRequest("GET", "https://cheese.example.com/v2/store/order/{orderId}", nil) resp, _ := http.DefaultClient.Do(req) defer resp.Body.Close() data, _ := io.ReadAll(resp.Body) fmt.Println(string(data)) } ``` ### Rust ```rust use reqwest; #[tokio::main] async fn main() -> Result<(), reqwest::Error> { let client = reqwest::Client::new(); let response = client.get("https://cheese.example.com/v2/store/order/{orderId}") .send() .await? .text() .await?; println!("{}", response); Ok(()) } ``` ## DELETE /store/order/{orderId} Cancel an order Cancel a pending order. Orders that have already been shipped cannot be cancelled. Authentication (security requirement alternatives): ```json [ { "cheesy_oauth": [ "write:orders" ] } ] ``` - cheesy_oauth: oauth2. OAuth2 authentication for full API access; scopes: write:orders Parameters: - `orderId` (path, integer, int64, required) - ID of the order Type: integer, int64 minimum: 1 Responses: - 204: Order cancelled successfully - 404: The requested resource was not found Content type: application/json Type: object Schema: [Error](https://sourcey.com/examples/docs-showcase/reference/api/schemas/error-54a0e8c17e.md) - `code` (required) Type: integer, int32 Example: ```json 404 ``` - `type` (optional) Type: string Example: ```json "Not found" ``` - `message` (required) Type: string Example: ```json "Your cheese has already been eaten" ``` ```json { "code": 404, "type": "Not found", "message": "Your cheese has already been eaten" } ``` - 409: Order has already been shipped Content type: application/json Type: object Schema: [Error](https://sourcey.com/examples/docs-showcase/reference/api/schemas/error-54a0e8c17e.md) - `code` (required) Type: integer, int32 Example: ```json 404 ``` - `type` (optional) Type: string Example: ```json "Not found" ``` - `message` (required) Type: string Example: ```json "Your cheese has already been eaten" ``` ## Examples ### cURL ```bash curl -X DELETE 'https://cheese.example.com/v2/store/order/{orderId}' ``` ### TypeScript ```typescript const response = await fetch('https://cheese.example.com/v2/store/order/{orderId}', { method: 'DELETE', }); const data: Record = await response.json(); ``` ### Python ```python import requests response = requests.delete('https://cheese.example.com/v2/store/order/{orderId}') data = response.json() ``` ### Go ```go package main import ( "fmt" "io" "net/http" ) func main() { req, _ := http.NewRequest("DELETE", "https://cheese.example.com/v2/store/order/{orderId}", nil) resp, _ := http.DefaultClient.Do(req) defer resp.Body.Close() data, _ := io.ReadAll(resp.Body) fmt.Println(string(data)) } ``` ### Rust ```rust use reqwest; #[tokio::main] async fn main() -> Result<(), reqwest::Error> { let client = reqwest::Client::new(); let response = client.delete("https://cheese.example.com/v2/store/order/{orderId}") .send() .await? .text() .await?; println!("{}", response); Ok(()) } ``` ## POST /customer Create a customer account Register a new customer account. The username and email must be unique. Authentication: no security requirement declared for this operation. Request body: application/json (required) Customer registration details Type: object Schema: [CustomerInput](https://sourcey.com/examples/docs-showcase/reference/api/schemas/customerinput-63c834e0ae.md) - `username` (required) Type: string minLength: 3 maxLength: 30 pattern: "^[a-zA-Z0-9_-]+$" - `firstName` (optional) Type: string maxLength: 50 - `lastName` (optional) Type: string maxLength: 50 - `email` (required) Type: string, email - `password` (required) Type: string, password minLength: 8 maxLength: 128 - `phone` (optional) Type: string; nullable ```json { "username": "gordo", "firstName": "Alotta", "lastName": "Cheese", "email": "love@cheese.com", "password": "secret123!", "phone": "+3344556677" } ``` Responses: - 201: Customer account created Content type: application/json Type: object Schema: [Customer](https://sourcey.com/examples/docs-showcase/reference/api/schemas/customer-bf3763383a.md) - `id` (optional) Type: integer, int64 Example: ```json 1 ``` - `username` (optional) Type: string Example: ```json "gordo" ``` - `firstName` (optional) Type: string Customer first name Example: ```json "Alotta" ``` - `lastName` (optional) Type: string Customer last name Example: ```json "Cheese" ``` - `email` (optional) Type: string, email Example: ```json "love@cheese.com" ``` - `phone` (optional) Type: string; nullable Example: ```json "+3344556677" ``` - `customerStatus` (optional) Type: string Customer tier based on purchase volume enum: ["bronze","silver","gold","platinum"] Example: ```json "gold" ``` - `favouriteCheese` (optional) Type: unknown The customer's favourite cheese (by reference or by name) oneOf: Reference: [Cheese](https://sourcey.com/examples/docs-showcase/reference/api/schemas/cheese-6e5a59d4fd.md); Type: object Type: object - `name` (required) Type: string - `createdAt` (optional) Type: string, date-time - 409: Username or email already exists Content type: application/json Type: object Schema: [Error](https://sourcey.com/examples/docs-showcase/reference/api/schemas/error-54a0e8c17e.md) - `code` (required) Type: integer, int32 Example: ```json 404 ``` - `type` (optional) Type: string Example: ```json "Not found" ``` - `message` (required) Type: string Example: ```json "Your cheese has already been eaten" ``` - 422: The request body failed validation Content type: application/json Type: object Schema: [ValidationError](https://sourcey.com/examples/docs-showcase/reference/api/schemas/validationerror-bdfaef14be.md) - `code` (optional) Type: integer, int32 Example: ```json 422 ``` - `type` (optional) Type: string Example: ```json "Validation error" ``` - `message` (optional) Type: string Example: ```json "Your cheese is not mouldy enough" ``` - `errors` (optional) Type: array Individual field validation errors Items: Type: object - `field` (optional) Type: string The field that failed validation - `message` (optional) Type: string Human-readable error message ```json { "code": 422, "type": "Validation error", "message": "Your cheese is not mouldy enough", "errors": [ { "field": "name", "message": "Name is required" }, { "field": "status", "message": "Must be one of available, pending, sold" } ] } ``` ## Examples ### cURL ```bash curl -X POST 'https://cheese.example.com/v2/customer' \ -H 'Content-Type: application/json' \ -d '{ "username": "gordo", "firstName": "Alotta", "lastName": "Cheese", "email": "love@cheese.com", "password": "secret123!", "phone": "+3344556677" }' ``` ### TypeScript ```typescript const response = await fetch('https://cheese.example.com/v2/customer', { method: 'POST', headers: { 'Content-Type': 'application/json', }, body: JSON.stringify({ "username": "gordo", "firstName": "Alotta", "lastName": "Cheese", "email": "love@cheese.com", "password": "secret123!", "phone": "+3344556677" }), }); const data: Record = await response.json(); ``` ### Python ```python import requests payload = { "username": "gordo", "firstName": "Alotta", "lastName": "Cheese", "email": "love@cheese.com", "password": "secret123!", "phone": "+3344556677" } response = requests.post('https://cheese.example.com/v2/customer', json=payload) data = response.json() ``` ### Go ```go package main import ( "fmt" "io" "net/http" "strings" ) func main() { body := strings.NewReader(`{ "username": "gordo", "firstName": "Alotta", "lastName": "Cheese", "email": "love@cheese.com", "password": "secret123!", "phone": "+3344556677" }`) req, _ := http.NewRequest("POST", "https://cheese.example.com/v2/customer", body) req.Header.Set("Content-Type", "application/json") resp, _ := http.DefaultClient.Do(req) defer resp.Body.Close() data, _ := io.ReadAll(resp.Body) fmt.Println(string(data)) } ``` ### Rust ```rust use reqwest; #[tokio::main] async fn main() -> Result<(), reqwest::Error> { let client = reqwest::Client::new(); let body = serde_json::json!({ "username": "gordo", "firstName": "Alotta", "lastName": "Cheese", "email": "love@cheese.com", "password": "secret123!", "phone": "+3344556677" }); let response = client.post("https://cheese.example.com/v2/customer") .json(&body) .send() .await? .text() .await?; println!("{}", response); Ok(()) } ``` ## POST /customer/createMultiple Create multiple customers Create a batch of customer accounts from an array. Each customer is validated independently - partial success is possible. Returns the created customers and any validation errors: ```json { "created": [...], "errors": [ { "index": 2, "message": "Email already exists" } ] } ``` Authentication: no security requirement declared for this operation. Request body: application/json (required) Array of customer objects to create Type: array minItems: 1 maxItems: 100 Items: Reference: [CustomerInput](https://sourcey.com/examples/docs-showcase/reference/api/schemas/customerinput-63c834e0ae.md); Type: object Responses: - 200: Batch creation result Content type: application/json Type: object - `created` (optional) Type: array Items: Reference: [Customer](https://sourcey.com/examples/docs-showcase/reference/api/schemas/customer-bf3763383a.md); Type: object - `errors` (optional) Type: array Items: Type: object - `index` (optional) Type: integer - `message` (optional) Type: string - 422: The request body failed validation Content type: application/json Type: object Schema: [ValidationError](https://sourcey.com/examples/docs-showcase/reference/api/schemas/validationerror-bdfaef14be.md) - `code` (optional) Type: integer, int32 Example: ```json 422 ``` - `type` (optional) Type: string Example: ```json "Validation error" ``` - `message` (optional) Type: string Example: ```json "Your cheese is not mouldy enough" ``` - `errors` (optional) Type: array Individual field validation errors Items: Type: object - `field` (optional) Type: string The field that failed validation - `message` (optional) Type: string Human-readable error message ```json { "code": 422, "type": "Validation error", "message": "Your cheese is not mouldy enough", "errors": [ { "field": "name", "message": "Name is required" }, { "field": "status", "message": "Must be one of available, pending, sold" } ] } ``` ## Examples ### cURL ```bash curl -X POST 'https://cheese.example.com/v2/customer/createMultiple' \ -H 'Content-Type: application/json' \ -d '[ { "username": "string", "firstName": "string", "lastName": "string", "email": "user@example.com", "password": "********", "phone": "string" } ]' ``` ### TypeScript ```typescript const response = await fetch('https://cheese.example.com/v2/customer/createMultiple', { method: 'POST', headers: { 'Content-Type': 'application/json', }, body: JSON.stringify([ { "username": "string", "firstName": "string", "lastName": "string", "email": "user@example.com", "password": "********", "phone": "string" } ]), }); const data: Record = await response.json(); ``` ### Python ```python import requests payload = [ { "username": "string", "firstName": "string", "lastName": "string", "email": "user@example.com", "password": "********", "phone": "string" } ] response = requests.post('https://cheese.example.com/v2/customer/createMultiple', json=payload) data = response.json() ``` ### Go ```go package main import ( "fmt" "io" "net/http" "strings" ) func main() { body := strings.NewReader(`[ { "username": "string", "firstName": "string", "lastName": "string", "email": "user@example.com", "password": "********", "phone": "string" } ]`) req, _ := http.NewRequest("POST", "https://cheese.example.com/v2/customer/createMultiple", body) req.Header.Set("Content-Type", "application/json") resp, _ := http.DefaultClient.Do(req) defer resp.Body.Close() data, _ := io.ReadAll(resp.Body) fmt.Println(string(data)) } ``` ### Rust ```rust use reqwest; #[tokio::main] async fn main() -> Result<(), reqwest::Error> { let client = reqwest::Client::new(); let body = serde_json::json!([ { "username": "string", "firstName": "string", "lastName": "string", "email": "user@example.com", "password": "********", "phone": "string" } ]); let response = client.post("https://cheese.example.com/v2/customer/createMultiple") .json(&body) .send() .await? .text() .await?; println!("{}", response); Ok(()) } ``` ## POST /customer/login Customer login Authenticate a customer and receive a session token. The token expires after 24 hours. Authentication: no security requirement declared for this operation. Request body: application/json (required) Type: object - `username` (required) Type: string The customer's username - `password` (required) Type: string, password The customer's password Responses: - 200: Login successful Content type: application/json Type: object - `token` (optional) Type: string JWT session token - `expiresAt` (optional) Type: string, date-time Token expiration time (UTC) - 401: Invalid username or password Content type: application/json Type: object Schema: [Error](https://sourcey.com/examples/docs-showcase/reference/api/schemas/error-54a0e8c17e.md) - `code` (required) Type: integer, int32 Example: ```json 404 ``` - `type` (optional) Type: string Example: ```json "Not found" ``` - `message` (required) Type: string Example: ```json "Your cheese has already been eaten" ``` ## Examples ### cURL ```bash curl -X POST 'https://cheese.example.com/v2/customer/login' \ -H 'Content-Type: application/json' \ -d '{ "username": "string", "password": "********" }' ``` ### TypeScript ```typescript const response = await fetch('https://cheese.example.com/v2/customer/login', { method: 'POST', headers: { 'Content-Type': 'application/json', }, body: JSON.stringify({ "username": "string", "password": "********" }), }); const data: Record = await response.json(); ``` ### Python ```python import requests payload = { "username": "string", "password": "********" } response = requests.post('https://cheese.example.com/v2/customer/login', json=payload) data = response.json() ``` ### Go ```go package main import ( "fmt" "io" "net/http" "strings" ) func main() { body := strings.NewReader(`{ "username": "string", "password": "********" }`) req, _ := http.NewRequest("POST", "https://cheese.example.com/v2/customer/login", body) req.Header.Set("Content-Type", "application/json") resp, _ := http.DefaultClient.Do(req) defer resp.Body.Close() data, _ := io.ReadAll(resp.Body) fmt.Println(string(data)) } ``` ### Rust ```rust use reqwest; #[tokio::main] async fn main() -> Result<(), reqwest::Error> { let client = reqwest::Client::new(); let body = serde_json::json!({ "username": "string", "password": "********" }); let response = client.post("https://cheese.example.com/v2/customer/login") .json(&body) .send() .await? .text() .await?; println!("{}", response); Ok(()) } ``` ## GET /customer/logout Customer logout End the current customer session and invalidate the session token. Authentication (security requirement alternatives): ```json [ { "bearer_auth": [] } ] ``` - bearer_auth: http (bearer). JWT token obtained from the `/customer/login` endpoint Responses: - 204: Logout successful ## Examples ### cURL ```bash curl -X GET 'https://cheese.example.com/v2/customer/logout' ``` ### TypeScript ```typescript const response = await fetch('https://cheese.example.com/v2/customer/logout', { method: 'GET', }); const data: Record = await response.json(); ``` ### Python ```python import requests response = requests.get('https://cheese.example.com/v2/customer/logout') data = response.json() ``` ### Go ```go package main import ( "fmt" "io" "net/http" ) func main() { req, _ := http.NewRequest("GET", "https://cheese.example.com/v2/customer/logout", nil) resp, _ := http.DefaultClient.Do(req) defer resp.Body.Close() data, _ := io.ReadAll(resp.Body) fmt.Println(string(data)) } ``` ### Rust ```rust use reqwest; #[tokio::main] async fn main() -> Result<(), reqwest::Error> { let client = reqwest::Client::new(); let response = client.get("https://cheese.example.com/v2/customer/logout") .send() .await? .text() .await?; println!("{}", response); Ok(()) } ``` ## GET /customer/{username} Get customer by username Retrieve a customer's profile by their username. Authentication (security requirement alternatives): ```json [ { "api_key": [] }, { "bearer_auth": [] } ] ``` - api_key: apiKey, header X-API-Key. API key authentication. Include your API key in the `X-API-Key` header. This is an example scheme. Supply credentials from your own service when adapting this contract. - bearer_auth: http (bearer). JWT token obtained from the `/customer/login` endpoint Parameters: - `username` (path, string, required) - The customer's username Type: string minLength: 3 maxLength: 30 pattern: "^[a-zA-Z0-9_-]+$" Responses: - 200: Customer profile Content type: application/json Type: object Schema: [Customer](https://sourcey.com/examples/docs-showcase/reference/api/schemas/customer-bf3763383a.md) - `id` (optional) Type: integer, int64 Example: ```json 1 ``` - `username` (optional) Type: string Example: ```json "gordo" ``` - `firstName` (optional) Type: string Customer first name Example: ```json "Alotta" ``` - `lastName` (optional) Type: string Customer last name Example: ```json "Cheese" ``` - `email` (optional) Type: string, email Example: ```json "love@cheese.com" ``` - `phone` (optional) Type: string; nullable Example: ```json "+3344556677" ``` - `customerStatus` (optional) Type: string Customer tier based on purchase volume enum: ["bronze","silver","gold","platinum"] Example: ```json "gold" ``` - `favouriteCheese` (optional) Type: unknown The customer's favourite cheese (by reference or by name) oneOf: Reference: [Cheese](https://sourcey.com/examples/docs-showcase/reference/api/schemas/cheese-6e5a59d4fd.md); Type: object Type: object - `name` (required) Type: string - `createdAt` (optional) Type: string, date-time - 404: The requested resource was not found Content type: application/json Type: object Schema: [Error](https://sourcey.com/examples/docs-showcase/reference/api/schemas/error-54a0e8c17e.md) - `code` (required) Type: integer, int32 Example: ```json 404 ``` - `type` (optional) Type: string Example: ```json "Not found" ``` - `message` (required) Type: string Example: ```json "Your cheese has already been eaten" ``` ```json { "code": 404, "type": "Not found", "message": "Your cheese has already been eaten" } ``` ## Examples ### cURL ```bash curl -X GET 'https://cheese.example.com/v2/customer/{username}' ``` ### TypeScript ```typescript const response = await fetch('https://cheese.example.com/v2/customer/{username}', { method: 'GET', }); const data: Record = await response.json(); ``` ### Python ```python import requests response = requests.get('https://cheese.example.com/v2/customer/{username}') data = response.json() ``` ### Go ```go package main import ( "fmt" "io" "net/http" ) func main() { req, _ := http.NewRequest("GET", "https://cheese.example.com/v2/customer/{username}", nil) resp, _ := http.DefaultClient.Do(req) defer resp.Body.Close() data, _ := io.ReadAll(resp.Body) fmt.Println(string(data)) } ``` ### Rust ```rust use reqwest; #[tokio::main] async fn main() -> Result<(), reqwest::Error> { let client = reqwest::Client::new(); let response = client.get("https://cheese.example.com/v2/customer/{username}") .send() .await? .text() .await?; println!("{}", response); Ok(()) } ``` ## PUT /customer/{username} Update customer profile Update a customer's profile. Can only be performed by the authenticated customer. Authentication (security requirement alternatives): ```json [ { "bearer_auth": [] } ] ``` - bearer_auth: http (bearer). JWT token obtained from the `/customer/login` endpoint Parameters: - `username` (path, string, required) - The customer's username Type: string minLength: 3 maxLength: 30 pattern: "^[a-zA-Z0-9_-]+$" Request body: application/json (required) Updated customer fields Type: object Schema: [CustomerInput](https://sourcey.com/examples/docs-showcase/reference/api/schemas/customerinput-63c834e0ae.md) - `username` (required) Type: string minLength: 3 maxLength: 30 pattern: "^[a-zA-Z0-9_-]+$" - `firstName` (optional) Type: string maxLength: 50 - `lastName` (optional) Type: string maxLength: 50 - `email` (required) Type: string, email - `password` (required) Type: string, password minLength: 8 maxLength: 128 - `phone` (optional) Type: string; nullable Responses: - 200: Customer updated Content type: application/json Type: object Schema: [Customer](https://sourcey.com/examples/docs-showcase/reference/api/schemas/customer-bf3763383a.md) - `id` (optional) Type: integer, int64 Example: ```json 1 ``` - `username` (optional) Type: string Example: ```json "gordo" ``` - `firstName` (optional) Type: string Customer first name Example: ```json "Alotta" ``` - `lastName` (optional) Type: string Customer last name Example: ```json "Cheese" ``` - `email` (optional) Type: string, email Example: ```json "love@cheese.com" ``` - `phone` (optional) Type: string; nullable Example: ```json "+3344556677" ``` - `customerStatus` (optional) Type: string Customer tier based on purchase volume enum: ["bronze","silver","gold","platinum"] Example: ```json "gold" ``` - `favouriteCheese` (optional) Type: unknown The customer's favourite cheese (by reference or by name) oneOf: Reference: [Cheese](https://sourcey.com/examples/docs-showcase/reference/api/schemas/cheese-6e5a59d4fd.md); Type: object Type: object - `name` (required) Type: string - `createdAt` (optional) Type: string, date-time - 404: The requested resource was not found Content type: application/json Type: object Schema: [Error](https://sourcey.com/examples/docs-showcase/reference/api/schemas/error-54a0e8c17e.md) - `code` (required) Type: integer, int32 Example: ```json 404 ``` - `type` (optional) Type: string Example: ```json "Not found" ``` - `message` (required) Type: string Example: ```json "Your cheese has already been eaten" ``` ```json { "code": 404, "type": "Not found", "message": "Your cheese has already been eaten" } ``` - 422: The request body failed validation Content type: application/json Type: object Schema: [ValidationError](https://sourcey.com/examples/docs-showcase/reference/api/schemas/validationerror-bdfaef14be.md) - `code` (optional) Type: integer, int32 Example: ```json 422 ``` - `type` (optional) Type: string Example: ```json "Validation error" ``` - `message` (optional) Type: string Example: ```json "Your cheese is not mouldy enough" ``` - `errors` (optional) Type: array Individual field validation errors Items: Type: object - `field` (optional) Type: string The field that failed validation - `message` (optional) Type: string Human-readable error message ```json { "code": 422, "type": "Validation error", "message": "Your cheese is not mouldy enough", "errors": [ { "field": "name", "message": "Name is required" }, { "field": "status", "message": "Must be one of available, pending, sold" } ] } ``` ## Examples ### cURL ```bash curl -X PUT 'https://cheese.example.com/v2/customer/{username}' \ -H 'Content-Type: application/json' \ -d '{ "username": "string", "firstName": "string", "lastName": "string", "email": "user@example.com", "password": "********", "phone": "string" }' ``` ### TypeScript ```typescript const response = await fetch('https://cheese.example.com/v2/customer/{username}', { method: 'PUT', headers: { 'Content-Type': 'application/json', }, body: JSON.stringify({ "username": "string", "firstName": "string", "lastName": "string", "email": "user@example.com", "password": "********", "phone": "string" }), }); const data: Record = await response.json(); ``` ### Python ```python import requests payload = { "username": "string", "firstName": "string", "lastName": "string", "email": "user@example.com", "password": "********", "phone": "string" } response = requests.put('https://cheese.example.com/v2/customer/{username}', json=payload) data = response.json() ``` ### Go ```go package main import ( "fmt" "io" "net/http" "strings" ) func main() { body := strings.NewReader(`{ "username": "string", "firstName": "string", "lastName": "string", "email": "user@example.com", "password": "********", "phone": "string" }`) req, _ := http.NewRequest("PUT", "https://cheese.example.com/v2/customer/{username}", body) req.Header.Set("Content-Type", "application/json") resp, _ := http.DefaultClient.Do(req) defer resp.Body.Close() data, _ := io.ReadAll(resp.Body) fmt.Println(string(data)) } ``` ### Rust ```rust use reqwest; #[tokio::main] async fn main() -> Result<(), reqwest::Error> { let client = reqwest::Client::new(); let body = serde_json::json!({ "username": "string", "firstName": "string", "lastName": "string", "email": "user@example.com", "password": "********", "phone": "string" }); let response = client.put("https://cheese.example.com/v2/customer/{username}") .json(&body) .send() .await? .text() .await?; println!("{}", response); Ok(()) } ``` ## DELETE /customer/{username} Delete customer account Permanently delete a customer account and all associated data. This action cannot be undone. Authentication (security requirement alternatives): ```json [ { "bearer_auth": [] } ] ``` - bearer_auth: http (bearer). JWT token obtained from the `/customer/login` endpoint Parameters: - `username` (path, string, required) - The customer's username Type: string minLength: 3 maxLength: 30 pattern: "^[a-zA-Z0-9_-]+$" Responses: - 204: Customer deleted - 404: The requested resource was not found Content type: application/json Type: object Schema: [Error](https://sourcey.com/examples/docs-showcase/reference/api/schemas/error-54a0e8c17e.md) - `code` (required) Type: integer, int32 Example: ```json 404 ``` - `type` (optional) Type: string Example: ```json "Not found" ``` - `message` (required) Type: string Example: ```json "Your cheese has already been eaten" ``` ```json { "code": 404, "type": "Not found", "message": "Your cheese has already been eaten" } ``` ## Examples ### cURL ```bash curl -X DELETE 'https://cheese.example.com/v2/customer/{username}' ``` ### TypeScript ```typescript const response = await fetch('https://cheese.example.com/v2/customer/{username}', { method: 'DELETE', }); const data: Record = await response.json(); ``` ### Python ```python import requests response = requests.delete('https://cheese.example.com/v2/customer/{username}') data = response.json() ``` ### Go ```go package main import ( "fmt" "io" "net/http" ) func main() { req, _ := http.NewRequest("DELETE", "https://cheese.example.com/v2/customer/{username}", nil) resp, _ := http.DefaultClient.Do(req) defer resp.Body.Close() data, _ := io.ReadAll(resp.Body) fmt.Println(string(data)) } ``` ### Rust ```rust use reqwest; #[tokio::main] async fn main() -> Result<(), reqwest::Error> { let client = reqwest::Client::new(); let response = client.delete("https://cheese.example.com/v2/customer/{username}") .send() .await? .text() .await?; println!("{}", response); Ok(()) } ``` ## Cheese Type: object Schema: [Cheese](https://sourcey.com/examples/docs-showcase/reference/api/schemas/cheese-6e5a59d4fd.md) - `id` (required) Type: integer, int64 Unique identifier Example: ```json 42 ``` - `name` (required) Type: string Name of the cheese minLength: 1 maxLength: 100 Example: ```json "Gorgonzola" ``` - `category` (optional) Reference: [Category](https://sourcey.com/examples/docs-showcase/reference/api/schemas/category-292c06f004.md); Type: object - `photoUrls` (optional) Type: array URLs of cheese photos Example: ```json [ "https://wannabechef.com/gorgonzola.jpg" ] ``` Items: Type: string, uri - `tags` (optional) Type: array Classification tags Items: Reference: [Tag](https://sourcey.com/examples/docs-showcase/reference/api/schemas/tag-1503916a2a.md); Type: object - `status` (required) Type: string Availability status in the store enum: ["available","pending","sold"] Example: ```json "available" ``` - `origin` (optional) Type: string; nullable Country of origin (null if unknown) Example: ```json "Italy" ``` - `pricePerKg` (optional) Type: number, float Price per kilogram in USD minimum: 0 exclusiveMinimum: true Example: ```json 28.5 ``` - `ageMonths` (optional) Type: integer Aging period in months minimum: 0 maximum: 120 Example: ```json 12 ``` - `organic` (optional) Type: boolean Whether the cheese is certified organic default: false - `createdAt` (optional) Type: string, date-time When the cheese was added to the store - `updatedAt` (optional) Type: string, date-time When the cheese was last updated ## CheeseInput Type: object Schema: [CheeseInput](https://sourcey.com/examples/docs-showcase/reference/api/schemas/cheeseinput-4479830925.md) - `name` (required) Type: string minLength: 1 maxLength: 100 - `category` (optional) Type: object - `name` (optional) Type: string - `photoUrls` (optional) Type: array Items: Type: string, uri - `tags` (optional) Type: array Items: Type: object - `name` (optional) Type: string - `status` (optional) Type: string default: "available" enum: ["available","pending","sold"] - `origin` (optional) Type: string; nullable - `pricePerKg` (optional) Type: number, float minimum: 0 exclusiveMinimum: true - `ageMonths` (optional) Type: integer minimum: 0 maximum: 120 - `organic` (optional) Type: boolean default: false ## CheeseList Type: object Paginated list of cheeses Schema: [CheeseList](https://sourcey.com/examples/docs-showcase/reference/api/schemas/cheeselist-06d8bd48db.md) - `items` (optional) Type: array Items: Reference: [Cheese](https://sourcey.com/examples/docs-showcase/reference/api/schemas/cheese-6e5a59d4fd.md); Type: object - `nextCursor` (optional) Type: string; nullable Cursor for the next page (null if no more results) - `hasMore` (optional) Type: boolean Whether there are more results - `total` (optional) Type: integer Total number of matching cheeses ## Category Type: object Schema: [Category](https://sourcey.com/examples/docs-showcase/reference/api/schemas/category-292c06f004.md) - `id` (optional) Type: integer, int64 Example: ```json 1 ``` - `name` (optional) Type: string Example: ```json "Italian Cheese" ``` ## Tag Type: object Schema: [Tag](https://sourcey.com/examples/docs-showcase/reference/api/schemas/tag-1503916a2a.md) - `id` (optional) Type: integer, int64 Example: ```json 1 ``` - `name` (optional) Type: string Example: ```json "blue" ``` ## Order Type: object Schema: [Order](https://sourcey.com/examples/docs-showcase/reference/api/schemas/order-6be090825c.md) Example: ```json { "id": 1001, "items": [ { "cheeseId": 42, "cheeseName": "Gorgonzola", "quantity": 3, "pricePerKg": 28.5 }, { "cheeseId": 17, "cheeseName": "Brie", "quantity": 1, "pricePerKg": 22 } ], "shippingAddress": { "street": "123 Cheese Lane", "city": "Cheddarville", "state": "WI", "zipCode": "53001", "country": "US" }, "status": "placed", "notes": "Please wrap each wheel separately", "total": 114.5, "shipDate": null, "createdAt": "2026-03-10T14:30:00Z", "updatedAt": "2026-03-10T14:30:00Z" } ``` - `id` (optional) Type: integer, int64 Example: ```json 1001 ``` - `items` (optional) Type: array Items: Reference: [OrderItem](https://sourcey.com/examples/docs-showcase/reference/api/schemas/orderitem-6b56cf7850.md); Type: object - `shippingAddress` (optional) Reference: [Address](https://sourcey.com/examples/docs-showcase/reference/api/schemas/address-56ef8f2095.md); Type: object - `status` (optional) Type: string Order lifecycle status enum: ["placed","approved","shipped","delivered","cancelled"] Example: ```json "placed" ``` - `notes` (optional) Type: string; nullable Special instructions for the order - `total` (optional) Type: number, float Order total in USD Example: ```json 114.5 ``` - `shipDate` (optional) Type: string, date-time; nullable Estimated ship date (null if not yet scheduled) - `createdAt` (optional) Type: string, date-time - `updatedAt` (optional) Type: string, date-time ## OrderInput Type: object Schema: [OrderInput](https://sourcey.com/examples/docs-showcase/reference/api/schemas/orderinput-fdf8fed0b2.md) - `items` (required) Type: array minItems: 1 maxItems: 50 Items: Type: object - `cheeseId` (required) Type: integer, int64 - `quantity` (required) Type: integer minimum: 1 maximum: 100 - `shippingAddress` (required) Reference: [Address](https://sourcey.com/examples/docs-showcase/reference/api/schemas/address-56ef8f2095.md); Type: object - `notes` (optional) Type: string; nullable maxLength: 500 ## OrderItem Type: object Schema: [OrderItem](https://sourcey.com/examples/docs-showcase/reference/api/schemas/orderitem-6b56cf7850.md) - `cheeseId` (optional) Type: integer, int64 - `cheeseName` (optional) Type: string - `quantity` (optional) Type: integer minimum: 1 - `pricePerKg` (optional) Type: number, float ## Address Type: object Schema: [Address](https://sourcey.com/examples/docs-showcase/reference/api/schemas/address-56ef8f2095.md) - `street` (required) Type: string Example: ```json "123 Cheese Lane" ``` - `city` (required) Type: string Example: ```json "Cheddarville" ``` - `state` (optional) Type: string; nullable Example: ```json "WI" ``` - `zipCode` (optional) Type: string pattern: "^\\d{5}(-\\d{4})?$" Example: ```json "53001" ``` - `country` (required) Type: string ISO 3166-1 alpha-2 country code minLength: 2 maxLength: 2 Example: ```json "US" ``` ## Customer Type: object Schema: [Customer](https://sourcey.com/examples/docs-showcase/reference/api/schemas/customer-bf3763383a.md) - `id` (optional) Type: integer, int64 Example: ```json 1 ``` - `username` (optional) Type: string Example: ```json "gordo" ``` - `firstName` (optional) Type: string Customer first name Example: ```json "Alotta" ``` - `lastName` (optional) Type: string Customer last name Example: ```json "Cheese" ``` - `email` (optional) Type: string, email Example: ```json "love@cheese.com" ``` - `phone` (optional) Type: string; nullable Example: ```json "+3344556677" ``` - `customerStatus` (optional) Type: string Customer tier based on purchase volume enum: ["bronze","silver","gold","platinum"] Example: ```json "gold" ``` - `favouriteCheese` (optional) Type: unknown The customer's favourite cheese (by reference or by name) oneOf: Reference: [Cheese](https://sourcey.com/examples/docs-showcase/reference/api/schemas/cheese-6e5a59d4fd.md); Type: object Type: object - `name` (required) Type: string - `createdAt` (optional) Type: string, date-time ## CustomerInput Type: object Schema: [CustomerInput](https://sourcey.com/examples/docs-showcase/reference/api/schemas/customerinput-63c834e0ae.md) - `username` (required) Type: string minLength: 3 maxLength: 30 pattern: "^[a-zA-Z0-9_-]+$" - `firstName` (optional) Type: string maxLength: 50 - `lastName` (optional) Type: string maxLength: 50 - `email` (required) Type: string, email - `password` (required) Type: string, password minLength: 8 maxLength: 128 - `phone` (optional) Type: string; nullable ## Error Type: object Schema: [Error](https://sourcey.com/examples/docs-showcase/reference/api/schemas/error-54a0e8c17e.md) - `code` (required) Type: integer, int32 Example: ```json 404 ``` - `type` (optional) Type: string Example: ```json "Not found" ``` - `message` (required) Type: string Example: ```json "Your cheese has already been eaten" ``` ## ValidationError Type: object Schema: [ValidationError](https://sourcey.com/examples/docs-showcase/reference/api/schemas/validationerror-bdfaef14be.md) - `code` (optional) Type: integer, int32 Example: ```json 422 ``` - `type` (optional) Type: string Example: ```json "Validation error" ``` - `message` (optional) Type: string Example: ```json "Your cheese is not mouldy enough" ``` - `errors` (optional) Type: array Individual field validation errors Items: Type: object - `field` (optional) Type: string The field that failed validation - `message` (optional) Type: string Human-readable error message