Cheese Store

v2.0.0

Base URLs

https://cheese.example.com/v2Example production URL (not a live service)

https://sandbox.cheese.example.com/v2Example sandbox URL (not a live service)

http://localhost:3000/v2Example local development URL

This is a fictional API contract used to demonstrate documentation generated by 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. 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:

{
  "items": [...],
  "nextCursor": "eyJpZCI6NDJ9",
  "hasMore": true
}

Authentication

api_keyapiKey

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.

API Key: X-API-Key in header

cheesy_oauthoauth2

OAuth2 authentication for full API access

implicit

Authorization URL: https://cheese.example.com/oauth/authorize

Scopes

read:cheeses- Read cheese data
write:cheeses- Create and update cheeses
read:orders- View order history
write:orders- Place and manage orders

authorizationCode

Authorization URL: https://cheese.example.com/oauth/authorize
Token URL: https://cheese.example.com/oauth/token

Scopes

read:cheeses- Read cheese data
write:cheeses- Create and update cheeses
read:orders- View order history
write:orders- Place and manage orders

bearer_authhttp

JWT token obtained from the /customer/login endpoint

Scheme: bearer (JWT)

Cheese

Cheese endpoints provide access to information and operations relating to the cheeses available in the store.

Cheeses can be filtered by status, tags, and category. Each cheese has a unique ID, name, category, and availability status.

Cheese Wiki

List all cheeses

GET

https://cheese.example.com/v2/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.

List all cheeses

curl -X GET 'https://cheese.example.com/v2/cheeses?limit=20&sort=name' \
  -H 'X-API-Key: YOUR_TOKEN'

const response = await fetch('https://cheese.example.com/v2/cheeses?limit=20&sort=name', {
  method: 'GET',
  headers: {
    'X-API-Key': 'YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'https://cheese.example.com/v2/cheeses?limit=20&sort=name',
    headers={
        'X-API-Key': 'YOUR_TOKEN',
    },
)
print(response.text)

package main

import (
  "fmt"
  "io"
  "net/http"
)

func main() {
  req, _ := http.NewRequest("GET", "https://cheese.example.com/v2/cheeses?limit=20&sort=name", nil)
  req.Header.Set("X-API-Key", "YOUR_TOKEN")
  resp, _ := http.DefaultClient.Do(req)
  defer resp.Body.Close()
  data, _ := io.ReadAll(resp.Body)
  fmt.Println(string(data))
}

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?limit=20&sort=name")
        .header("X-API-Key", "YOUR_TOKEN")
        .send()
        .await?
        .text()
        .await?;
    println!("{}", response);
    Ok(())
}

{
  "items": [
    {
      "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"
    }
  ],
  "nextCursor": "string",
  "hasMore": true,
  "total": 0
}

{
  "code": 429,
  "type": "Rate limited",
  "message": "Too many requests, please try again later"
}

Parameters

cursorstringquery

Pagination cursor from a previous response

limitinteger[1, 100]20query

Maximum number of cheeses to return

statusstringavailablependingsoldquery

Filter by availability status

sortstringname-namecreatedAt-createdAtnamequery

Sort order for results

Response

200OKCheeseList

A paginated list of cheeses

Response headers

Response fields application/json

Paginated list of cheeses

itemsArray<Cheese>

Show child attributes

idinteger<int64>required

Unique identifier

Example

namestringrequired

Name of the cheese

Example

Gorgonzola

categoryCategory

Show child attributes

idinteger<int64>

Example

namestring

Example

Italian Cheese

photoUrlsArray<string>

URLs of cheese photos

Example

[
  "https://wannabechef.com/gorgonzola.jpg"
]

tagsArray<Tag>

Classification tags

Show child attributes

idinteger<int64>

Example

namestring

Example

blue

statusstringavailablependingsoldrequired

Availability status in the store

Example

available

originstring | null

Country of origin (null if unknown)

Example

Italy

pricePerKgnumber<float>> 0

Price per kilogram in USD

Example

28.5

ageMonthsinteger[0, 120]

Aging period in months

Example

organicbooleanfalse

Whether the cheese is certified organic

createdAtstring<date-time>

When the cheese was added to the store

updatedAtstring<date-time>

When the cheese was last updated

nextCursorstring | null

Cursor for the next page (null if no more results)

hasMoreboolean

Whether there are more results

totalinteger

Total number of matching cheeses

429Too Many RequestsError

Rate limit exceeded

Response headers

X-Rate-Limit-Remainingintegerheader

Remaining requests in the current window

Response fields application/json

codeinteger<int32>required

Example

typestring

Example

Not found

messagestringrequired

Example

Your cheese has already been eaten

Authorization

api_keyapiKey in header

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_oauthoauth2

OAuth2 authentication for full API access

Scopes: read:cheeses

Add a new cheese

POST

https://cheese.example.com/v2/cheeses

Add a new cheese to the store inventory. The cheese name must be unique within its category.

Add a new cheese

curl -X POST 'https://cheese.example.com/v2/cheeses' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "name": "Gorgonzola",
  "category": {
    "name": "Blue cheese"
  },
  "origin": "Italy",
  "pricePerKg": 28.5
}'

const body = `{
  "name": "Gorgonzola",
  "category": {
    "name": "Blue cheese"
  },
  "origin": "Italy",
  "pricePerKg": 28.5
}`;

const response = await fetch('https://cheese.example.com/v2/cheeses', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "name": "Gorgonzola",
  "category": {
    "name": "Blue cheese"
  },
  "origin": "Italy",
  "pricePerKg": 28.5
}'''

response = requests.post(
    'https://cheese.example.com/v2/cheeses',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

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("Authorization", "Bearer YOUR_TOKEN")
  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))
}

use reqwest;

#[tokio::main]
async fn main() -> Result<(), reqwest::Error> {
    let client = reqwest::Client::new();
    let body = r#"{
  "name": "Gorgonzola",
  "category": {
    "name": "Blue cheese"
  },
  "origin": "Italy",
  "pricePerKg": 28.5
}"#;
    let response = client.post("https://cheese.example.com/v2/cheeses")
        .body(body)
        .header("Authorization", "Bearer YOUR_TOKEN")
        .header("Content-Type", "application/json")
        .send()
        .await?
        .text()
        .await?;
    println!("{}", response);
    Ok(())
}

Request Body

{
  "name": "Gorgonzola",
  "category": {
    "name": "Blue cheese"
  },
  "origin": "Italy",
  "pricePerKg": 28.5
}

{
  "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"
}

{
  "code": 404,
  "type": "Not found",
  "message": "Your cheese has already been eaten"
}

{
  "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"
    }
  ]
}

Body

application/json

Cheese object to add to the store

namestringrequired

categoryobject

Show child attributes

namestring

photoUrlsArray<string>

tagsArray<object>

Show child attributes

namestring

statusstringavailablependingsoldavailable

originstring | null

pricePerKgnumber<float>> 0

ageMonthsinteger[0, 120]

organicbooleanfalse

Response

201CreatedCheese

Cheese created successfully

Response headers

Locationstring<uri>header

URL of the newly created cheese

Response fields application/json

idinteger<int64>required

Unique identifier

Example

namestringrequired

Name of the cheese

Example

Gorgonzola

categoryCategory

Show child attributes

idinteger<int64>

Example

namestring

Example

Italian Cheese

photoUrlsArray<string>

URLs of cheese photos

Example

[
  "https://wannabechef.com/gorgonzola.jpg"
]

tagsArray<Tag>

Classification tags

Show child attributes

idinteger<int64>

Example

namestring

Example

blue

statusstringavailablependingsoldrequired

Availability status in the store

Example

available

originstring | null

Country of origin (null if unknown)

Example

Italy

pricePerKgnumber<float>> 0

Price per kilogram in USD

Example

28.5

ageMonthsinteger[0, 120]

Aging period in months

Example

organicbooleanfalse

Whether the cheese is certified organic

createdAtstring<date-time>

When the cheese was added to the store

updatedAtstring<date-time>

When the cheese was last updated

409ConflictError

A cheese with this name already exists in the category

Response fields application/json

codeinteger<int32>required

Example

typestring

Example

Not found

messagestringrequired

Example

Your cheese has already been eaten

422Unprocessable EntityValidationError

The request body failed validation

Response fields application/json

codeinteger<int32>

Example

typestring

Example

Validation error

messagestring

Example

Your cheese is not mouldy enough

errorsArray<object>

Individual field validation errors

Show child attributes

fieldstring

The field that failed validation

messagestring

Human-readable error message

Authorization

cheesy_oauthoauth2

OAuth2 authentication for full API access

Scopes: write:cheeses

Update an existing cheese

PUT

https://cheese.example.com/v2/cheeses

Replace an existing cheese with updated data. The cheese ID in the body must match an existing cheese.

Update an existing cheese

curl -X PUT 'https://cheese.example.com/v2/cheeses' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "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 body = `{
  "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 response = await fetch('https://cheese.example.com/v2/cheeses', {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "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',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

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("Authorization", "Bearer YOUR_TOKEN")
  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))
}

use reqwest;

#[tokio::main]
async fn main() -> Result<(), reqwest::Error> {
    let client = reqwest::Client::new();
    let body = r#"{
  "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")
        .body(body)
        .header("Authorization", "Bearer YOUR_TOKEN")
        .header("Content-Type", "application/json")
        .send()
        .await?
        .text()
        .await?;
    println!("{}", response);
    Ok(())
}

Request Body

{
  "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"
}

{
  "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"
}

{
  "code": 404,
  "type": "Not found",
  "message": "Your cheese has already been eaten"
}

{
  "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"
    }
  ]
}

Body

application/json

Cheese object with updated fields

idinteger<int64>required

Unique identifier

Example

namestringrequired

Name of the cheese

Example

Gorgonzola

categoryCategory

Show child attributes

idinteger<int64>

Example

namestring

Example

Italian Cheese

photoUrlsArray<string>

URLs of cheese photos

Example

[
  "https://wannabechef.com/gorgonzola.jpg"
]

tagsArray<Tag>

Classification tags

Show child attributes

idinteger<int64>

Example

namestring

Example

blue

statusstringavailablependingsoldrequired

Availability status in the store

Example

available

originstring | null

Country of origin (null if unknown)

Example

Italy

pricePerKgnumber<float>> 0

Price per kilogram in USD

Example

28.5

ageMonthsinteger[0, 120]

Aging period in months

Example

organicbooleanfalse

Whether the cheese is certified organic

createdAtstring<date-time>

When the cheese was added to the store

updatedAtstring<date-time>

When the cheese was last updated

Response

200OKCheese

Cheese updated successfully

Response fields application/json

idinteger<int64>required

Unique identifier

Example

namestringrequired

Name of the cheese

Example

Gorgonzola

categoryCategory

Show child attributes

idinteger<int64>

Example

namestring

Example

Italian Cheese

photoUrlsArray<string>

URLs of cheese photos

Example

[
  "https://wannabechef.com/gorgonzola.jpg"
]

tagsArray<Tag>

Classification tags

Show child attributes

idinteger<int64>

Example

namestring

Example

blue

statusstringavailablependingsoldrequired

Availability status in the store

Example

available

originstring | null

Country of origin (null if unknown)

Example

Italy

pricePerKgnumber<float>> 0

Price per kilogram in USD

Example

28.5

ageMonthsinteger[0, 120]

Aging period in months

Example

organicbooleanfalse

Whether the cheese is certified organic

createdAtstring<date-time>

When the cheese was added to the store

updatedAtstring<date-time>

When the cheese was last updated

404Not FoundError

The requested resource was not found

Response fields application/json

codeinteger<int32>required

Example

typestring

Example

Not found

messagestringrequired

Example

Your cheese has already been eaten

422Unprocessable EntityValidationError

The request body failed validation

Response fields application/json

codeinteger<int32>

Example

typestring

Example

Validation error

messagestring

Example

Your cheese is not mouldy enough

errorsArray<object>

Individual field validation errors

Show child attributes

fieldstring

The field that failed validation

messagestring

Human-readable error message

Authorization

cheesy_oauthoauth2

OAuth2 authentication for full API access

Scopes: write:cheeses

Find cheeses by status

GET

https://cheese.example.com/v2/cheeses/findByStatus

Multiple status values can be provided as comma-separated strings. Returns all cheeses matching any of the given statuses.

Find cheeses by status

curl -X GET 'https://cheese.example.com/v2/cheeses/findByStatus?status=available' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('https://cheese.example.com/v2/cheeses/findByStatus?status=available', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'https://cheese.example.com/v2/cheeses/findByStatus?status=available',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

package main

import (
  "fmt"
  "io"
  "net/http"
)

func main() {
  req, _ := http.NewRequest("GET", "https://cheese.example.com/v2/cheeses/findByStatus?status=available", nil)
  req.Header.Set("Authorization", "Bearer YOUR_TOKEN")
  resp, _ := http.DefaultClient.Do(req)
  defer resp.Body.Close()
  data, _ := io.ReadAll(resp.Body)
  fmt.Println(string(data))
}

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?status=available")
        .header("Authorization", "Bearer YOUR_TOKEN")
        .send()
        .await?
        .text()
        .await?;
    println!("{}", response);
    Ok(())
}

[
  {
    "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"
  }
]

{
  "code": 404,
  "type": "Not found",
  "message": "Your cheese has already been eaten"
}

Parameters

statusArray<string>availablependingsoldrequiredquery

Status values to filter by

Response

200OKArray<Cheese>

Matching cheeses

Response fields application/json

Array<Cheese>

Show child attributes

idinteger<int64>required

Unique identifier

Example

namestringrequired

Name of the cheese

Example

Gorgonzola

categoryCategory

Show child attributes

idinteger<int64>

Example

namestring

Example

Italian Cheese

photoUrlsArray<string>

URLs of cheese photos

Example

[
  "https://wannabechef.com/gorgonzola.jpg"
]

tagsArray<Tag>

Classification tags

Show child attributes

idinteger<int64>

Example

namestring

Example

blue

statusstringavailablependingsoldrequired

Availability status in the store

Example

available

originstring | null

Country of origin (null if unknown)

Example

Italy

pricePerKgnumber<float>> 0

Price per kilogram in USD

Example

28.5

ageMonthsinteger[0, 120]

Aging period in months

Example

organicbooleanfalse

Whether the cheese is certified organic

createdAtstring<date-time>

When the cheese was added to the store

updatedAtstring<date-time>

When the cheese was last updated

400Bad RequestError

Invalid status value provided

Response fields application/json

codeinteger<int32>required

Example

typestring

Example

Not found

messagestringrequired

Example

Your cheese has already been eaten

Authorization

cheesy_oauthoauth2

OAuth2 authentication for full API access

Scopes: read:cheeses

Find cheeses by tags

deprecated

GET

https://cheese.example.com/v2/cheeses/findByTags

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.

Find cheeses by tags

curl -X GET 'https://cheese.example.com/v2/cheeses/findByTags?tags=string' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('https://cheese.example.com/v2/cheeses/findByTags?tags=string', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'https://cheese.example.com/v2/cheeses/findByTags?tags=string',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

package main

import (
  "fmt"
  "io"
  "net/http"
)

func main() {
  req, _ := http.NewRequest("GET", "https://cheese.example.com/v2/cheeses/findByTags?tags=string", nil)
  req.Header.Set("Authorization", "Bearer YOUR_TOKEN")
  resp, _ := http.DefaultClient.Do(req)
  defer resp.Body.Close()
  data, _ := io.ReadAll(resp.Body)
  fmt.Println(string(data))
}

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?tags=string")
        .header("Authorization", "Bearer YOUR_TOKEN")
        .send()
        .await?
        .text()
        .await?;
    println!("{}", response);
    Ok(())
}

[
  {
    "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"
  }
]

{
  "code": 404,
  "type": "Not found",
  "message": "Your cheese has already been eaten"
}

Parameters

tagsArray<string>requiredquery

Tags to filter by

Response

200OKArray<Cheese>

Matching cheeses

Response fields application/json

Array<Cheese>

Show child attributes

idinteger<int64>required

Unique identifier

Example

namestringrequired

Name of the cheese

Example

Gorgonzola

categoryCategory

Show child attributes

idinteger<int64>

Example

namestring

Example

Italian Cheese

photoUrlsArray<string>

URLs of cheese photos

Example

[
  "https://wannabechef.com/gorgonzola.jpg"
]

tagsArray<Tag>

Classification tags

Show child attributes

idinteger<int64>

Example

namestring

Example

blue

statusstringavailablependingsoldrequired

Availability status in the store

Example

available

originstring | null

Country of origin (null if unknown)

Example

Italy

pricePerKgnumber<float>> 0

Price per kilogram in USD

Example

28.5

ageMonthsinteger[0, 120]

Aging period in months

Example

organicbooleanfalse

Whether the cheese is certified organic

createdAtstring<date-time>

When the cheese was added to the store

updatedAtstring<date-time>

When the cheese was last updated

400Bad RequestError

Invalid tag value

Response fields application/json

codeinteger<int32>required

Example

typestring

Example

Not found

messagestringrequired

Example

Your cheese has already been eaten

Authorization

cheesy_oauthoauth2

OAuth2 authentication for full API access

Scopes: read:cheeses

Get cheese by ID

GET

https://cheese.example.com/v2/cheeses/{cheeseId}

Returns detailed information about a specific cheese, including its category, tags, and current availability status.

Get cheese by ID

curl -X GET 'https://cheese.example.com/v2/cheeses/42' \
  -H 'X-API-Key: YOUR_TOKEN'

const response = await fetch('https://cheese.example.com/v2/cheeses/42', {
  method: 'GET',
  headers: {
    'X-API-Key': 'YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'https://cheese.example.com/v2/cheeses/42',
    headers={
        'X-API-Key': 'YOUR_TOKEN',
    },
)
print(response.text)

package main

import (
  "fmt"
  "io"
  "net/http"
)

func main() {
  req, _ := http.NewRequest("GET", "https://cheese.example.com/v2/cheeses/42", nil)
  req.Header.Set("X-API-Key", "YOUR_TOKEN")
  resp, _ := http.DefaultClient.Do(req)
  defer resp.Body.Close()
  data, _ := io.ReadAll(resp.Body)
  fmt.Println(string(data))
}

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/42")
        .header("X-API-Key", "YOUR_TOKEN")
        .send()
        .await?
        .text()
        .await?;
    println!("{}", response);
    Ok(())
}

{
  "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"
    }
  ]
}

{
  "code": 404,
  "type": "Not found",
  "message": "Your cheese has already been eaten"
}

Parameters

cheeseIdinteger<int64>>= 1requiredpath

Unique identifier for the cheese

Response

200OKCheese

Cheese details

Response fields application/json

idinteger<int64>required

Unique identifier

Example

namestringrequired

Name of the cheese

Example

Gorgonzola

categoryCategory

Show child attributes

idinteger<int64>

Example

namestring

Example

Italian Cheese

photoUrlsArray<string>

URLs of cheese photos

Example

[
  "https://wannabechef.com/gorgonzola.jpg"
]

tagsArray<Tag>

Classification tags

Show child attributes

idinteger<int64>

Example

namestring

Example

blue

statusstringavailablependingsoldrequired

Availability status in the store

Example

available

originstring | null

Country of origin (null if unknown)

Example

Italy

pricePerKgnumber<float>> 0

Price per kilogram in USD

Example

28.5

ageMonthsinteger[0, 120]

Aging period in months

Example

organicbooleanfalse

Whether the cheese is certified organic

createdAtstring<date-time>

When the cheese was added to the store

updatedAtstring<date-time>

When the cheese was last updated

404Not FoundError

The requested resource was not found

Response fields application/json

codeinteger<int32>required

Example

typestring

Example

Not found

messagestringrequired

Example

Your cheese has already been eaten

Authorization

api_keyapiKey in header

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.

Update cheese with form data

POST

https://cheese.example.com/v2/cheeses/{cheeseId}

Updates specific fields of a cheese using form data. Only provided fields are updated.

Update cheese with form data

curl -X POST 'https://cheese.example.com/v2/cheeses/42' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('https://cheese.example.com/v2/cheeses/42', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.post(
    'https://cheese.example.com/v2/cheeses/42',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

package main

import (
  "fmt"
  "io"
  "net/http"
)

func main() {
  req, _ := http.NewRequest("POST", "https://cheese.example.com/v2/cheeses/42", nil)
  req.Header.Set("Authorization", "Bearer YOUR_TOKEN")
  resp, _ := http.DefaultClient.Do(req)
  defer resp.Body.Close()
  data, _ := io.ReadAll(resp.Body)
  fmt.Println(string(data))
}

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/42")
        .header("Authorization", "Bearer YOUR_TOKEN")
        .send()
        .await?
        .text()
        .await?;
    println!("{}", response);
    Ok(())
}

{
  "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"
}

{
  "code": 404,
  "type": "Not found",
  "message": "Your cheese has already been eaten"
}

{
  "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"
    }
  ]
}

Parameters

cheeseIdinteger<int64>>= 1requiredpath

Unique identifier for the cheese

namestringquery

Updated name of the cheese

statusstringavailablependingsoldquery

Updated status of the cheese

Response

200OKCheese

Cheese updated

Response fields application/json

idinteger<int64>required

Unique identifier

Example

namestringrequired

Name of the cheese

Example

Gorgonzola

categoryCategory

Show child attributes

idinteger<int64>

Example

namestring

Example

Italian Cheese

photoUrlsArray<string>

URLs of cheese photos

Example

[
  "https://wannabechef.com/gorgonzola.jpg"
]

tagsArray<Tag>

Classification tags

Show child attributes

idinteger<int64>

Example

namestring

Example

blue

statusstringavailablependingsoldrequired

Availability status in the store

Example

available

originstring | null

Country of origin (null if unknown)

Example

Italy

pricePerKgnumber<float>> 0

Price per kilogram in USD

Example

28.5

ageMonthsinteger[0, 120]

Aging period in months

Example

organicbooleanfalse

Whether the cheese is certified organic

createdAtstring<date-time>

When the cheese was added to the store

updatedAtstring<date-time>

When the cheese was last updated

404Not FoundError

The requested resource was not found

Response fields application/json

codeinteger<int32>required

Example

typestring

Example

Not found

messagestringrequired

Example

Your cheese has already been eaten

422Unprocessable EntityValidationError

The request body failed validation

Response fields application/json

codeinteger<int32>

Example

typestring

Example

Validation error

messagestring

Example

Your cheese is not mouldy enough

errorsArray<object>

Individual field validation errors

Show child attributes

fieldstring

The field that failed validation

messagestring

Human-readable error message

Authorization

cheesy_oauthoauth2

OAuth2 authentication for full API access

Scopes: write:cheeses

Delete a cheese

DELETE

https://cheese.example.com/v2/cheeses/{cheeseId}

Permanently removes a cheese from the store. This action cannot be undone. Any pending orders for this cheese will be cancelled.

Delete a cheese

curl -X DELETE 'https://cheese.example.com/v2/cheeses/42' \
  -H 'X-Confirm-Delete: true' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('https://cheese.example.com/v2/cheeses/42', {
  method: 'DELETE',
  headers: {
    'X-Confirm-Delete': 'true',
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.delete(
    'https://cheese.example.com/v2/cheeses/42',
    headers={
        'X-Confirm-Delete': 'true',
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

package main

import (
  "fmt"
  "io"
  "net/http"
)

func main() {
  req, _ := http.NewRequest("DELETE", "https://cheese.example.com/v2/cheeses/42", nil)
  req.Header.Set("X-Confirm-Delete", "true")
  req.Header.Set("Authorization", "Bearer YOUR_TOKEN")
  resp, _ := http.DefaultClient.Do(req)
  defer resp.Body.Close()
  data, _ := io.ReadAll(resp.Body)
  fmt.Println(string(data))
}

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/42")
        .header("X-Confirm-Delete", "true")
        .header("Authorization", "Bearer YOUR_TOKEN")
        .send()
        .await?
        .text()
        .await?;
    println!("{}", response);
    Ok(())
}

{
  "code": 404,
  "type": "Not found",
  "message": "Your cheese has already been eaten"
}

{
  "code": 404,
  "type": "Not found",
  "message": "Your cheese has already been eaten"
}

Parameters

cheeseIdinteger<int64>>= 1requiredpath

Unique identifier for the cheese

Response

204No Content

Cheese deleted successfully

404Not FoundError

The requested resource was not found

Response fields application/json

codeinteger<int32>required

Example

typestring

Example

Not found

messagestringrequired

Example

Your cheese has already been eaten

409ConflictError

Cheese has active orders and cannot be deleted

Response fields application/json

codeinteger<int32>required

Example

typestring

Example

Not found

messagestringrequired

Example

Your cheese has already been eaten

Authorization

cheesy_oauthoauth2

OAuth2 authentication for full API access

Scopes: write:cheeses

Upload a cheese image

POST

https://cheese.example.com/v2/cheeses/{cheeseId}/uploadImage

Upload a photo of the cheese. Supports JPEG, PNG, and WebP formats. Maximum file size is 10MB.

Upload a cheese image

curl -X POST 'https://cheese.example.com/v2/cheeses/0/uploadImage' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  --form-string 'caption=string' \
  --form-string 'isPrimary=false'

const form = new FormData();
form.append('caption', 'string');
form.append('isPrimary', 'false');
const response = await fetch('https://cheese.example.com/v2/cheeses/0/uploadImage', {
  method: 'POST',
  headers: {"Authorization":"Bearer YOUR_TOKEN"},
  body: form,
});
console.log(await response.text());

import requests
from contextlib import ExitStack

with ExitStack() as stack:
    files = [
        ('caption', (None, 'string')),
        ('isPrimary', (None, 'false')),
    ]
    response = requests.request('POST', 'https://cheese.example.com/v2/cheeses/0/uploadImage', headers={"Authorization":"Bearer YOUR_TOKEN"}, files=files)
    print(response.text)

package main
import ("bytes"; "fmt"; "io"; "mime/multipart"; "net/http")
func main() {
  var body bytes.Buffer
  writer := multipart.NewWriter(&body)
  writer.WriteField("caption", "string")
  writer.WriteField("isPrimary", "false")
  writer.Close()
  req, _ := http.NewRequest("POST", "https://cheese.example.com/v2/cheeses/0/uploadImage", &body)
  req.Header.Set("Authorization", "Bearer YOUR_TOKEN")
  req.Header.Set("Content-Type", writer.FormDataContentType())
  resp, err := http.DefaultClient.Do(req)
  if err != nil { panic(err) }
  defer resp.Body.Close()
  data, _ := io.ReadAll(resp.Body)
  fmt.Println(string(data))
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
  let form = reqwest::multipart::Form::new()
    .text("caption", "string")
    .text("isPrimary", "false")
    ;
  let response = reqwest::Client::new().request(reqwest::Method::from_bytes(b"POST")?, "https://cheese.example.com/v2/cheeses/0/uploadImage")
    .header("Authorization", "Bearer YOUR_TOKEN")
    .multipart(form).send().await?;
  println!("{}", response.text().await?);
  Ok(())
}

Request Body

{
  "file": "<binary>",
  "caption": "string",
  "isPrimary": false
}

{
  "imageUrl": "https://example.com",
  "thumbnailUrl": "https://example.com",
  "size": 0
}

{
  "code": 404,
  "type": "Not found",
  "message": "Your cheese has already been eaten"
}

{
  "code": 404,
  "type": "Not found",
  "message": "Your cheese has already been eaten"
}

Body

multipart/form-data

filestring<binary>required

Image file (JPEG, PNG, or WebP, max 10MB)

captionstring

Optional caption for the image

isPrimarybooleanfalse

Set as the primary display image

Parameters

cheeseIdinteger<int64>requiredpath

ID of cheese to upload image for

Response

200OKobject

Image uploaded successfully

Response fields application/json

imageUrlstring<uri>

thumbnailUrlstring<uri>

sizeinteger

File size in bytes

413Payload Too LargeError

File too large (max 10MB)

Response fields application/json

codeinteger<int32>required

Example

typestring

Example

Not found

messagestringrequired

Example

Your cheese has already been eaten

415Unsupported Media TypeError

Unsupported media type

Response fields application/json

codeinteger<int32>required

Example

typestring

Example

Not found

messagestringrequired

Example

Your cheese has already been eaten

Authorization

cheesy_oauthoauth2

OAuth2 authentication for full API access

Scopes: write:cheeses

Store

Store endpoints provide access to cheese store orders and inventory management. Orders track the purchase lifecycle from placement through delivery.

Get store inventory

GET

https://cheese.example.com/v2/store/inventory

Returns a map of cheese status codes to quantities, representing the current inventory levels.

Get store inventory

curl -X GET 'https://cheese.example.com/v2/store/inventory' \
  -H 'X-API-Key: YOUR_TOKEN'

const response = await fetch('https://cheese.example.com/v2/store/inventory', {
  method: 'GET',
  headers: {
    'X-API-Key': 'YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'https://cheese.example.com/v2/store/inventory',
    headers={
        'X-API-Key': 'YOUR_TOKEN',
    },
)
print(response.text)

package main

import (
  "fmt"
  "io"
  "net/http"
)

func main() {
  req, _ := http.NewRequest("GET", "https://cheese.example.com/v2/store/inventory", nil)
  req.Header.Set("X-API-Key", "YOUR_TOKEN")
  resp, _ := http.DefaultClient.Do(req)
  defer resp.Body.Close()
  data, _ := io.ReadAll(resp.Body)
  fmt.Println(string(data))
}

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")
        .header("X-API-Key", "YOUR_TOKEN")
        .send()
        .await?
        .text()
        .await?;
    println!("{}", response);
    Ok(())
}

200

{
  "available": 256,
  "pending": 34,
  "sold": 1089
}

Response

200OKobject

Inventory counts by status

Response fields application/json

[key: string]integer<int32>

Authorization

api_keyapiKey in header

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.

Place a cheese order

POST

https://cheese.example.com/v2/store/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}.

Place a cheese order

curl -X POST 'https://cheese.example.com/v2/store/order' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "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 body = `{
  "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 response = await fetch('https://cheese.example.com/v2/store/order', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "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',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

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("Authorization", "Bearer YOUR_TOKEN")
  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))
}

use reqwest;

#[tokio::main]
async fn main() -> Result<(), reqwest::Error> {
    let client = reqwest::Client::new();
    let body = r#"{
  "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")
        .body(body)
        .header("Authorization", "Bearer YOUR_TOKEN")
        .header("Content-Type", "application/json")
        .send()
        .await?
        .text()
        .await?;
    println!("{}", response);
    Ok(())
}

Request Body

{
  "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"
}

{
  "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"
}

{
  "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"
    }
  ]
}

Body

application/json

Order details

itemsArray<object>required

Show child attributes

cheeseIdinteger<int64>required

quantityinteger[1, 100]required

shippingAddressAddressrequired

Show child attributes

streetstringrequired

Example

123 Cheese Lane

citystringrequired

Example

Cheddarville

statestring | null

Example

WI

zipCodestring

Example

countrystringrequired

ISO 3166-1 alpha-2 country code

Example

US

notesstring | null

Response

201CreatedOrder

Order placed successfully

Response headers

Locationstring<uri>header

URL of the created order

Response fields application/json

idinteger<int64>

Example

itemsArray<OrderItem>

Show child attributes

cheeseIdinteger<int64>

cheeseNamestring

quantityinteger>= 1

pricePerKgnumber<float>

shippingAddressAddress

Show child attributes

streetstringrequired

Example

123 Cheese Lane

citystringrequired

Example

Cheddarville

statestring | null

Example

WI

zipCodestring

Example

countrystringrequired

ISO 3166-1 alpha-2 country code

Example

US

statusstringplacedapprovedshippeddeliveredcancelled

Order lifecycle status

Example

placed

notesstring | null

Special instructions for the order

totalnumber<float>

Order total in USD

Example

114.5

shipDatestring<date-time> | null

Estimated ship date (null if not yet scheduled)

createdAtstring<date-time>

updatedAtstring<date-time>

Example

{
  "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"
}

422Unprocessable EntityValidationError

The request body failed validation

Response fields application/json

codeinteger<int32>

Example

typestring

Example

Validation error

messagestring

Example

Your cheese is not mouldy enough

errorsArray<object>

Individual field validation errors

Show child attributes

fieldstring

The field that failed validation

messagestring

Human-readable error message

Authorization

cheesy_oauthoauth2

OAuth2 authentication for full API access

Scopes: write:orders

Get order by ID

GET

https://cheese.example.com/v2/store/order/{orderId}

Retrieve details of a specific order. For testing, use order IDs between 1 and 10.

Get order by ID

curl -X GET 'https://cheese.example.com/v2/store/order/1001' \
  -H 'X-API-Key: YOUR_TOKEN'

const response = await fetch('https://cheese.example.com/v2/store/order/1001', {
  method: 'GET',
  headers: {
    'X-API-Key': 'YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'https://cheese.example.com/v2/store/order/1001',
    headers={
        'X-API-Key': 'YOUR_TOKEN',
    },
)
print(response.text)

package main

import (
  "fmt"
  "io"
  "net/http"
)

func main() {
  req, _ := http.NewRequest("GET", "https://cheese.example.com/v2/store/order/1001", nil)
  req.Header.Set("X-API-Key", "YOUR_TOKEN")
  resp, _ := http.DefaultClient.Do(req)
  defer resp.Body.Close()
  data, _ := io.ReadAll(resp.Body)
  fmt.Println(string(data))
}

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/1001")
        .header("X-API-Key", "YOUR_TOKEN")
        .send()
        .await?
        .text()
        .await?;
    println!("{}", response);
    Ok(())
}

{
  "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"
}

{
  "code": 404,
  "type": "Not found",
  "message": "Your cheese has already been eaten"
}

Parameters

orderIdinteger<int64>>= 1requiredpath

ID of the order

Response

200OKOrder

Order details

Response fields application/json

idinteger<int64>

Example

itemsArray<OrderItem>

Show child attributes

cheeseIdinteger<int64>

cheeseNamestring

quantityinteger>= 1

pricePerKgnumber<float>

shippingAddressAddress

Show child attributes

streetstringrequired

Example

123 Cheese Lane

citystringrequired

Example

Cheddarville

statestring | null

Example

WI

zipCodestring

Example

countrystringrequired

ISO 3166-1 alpha-2 country code

Example

US

statusstringplacedapprovedshippeddeliveredcancelled

Order lifecycle status

Example

placed

notesstring | null

Special instructions for the order

totalnumber<float>

Order total in USD

Example

114.5

shipDatestring<date-time> | null

Estimated ship date (null if not yet scheduled)

createdAtstring<date-time>

updatedAtstring<date-time>

Example

{
  "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"
}

404Not FoundError

The requested resource was not found

Response fields application/json

codeinteger<int32>required

Example

typestring

Example

Not found

messagestringrequired

Example

Your cheese has already been eaten

Authorization

api_keyapiKey in header

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.

Cancel an order

DELETE

https://cheese.example.com/v2/store/order/{orderId}

Cancel a pending order. Orders that have already been shipped cannot be cancelled.

Cancel an order

curl -X DELETE 'https://cheese.example.com/v2/store/order/1001' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('https://cheese.example.com/v2/store/order/1001', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.delete(
    'https://cheese.example.com/v2/store/order/1001',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

package main

import (
  "fmt"
  "io"
  "net/http"
)

func main() {
  req, _ := http.NewRequest("DELETE", "https://cheese.example.com/v2/store/order/1001", nil)
  req.Header.Set("Authorization", "Bearer YOUR_TOKEN")
  resp, _ := http.DefaultClient.Do(req)
  defer resp.Body.Close()
  data, _ := io.ReadAll(resp.Body)
  fmt.Println(string(data))
}

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/1001")
        .header("Authorization", "Bearer YOUR_TOKEN")
        .send()
        .await?
        .text()
        .await?;
    println!("{}", response);
    Ok(())
}

{
  "code": 404,
  "type": "Not found",
  "message": "Your cheese has already been eaten"
}

{
  "code": 404,
  "type": "Not found",
  "message": "Your cheese has already been eaten"
}

Parameters

orderIdinteger<int64>>= 1requiredpath

ID of the order

Response

204No Content

Order cancelled successfully

404Not FoundError

The requested resource was not found

Response fields application/json

codeinteger<int32>required

Example

typestring

Example

Not found

messagestringrequired

Example

Your cheese has already been eaten

409ConflictError

Order has already been shipped

Response fields application/json

codeinteger<int32>required

Example

typestring

Example

Not found

messagestringrequired

Example

Your cheese has already been eaten

Authorization

cheesy_oauthoauth2

OAuth2 authentication for full API access

Scopes: write:orders

Customer

Customer endpoints handle account creation, authentication, and profile management.

Customer accounts support OAuth2 login and API key authentication.

Customer Portal

Create a customer account

POST

https://cheese.example.com/v2/customer

Create a customer account

curl -X POST 'https://cheese.example.com/v2/customer' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "username": "gordo",
  "firstName": "Alotta",
  "lastName": "Cheese",
  "email": "love@cheese.com",
  "password": "secret123!",
  "phone": "+3344556677"
}'

const body = `{
  "username": "gordo",
  "firstName": "Alotta",
  "lastName": "Cheese",
  "email": "love@cheese.com",
  "password": "secret123!",
  "phone": "+3344556677"
}`;

const response = await fetch('https://cheese.example.com/v2/customer', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "username": "gordo",
  "firstName": "Alotta",
  "lastName": "Cheese",
  "email": "love@cheese.com",
  "password": "secret123!",
  "phone": "+3344556677"
}'''

response = requests.post(
    'https://cheese.example.com/v2/customer',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)

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))
}

use reqwest;

#[tokio::main]
async fn main() -> Result<(), reqwest::Error> {
    let client = reqwest::Client::new();
    let body = r#"{
  "username": "gordo",
  "firstName": "Alotta",
  "lastName": "Cheese",
  "email": "love@cheese.com",
  "password": "secret123!",
  "phone": "+3344556677"
}"#;
    let response = client.post("https://cheese.example.com/v2/customer")
        .body(body)
        .header("Content-Type", "application/json")
        .send()
        .await?
        .text()
        .await?;
    println!("{}", response);
    Ok(())
}

Request Body

{
  "username": "gordo",
  "firstName": "Alotta",
  "lastName": "Cheese",
  "email": "love@cheese.com",
  "password": "secret123!",
  "phone": "+3344556677"
}

{
  "id": 1,
  "username": "gordo",
  "firstName": "Alotta",
  "lastName": "Cheese",
  "email": "love@cheese.com",
  "phone": "+3344556677",
  "customerStatus": "gold",
  "favouriteCheese": {
    "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"
  },
  "createdAt": "2024-01-15T09:30:00Z"
}

{
  "code": 404,
  "type": "Not found",
  "message": "Your cheese has already been eaten"
}

{
  "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"
    }
  ]
}

Body

application/json

Customer registration details

usernamestringrequired

firstNamestring

lastNamestring

emailstring<email>required

passwordstring<password>required

phonestring | null

Response

201CreatedCustomer

Customer account created

Response fields application/json

idinteger<int64>

Example

usernamestring

Example

gordo

firstNamestring

Customer first name

Example

Alotta

lastNamestring

Customer last name

Example

Cheese

emailstring<email>

Example

love@cheese.com

phonestring | null

Example

+3344556677

customerStatusstringbronzesilvergoldplatinum

Customer tier based on purchase volume

Example

gold

favouriteCheeseCheese | object

The customer's favourite cheese (by reference or by name)

Show child attributes

One of

idinteger<int64>required

Unique identifier

Example

namestringrequired

Name of the cheese

Example

Gorgonzola

categoryCategory

Show child attributes

idinteger<int64>

Example

namestring

Example

Italian Cheese

photoUrlsArray<string>

URLs of cheese photos

Example

[
  "https://wannabechef.com/gorgonzola.jpg"
]

tagsArray<Tag>

Classification tags

Show child attributes

idinteger<int64>

Example

namestring

Example

blue

statusstringavailablependingsoldrequired

Availability status in the store

Example

available

originstring | null

Country of origin (null if unknown)

Example

Italy

pricePerKgnumber<float>> 0

Price per kilogram in USD

Example

28.5

ageMonthsinteger[0, 120]

Aging period in months

Example

organicbooleanfalse

Whether the cheese is certified organic

createdAtstring<date-time>

When the cheese was added to the store

updatedAtstring<date-time>

When the cheese was last updated

namestringrequired

createdAtstring<date-time>

409ConflictError

Username or email already exists

Response fields application/json

codeinteger<int32>required

Example

typestring

Example

Not found

messagestringrequired

Example

Your cheese has already been eaten

422Unprocessable EntityValidationError

The request body failed validation

Response fields application/json

codeinteger<int32>

Example

typestring

Example

Validation error

messagestring

Example

Your cheese is not mouldy enough

errorsArray<object>

Individual field validation errors

Show child attributes

fieldstring

The field that failed validation

messagestring

Human-readable error message

Create multiple customers

POST

https://cheese.example.com/v2/customer/createMultiple

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:

{
  "created": [...],
  "errors": [
    { "index": 2, "message": "Email already exists" }
  ]
}

Create multiple customers

curl -X POST 'https://cheese.example.com/v2/customer/createMultiple' \
  -H 'Content-Type: application/json' \
  --data-raw '[
  {
    "username": "string",
    "firstName": "string",
    "lastName": "string",
    "email": "user@example.com",
    "password": "********",
    "phone": "string"
  }
]'

const body = `[
  {
    "username": "string",
    "firstName": "string",
    "lastName": "string",
    "email": "user@example.com",
    "password": "********",
    "phone": "string"
  }
]`;

const response = await fetch('https://cheese.example.com/v2/customer/createMultiple', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''[
  {
    "username": "string",
    "firstName": "string",
    "lastName": "string",
    "email": "user@example.com",
    "password": "********",
    "phone": "string"
  }
]'''

response = requests.post(
    'https://cheese.example.com/v2/customer/createMultiple',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)

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))
}

use reqwest;

#[tokio::main]
async fn main() -> Result<(), reqwest::Error> {
    let client = reqwest::Client::new();
    let body = r#"[
  {
    "username": "string",
    "firstName": "string",
    "lastName": "string",
    "email": "user@example.com",
    "password": "********",
    "phone": "string"
  }
]"#;
    let response = client.post("https://cheese.example.com/v2/customer/createMultiple")
        .body(body)
        .header("Content-Type", "application/json")
        .send()
        .await?
        .text()
        .await?;
    println!("{}", response);
    Ok(())
}

Request Body

[
  {
    "username": "string",
    "firstName": "string",
    "lastName": "string",
    "email": "user@example.com",
    "password": "********",
    "phone": "string"
  }
]

{
  "created": [
    {
      "id": 1,
      "username": "gordo",
      "firstName": "Alotta",
      "lastName": "Cheese",
      "email": "love@cheese.com",
      "phone": "+3344556677",
      "customerStatus": "gold",
      "favouriteCheese": {
        "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"
      },
      "createdAt": "2024-01-15T09:30:00Z"
    }
  ],
  "errors": [
    {
      "index": 0,
      "message": "string"
    }
  ]
}

{
  "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"
    }
  ]
}

Body

application/json

Array of customer objects to create

Array<CustomerInput>

Show child attributes

usernamestringrequired

firstNamestring

lastNamestring

emailstring<email>required

passwordstring<password>required

phonestring | null

Response

200OKobject

Batch creation result

Response fields application/json

createdArray<Customer>

Show child attributes

idinteger<int64>

Example

usernamestring

Example

gordo

firstNamestring

Customer first name

Example

Alotta

lastNamestring

Customer last name

Example

Cheese

emailstring<email>

Example

love@cheese.com

phonestring | null

Example

+3344556677

customerStatusstringbronzesilvergoldplatinum

Customer tier based on purchase volume

Example

gold

favouriteCheeseCheese | object

The customer's favourite cheese (by reference or by name)

Show child attributes

One of

idinteger<int64>required

Unique identifier

Example

namestringrequired

Name of the cheese

Example

Gorgonzola

categoryCategory

Show child attributes

idinteger<int64>

Example

namestring

Example

Italian Cheese

photoUrlsArray<string>

URLs of cheese photos

Example

[
  "https://wannabechef.com/gorgonzola.jpg"
]

tagsArray<Tag>

Classification tags

Show child attributes

idinteger<int64>

Example

namestring

Example

blue

statusstringavailablependingsoldrequired

Availability status in the store

Example

available

originstring | null

Country of origin (null if unknown)

Example

Italy

pricePerKgnumber<float>> 0

Price per kilogram in USD

Example

28.5

ageMonthsinteger[0, 120]

Aging period in months

Example

organicbooleanfalse

Whether the cheese is certified organic

createdAtstring<date-time>

When the cheese was added to the store

updatedAtstring<date-time>

When the cheese was last updated

namestringrequired

createdAtstring<date-time>

errorsArray<object>

Show child attributes

indexinteger

messagestring

422Unprocessable EntityValidationError

The request body failed validation

Response fields application/json

codeinteger<int32>

Example

typestring

Example

Validation error

messagestring

Example

Your cheese is not mouldy enough

errorsArray<object>

Individual field validation errors

Show child attributes

fieldstring

The field that failed validation

messagestring

Human-readable error message

Customer login

POST

https://cheese.example.com/v2/customer/login

Authenticate a customer and receive a session token. The token expires after 24 hours.

Customer login

curl -X POST 'https://cheese.example.com/v2/customer/login' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "username": "string",
  "password": "********"
}'

const body = `{
  "username": "string",
  "password": "********"
}`;

const response = await fetch('https://cheese.example.com/v2/customer/login', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "username": "string",
  "password": "********"
}'''

response = requests.post(
    'https://cheese.example.com/v2/customer/login',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)

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))
}

use reqwest;

#[tokio::main]
async fn main() -> Result<(), reqwest::Error> {
    let client = reqwest::Client::new();
    let body = r#"{
  "username": "string",
  "password": "********"
}"#;
    let response = client.post("https://cheese.example.com/v2/customer/login")
        .body(body)
        .header("Content-Type", "application/json")
        .send()
        .await?
        .text()
        .await?;
    println!("{}", response);
    Ok(())
}

Request Body

{
  "username": "string",
  "password": "********"
}

{
  "token": "string",
  "expiresAt": "2024-01-15T09:30:00Z"
}

{
  "code": 404,
  "type": "Not found",
  "message": "Your cheese has already been eaten"
}

Response

200OKobject

Response headers

X-Rate-Limitinteger<int32>header

Requests per hour allowed for this customer

X-Expires-Afterstring<date-time>header

Token expiration date-time (UTC)

Response fields application/json

tokenstring

JWT session token

expiresAtstring<date-time>

Token expiration time (UTC)

401UnauthorizedError

Invalid username or password

Response fields application/json

codeinteger<int32>required

Example

typestring

Example

Not found

messagestringrequired

Example

Your cheese has already been eaten

Customer logout

GET

https://cheese.example.com/v2/customer/logout

End the current customer session and invalidate the session token.

Customer logout

curl -X GET 'https://cheese.example.com/v2/customer/logout' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('https://cheese.example.com/v2/customer/logout', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'https://cheese.example.com/v2/customer/logout',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

package main

import (
  "fmt"
  "io"
  "net/http"
)

func main() {
  req, _ := http.NewRequest("GET", "https://cheese.example.com/v2/customer/logout", nil)
  req.Header.Set("Authorization", "Bearer YOUR_TOKEN")
  resp, _ := http.DefaultClient.Do(req)
  defer resp.Body.Close()
  data, _ := io.ReadAll(resp.Body)
  fmt.Println(string(data))
}

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")
        .header("Authorization", "Bearer YOUR_TOKEN")
        .send()
        .await?
        .text()
        .await?;
    println!("{}", response);
    Ok(())
}

Response

204No Content

Logout successful

Authorization

bearer_authhttp (bearer)

JWT token obtained from the /customer/login endpoint

Get customer by username

GET

https://cheese.example.com/v2/customer/{username}

Retrieve a customer's profile by their username.

Get customer by username

curl -X GET 'https://cheese.example.com/v2/customer/gordo' \
  -H 'X-API-Key: YOUR_TOKEN'

const response = await fetch('https://cheese.example.com/v2/customer/gordo', {
  method: 'GET',
  headers: {
    'X-API-Key': 'YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'https://cheese.example.com/v2/customer/gordo',
    headers={
        'X-API-Key': 'YOUR_TOKEN',
    },
)
print(response.text)

package main

import (
  "fmt"
  "io"
  "net/http"
)

func main() {
  req, _ := http.NewRequest("GET", "https://cheese.example.com/v2/customer/gordo", nil)
  req.Header.Set("X-API-Key", "YOUR_TOKEN")
  resp, _ := http.DefaultClient.Do(req)
  defer resp.Body.Close()
  data, _ := io.ReadAll(resp.Body)
  fmt.Println(string(data))
}

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/gordo")
        .header("X-API-Key", "YOUR_TOKEN")
        .send()
        .await?
        .text()
        .await?;
    println!("{}", response);
    Ok(())
}

{
  "id": 1,
  "username": "gordo",
  "firstName": "Alotta",
  "lastName": "Cheese",
  "email": "love@cheese.com",
  "phone": "+3344556677",
  "customerStatus": "gold",
  "favouriteCheese": {
    "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"
  },
  "createdAt": "2024-01-15T09:30:00Z"
}

{
  "code": 404,
  "type": "Not found",
  "message": "Your cheese has already been eaten"
}

Parameters

usernamestringrequiredpath

The customer's username

Response

200OKCustomer

Customer profile

Response fields application/json

idinteger<int64>

Example

usernamestring

Example

gordo

firstNamestring

Customer first name

Example

Alotta

lastNamestring

Customer last name

Example

Cheese

emailstring<email>

Example

love@cheese.com

phonestring | null

Example

+3344556677

customerStatusstringbronzesilvergoldplatinum

Customer tier based on purchase volume

Example

gold

favouriteCheeseCheese | object

The customer's favourite cheese (by reference or by name)

Show child attributes

One of

idinteger<int64>required

Unique identifier

Example

namestringrequired

Name of the cheese

Example

Gorgonzola

categoryCategory

Show child attributes

idinteger<int64>

Example

namestring

Example

Italian Cheese

photoUrlsArray<string>

URLs of cheese photos

Example

[
  "https://wannabechef.com/gorgonzola.jpg"
]

tagsArray<Tag>

Classification tags

Show child attributes

idinteger<int64>

Example

namestring

Example

blue

statusstringavailablependingsoldrequired

Availability status in the store

Example

available

originstring | null

Country of origin (null if unknown)

Example

Italy

pricePerKgnumber<float>> 0

Price per kilogram in USD

Example

28.5

ageMonthsinteger[0, 120]

Aging period in months

Example

organicbooleanfalse

Whether the cheese is certified organic

createdAtstring<date-time>

When the cheese was added to the store

updatedAtstring<date-time>

When the cheese was last updated

namestringrequired

createdAtstring<date-time>

404Not FoundError

The requested resource was not found

Response fields application/json

codeinteger<int32>required

Example

typestring

Example

Not found

messagestringrequired

Example

Your cheese has already been eaten

Authorization

api_keyapiKey in header

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_authhttp (bearer)

JWT token obtained from the /customer/login endpoint

Update customer profile

PUT

https://cheese.example.com/v2/customer/{username}

Update a customer's profile. Can only be performed by the authenticated customer.

Update customer profile

curl -X PUT 'https://cheese.example.com/v2/customer/gordo' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "username": "string",
  "firstName": "string",
  "lastName": "string",
  "email": "user@example.com",
  "password": "********",
  "phone": "string"
}'

const body = `{
  "username": "string",
  "firstName": "string",
  "lastName": "string",
  "email": "user@example.com",
  "password": "********",
  "phone": "string"
}`;

const response = await fetch('https://cheese.example.com/v2/customer/gordo', {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "username": "string",
  "firstName": "string",
  "lastName": "string",
  "email": "user@example.com",
  "password": "********",
  "phone": "string"
}'''

response = requests.put(
    'https://cheese.example.com/v2/customer/gordo',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

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/gordo", body)
  req.Header.Set("Authorization", "Bearer YOUR_TOKEN")
  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))
}

use reqwest;

#[tokio::main]
async fn main() -> Result<(), reqwest::Error> {
    let client = reqwest::Client::new();
    let body = r#"{
  "username": "string",
  "firstName": "string",
  "lastName": "string",
  "email": "user@example.com",
  "password": "********",
  "phone": "string"
}"#;
    let response = client.put("https://cheese.example.com/v2/customer/gordo")
        .body(body)
        .header("Authorization", "Bearer YOUR_TOKEN")
        .header("Content-Type", "application/json")
        .send()
        .await?
        .text()
        .await?;
    println!("{}", response);
    Ok(())
}

Request Body

{
  "username": "string",
  "firstName": "string",
  "lastName": "string",
  "email": "user@example.com",
  "password": "********",
  "phone": "string"
}

{
  "id": 1,
  "username": "gordo",
  "firstName": "Alotta",
  "lastName": "Cheese",
  "email": "love@cheese.com",
  "phone": "+3344556677",
  "customerStatus": "gold",
  "favouriteCheese": {
    "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"
  },
  "createdAt": "2024-01-15T09:30:00Z"
}

{
  "code": 404,
  "type": "Not found",
  "message": "Your cheese has already been eaten"
}

{
  "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"
    }
  ]
}

Body

application/json

Updated customer fields

usernamestringrequired

firstNamestring

lastNamestring

emailstring<email>required

passwordstring<password>required

phonestring | null

Parameters

usernamestringrequiredpath

The customer's username

Response

200OKCustomer

Customer updated

Response fields application/json

idinteger<int64>

Example

usernamestring

Example

gordo

firstNamestring

Customer first name

Example

Alotta

lastNamestring

Customer last name

Example

Cheese

emailstring<email>

Example

love@cheese.com

phonestring | null

Example

+3344556677

customerStatusstringbronzesilvergoldplatinum

Customer tier based on purchase volume

Example

gold

favouriteCheeseCheese | object

The customer's favourite cheese (by reference or by name)

Show child attributes

One of

idinteger<int64>required

Unique identifier

Example

namestringrequired

Name of the cheese

Example

Gorgonzola

categoryCategory

Show child attributes

idinteger<int64>

Example

namestring

Example

Italian Cheese

photoUrlsArray<string>

URLs of cheese photos

Example

[
  "https://wannabechef.com/gorgonzola.jpg"
]

tagsArray<Tag>

Classification tags

Show child attributes

idinteger<int64>

Example

namestring

Example

blue

statusstringavailablependingsoldrequired

Availability status in the store

Example

available

originstring | null

Country of origin (null if unknown)

Example

Italy

pricePerKgnumber<float>> 0

Price per kilogram in USD

Example

28.5

ageMonthsinteger[0, 120]

Aging period in months

Example

organicbooleanfalse

Whether the cheese is certified organic

createdAtstring<date-time>

When the cheese was added to the store

updatedAtstring<date-time>

When the cheese was last updated

namestringrequired

createdAtstring<date-time>

404Not FoundError

The requested resource was not found

Response fields application/json

codeinteger<int32>required

Example

typestring

Example

Not found

messagestringrequired

Example

Your cheese has already been eaten

422Unprocessable EntityValidationError

The request body failed validation

Response fields application/json

codeinteger<int32>

Example

typestring

Example

Validation error

messagestring

Example

Your cheese is not mouldy enough

errorsArray<object>

Individual field validation errors

Show child attributes

fieldstring

The field that failed validation

messagestring

Human-readable error message

Authorization

bearer_authhttp (bearer)

JWT token obtained from the /customer/login endpoint

Delete customer account

DELETE

https://cheese.example.com/v2/customer/{username}

Permanently delete a customer account and all associated data. This action cannot be undone.

Delete customer account

curl -X DELETE 'https://cheese.example.com/v2/customer/gordo' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('https://cheese.example.com/v2/customer/gordo', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.delete(
    'https://cheese.example.com/v2/customer/gordo',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

package main

import (
  "fmt"
  "io"
  "net/http"
)

func main() {
  req, _ := http.NewRequest("DELETE", "https://cheese.example.com/v2/customer/gordo", nil)
  req.Header.Set("Authorization", "Bearer YOUR_TOKEN")
  resp, _ := http.DefaultClient.Do(req)
  defer resp.Body.Close()
  data, _ := io.ReadAll(resp.Body)
  fmt.Println(string(data))
}

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/gordo")
        .header("Authorization", "Bearer YOUR_TOKEN")
        .send()
        .await?
        .text()
        .await?;
    println!("{}", response);
    Ok(())
}

404

{
  "code": 404,
  "type": "Not found",
  "message": "Your cheese has already been eaten"
}

Parameters

usernamestringrequiredpath

The customer's username

Response

204No Content

Customer deleted

404Not FoundError

The requested resource was not found

Response fields application/json

codeinteger<int32>required

Example

typestring

Example

Not found

messagestringrequired

Example

Your cheese has already been eaten

Authorization

bearer_authhttp (bearer)

JWT token obtained from the /customer/login endpoint

Models

Cheese

object

idinteger<int64>required

Unique identifier

Example

namestringrequired

Name of the cheese

Example

Gorgonzola

categoryCategory

Show child attributes

idinteger<int64>

Example

namestring

Example

Italian Cheese

photoUrlsArray<string>

URLs of cheese photos

Example

[
  "https://wannabechef.com/gorgonzola.jpg"
]

tagsArray<Tag>

Classification tags

Show child attributes

idinteger<int64>

Example

namestring

Example

blue

statusstringavailablependingsoldrequired

Availability status in the store

Example

available

originstring | null

Country of origin (null if unknown)

Example

Italy

pricePerKgnumber<float>> 0

Price per kilogram in USD

Example

28.5

ageMonthsinteger[0, 120]

Aging period in months

Example

organicbooleanfalse

Whether the cheese is certified organic

createdAtstring<date-time>

When the cheese was added to the store

updatedAtstring<date-time>

When the cheese was last updated

Example

{
  "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"
}

CheeseInput

object

namestringrequired

categoryobject

Show child attributes

namestring

photoUrlsArray<string>

tagsArray<object>

Show child attributes

namestring

statusstringavailablependingsoldavailable

originstring | null

pricePerKgnumber<float>> 0

ageMonthsinteger[0, 120]

organicbooleanfalse

Example

{
  "name": "string",
  "category": {
    "name": "string"
  },
  "photoUrls": [
    "https://example.com"
  ],
  "tags": [
    {
      "name": "string"
    }
  ],
  "status": "available",
  "origin": "string",
  "pricePerKg": 0,
  "ageMonths": 0,
  "organic": false
}

CheeseList

object

Paginated list of cheeses

itemsArray<Cheese>

Show child attributes

idinteger<int64>required

Unique identifier

Example

namestringrequired

Name of the cheese

Example

Gorgonzola

categoryCategory

Show child attributes

idinteger<int64>

Example

namestring

Example

Italian Cheese

photoUrlsArray<string>

URLs of cheese photos

Example

[
  "https://wannabechef.com/gorgonzola.jpg"
]

tagsArray<Tag>

Classification tags

Show child attributes

idinteger<int64>

Example

namestring

Example

blue

statusstringavailablependingsoldrequired

Availability status in the store

Example

available

originstring | null

Country of origin (null if unknown)

Example

Italy

pricePerKgnumber<float>> 0

Price per kilogram in USD

Example

28.5

ageMonthsinteger[0, 120]

Aging period in months

Example

organicbooleanfalse

Whether the cheese is certified organic

createdAtstring<date-time>

When the cheese was added to the store

updatedAtstring<date-time>

When the cheese was last updated

nextCursorstring | null

Cursor for the next page (null if no more results)

hasMoreboolean

Whether there are more results

totalinteger

Total number of matching cheeses

Example

{
  "items": [
    {
      "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"
    }
  ],
  "nextCursor": "string",
  "hasMore": true,
  "total": 0
}

Tag

object

idinteger<int64>

Example

namestring

Example

blue

Order

object

idinteger<int64>

Example

itemsArray<OrderItem>

Show child attributes

cheeseIdinteger<int64>

cheeseNamestring

quantityinteger>= 1

pricePerKgnumber<float>

shippingAddressAddress

Show child attributes

streetstringrequired

Example

123 Cheese Lane

citystringrequired

Example

Cheddarville

statestring | null

Example

WI

zipCodestring

Example

countrystringrequired

ISO 3166-1 alpha-2 country code

Example

US

statusstringplacedapprovedshippeddeliveredcancelled

Order lifecycle status

Example

placed

notesstring | null

Special instructions for the order

totalnumber<float>

Order total in USD

Example

114.5

shipDatestring<date-time> | null

Estimated ship date (null if not yet scheduled)

createdAtstring<date-time>

updatedAtstring<date-time>

Example

{
  "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"
}

Example

{
  "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"
}

OrderInput

object

itemsArray<object>required

Show child attributes

cheeseIdinteger<int64>required

quantityinteger[1, 100]required

shippingAddressAddressrequired

Show child attributes

streetstringrequired

Example

123 Cheese Lane

citystringrequired

Example

Cheddarville

statestring | null

Example

WI

zipCodestring

Example

countrystringrequired

ISO 3166-1 alpha-2 country code

Example

US

notesstring | null

Example

{
  "items": [
    {
      "cheeseId": 0,
      "quantity": 1
    }
  ],
  "shippingAddress": {
    "street": "123 Cheese Lane",
    "city": "Cheddarville",
    "state": "WI",
    "zipCode": "53001",
    "country": "US"
  },
  "notes": "string"
}

OrderItem

object

cheeseIdinteger<int64>

cheeseNamestring

quantityinteger>= 1

pricePerKgnumber<float>

Address

object

streetstringrequired

Example

123 Cheese Lane

citystringrequired

Example

Cheddarville

statestring | null

Example

WI

zipCodestring

Example

countrystringrequired

ISO 3166-1 alpha-2 country code

Example

US

Customer

object

idinteger<int64>

Example

usernamestring

Example

gordo

firstNamestring

Customer first name

Example

Alotta

lastNamestring

Customer last name

Example

Cheese

emailstring<email>

Example

love@cheese.com

phonestring | null

Example

+3344556677

customerStatusstringbronzesilvergoldplatinum

Customer tier based on purchase volume

Example

gold

favouriteCheeseCheese | object

The customer's favourite cheese (by reference or by name)

Show child attributes

One of

idinteger<int64>required

Unique identifier

Example

namestringrequired

Name of the cheese

Example

Gorgonzola

categoryCategory

Show child attributes

idinteger<int64>

Example

namestring

Example

Italian Cheese

photoUrlsArray<string>

URLs of cheese photos

Example

[
  "https://wannabechef.com/gorgonzola.jpg"
]

tagsArray<Tag>

Classification tags

Show child attributes

idinteger<int64>

Example

namestring

Example

blue

statusstringavailablependingsoldrequired

Availability status in the store

Example

available

originstring | null

Country of origin (null if unknown)

Example

Italy

pricePerKgnumber<float>> 0

Price per kilogram in USD

Example

28.5

ageMonthsinteger[0, 120]

Aging period in months

Example

organicbooleanfalse

Whether the cheese is certified organic

createdAtstring<date-time>

When the cheese was added to the store

updatedAtstring<date-time>

When the cheese was last updated

namestringrequired

createdAtstring<date-time>

Example

{
  "id": 1,
  "username": "gordo",
  "firstName": "Alotta",
  "lastName": "Cheese",
  "email": "love@cheese.com",
  "phone": "+3344556677",
  "customerStatus": "gold",
  "favouriteCheese": {
    "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"
  },
  "createdAt": "2024-01-15T09:30:00Z"
}

CustomerInput

object

usernamestringrequired

firstNamestring

lastNamestring

emailstring<email>required

passwordstring<password>required

phonestring | null

Error

object

codeinteger<int32>required

Example

typestring

Example

Not found

messagestringrequired

Example

Your cheese has already been eaten

ValidationError

object

codeinteger<int32>

Example

typestring

Example

Validation error

messagestring

Example

Your cheese is not mouldy enough

errorsArray<object>

Individual field validation errors

Show child attributes

fieldstring

The field that failed validation

messagestring

Human-readable error message