Cheese Store API Reference

Welcome to the sample Cheese Store API reference. This is a live example of how you can use Spectacle in conjunction with an OpenAPI Specification v2 (fka Swagger specification) to generate beautiful static documentation for your own APIs.

The Cheese Store API is organized around the REST mothodology, and it uses resource-oriented URLs, and common HTTP response codes to indicate API errors. All requests are authenticated using an api-key which can be obtained from your developer dashboard. And now, more cheese...

Hard cheese gouda say cheese. Ricotta cauliflower cheese cheesecake bocconcini edam bocconcini fromage feta. Who moved my cheese bocconcini cheese and wine cottage cheese cheese on toast who moved my cheese caerphilly stinking bishop. Bocconcini cheesy feet the big cheese macaroni cheese cheesy feet mascarpone.

API Endpoint
https://cheesy.sourcey.com/v1
Terms of Service: http://cheesy.sourcey.com/terms
Contact: cheesy@sourcey.com
Schemes: http, https
Version: 1.0.0

Authentication

cheesy_auth

authorizationUrl
http://cheesy.sourcey.com/api/oauth/dialog
flow
implicit

api_key

name
api_key
in
header

Cheese

Cheese methods provide access to information and operations relating to the cheese available in the store.

Cheese

Add a new cheese to the store

POST /cheeses
Cheese

Cheese object to be added to the store

Request Example
{
  "id": 1,
  "category": {
    "id": 1,
    "name": "Italian Cheese"
  },
  "name": "Gorgonzola",
  "photoUrls": [
    "https://wannabechef.com/gorgonzola.jpg"
  ],
  "tags": [
    {
      "id": 1,
      "name": "Manchego"
    }
  ],
  "status": "available"
}
200 OK
Cheese

Successful operation

422 Unprocessable Entity
ValidationError

Invalid input

Response Example (200 OK) 
{
  "id": 1,
  "category": {
    "id": 1,
    "name": "Italian Cheese"
  },
  "name": "Gorgonzola",
  "photoUrls": [
    "https://wannabechef.com/gorgonzola.jpg"
  ],
  "tags": [
    {
      "id": 1,
      "name": "Manchego"
    }
  ],
  "status": "available"
}
Response Example (422 Unprocessable Entity) 
{
  "code": 422,
  "type": "Validation error",
  "message": "Your cheese is not mouldy enough"
}
cheesy_auth write:cheeses , read:cheeses
Cheese

Update an existing cheese

PUT /cheeses
Cheese

Cheese object that needs to be updated

Request Example
{
  "id": 1,
  "category": {
    "id": 1,
    "name": "Italian Cheese"
  },
  "name": "Gorgonzola",
  "photoUrls": [
    "https://wannabechef.com/gorgonzola.jpg"
  ],
  "tags": [
    {
      "id": 1,
      "name": "Manchego"
    }
  ],
  "status": "available"
}
404 Not Found
NotFoundError

Cheese not found

422 Unprocessable Entity
ValidationError

Validation exception

Response Example (404 Not Found) 
{
  "code": 404,
  "type": "Not found",
  "message": "Your cheese has already been eaten"
}
Response Example (422 Unprocessable Entity) 
{
  "code": 422,
  "type": "Validation error",
  "message": "Your cheese is not mouldy enough"
}
cheesy_auth write:cheeses , read:cheeses
Cheese

Finds cheeses by tags

GET /cheeses/findByTags

Muliple tags can be provided with comma separated strings. Use tag1, tag2, tag3 for testing.

tags

Tags to filter by

format
multiple parameters (tags=aaa&tags=bbb)
type
string[]
in
query
200 OK
Cheese

Successful operation

404 Not Found
NotFoundError

Invalid tag value

Response Example (200 OK) 
[
  {
    "id": 1,
    "category": {
      "id": 1,
      "name": "Italian Cheese"
    },
    "name": "Gorgonzola",
    "photoUrls": [
      "https://wannabechef.com/gorgonzola.jpg"
    ],
    "tags": [
      {
        "id": 1,
        "name": "Manchego"
      }
    ],
    "status": "available"
  }
]
Response Example (404 Not Found) 
{
  "code": 404,
  "type": "Not found",
  "message": "Your cheese has already been eaten"
}
cheesy_auth write:cheeses , read:cheeses
Cheese

Find cheese by ID

GET /cheeses/{cheeseId}

Return a specific cheese by it's ID.

cheeseId

ID of cheese to return

type
integer (int64)
in
path
200 OK
Cheese

Successful operation

404 Not Found
NotFoundError

Cheese not found

Response Example (200 OK) 
{
  "id": 1,
  "category": {
    "id": 1,
    "name": "Italian Cheese"
  },
  "name": "Gorgonzola",
  "photoUrls": [
    "https://wannabechef.com/gorgonzola.jpg"
  ],
  "tags": [
    {
      "id": 1,
      "name": "Manchego"
    }
  ],
  "status": "available"
}
Response Example (404 Not Found) 
{
  "code": 404,
  "type": "Not found",
  "message": "Your cheese has already been eaten"
}
api_key
Cheese

Update a cheese

POST /cheeses/{cheeseId}

Updates a cheese in the Store with form data.

cheeseId

ID of the cheese to be updated

type
integer (int64)
in
path
name

Updated name of the cheese

type
string
in
formData
status

Updated status of the cheese

type
string
in
formData
422 Unprocessable Entity
ValidationError

Cannot update cheese

Response Example (422 Unprocessable Entity) 
{
  "code": 422,
  "type": "Validation error",
  "message": "Your cheese is not mouldy enough"
}
cheesy_auth write:cheeses , read:cheeses
Cheese

Deletes a cheese

DELETE /cheeses/{cheeseId}
api_key

(no description)

type
string
in
header
cheeseId

Cheese ID to delete

type
integer (int64)
in
path
404 Not Found
NotFoundError

Cheese not found

Response Example (404 Not Found) 
{
  "code": 404,
  "type": "Not found",
  "message": "Your cheese has already been eaten"
}
cheesy_auth write:cheeses , read:cheeses
Cheese

Finds cheeses by status

GET /cheeses/findByStatus

Multiple status values can be provided with comma separated strings.

status

Status values that need to be considered for filter

format
multiple parameters (status=aaa&status=bbb)
type
string[]
in
query
200 OK
Cheese

Successful operation

404 Not Found
NotFoundError

Invalid status value

Response Example (200 OK) 
[
  {
    "id": 1,
    "category": {
      "id": 1,
      "name": "Italian Cheese"
    },
    "name": "Gorgonzola",
    "photoUrls": [
      "https://wannabechef.com/gorgonzola.jpg"
    ],
    "tags": [
      {
        "id": 1,
        "name": "Manchego"
      }
    ],
    "status": "available"
  }
]
Response Example (404 Not Found) 
{
  "code": 404,
  "type": "Not found",
  "message": "Your cheese has already been eaten"
}
cheesy_auth write:cheeses , read:cheeses
Cheese

Upload a cheese image

POST /cheeses/{cheeseId}/uploadImage
cheeseId

ID of cheese to update

type
integer (int64)
in
path
additionalMetadata

Additional data to pass to server

type
string
in
formData
file

Image file to upload

type
file
in
formData
200 OK
Cheese

Successful operation

Response Example (200 OK) 
{
  "id": 1,
  "category": {
    "id": 1,
    "name": "Italian Cheese"
  },
  "name": "Gorgonzola",
  "photoUrls": [
    "https://wannabechef.com/gorgonzola.jpg"
  ],
  "tags": [
    {
      "id": 1,
      "name": "Manchego"
    }
  ],
  "status": "available"
}
cheesy_auth write:cheeses , read:cheeses

Store

Store methods provide access to cheese store orders.

Store

Return cheese inventories by available status

GET /store/inventory

Returns a list of available cheeses.

200 OK
Cheese

Successful operation

Response Example (200 OK) 
[
  {
    "id": 1,
    "category": {
      "id": 1,
      "name": "Italian Cheese"
    },
    "name": "Gorgonzola",
    "photoUrls": [
      "https://wannabechef.com/gorgonzola.jpg"
    ],
    "tags": [
      {
        "id": 1,
        "name": "Manchego"
      }
    ],
    "status": "available"
  }
]
api_key
Store

Place a cheese order

POST /store/order

Place an order to purchase cheese from the store.

Order

Order to place for purchasing the cheese.

Request Example
{
  "cheeseId": "1",
  "complete": "true",
  "id": "1",
  "quantity": "66",
  "shipDate": "04-10-2017 00:09:21 UTC",
  "status": "available"
}
200 OK
Order

Successful operation

422 Unprocessable Entity
ValidationError

Invalid order

Response Example (200 OK) 
{
  "cheeseId": "1",
  "complete": "true",
  "id": "1",
  "quantity": "66",
  "shipDate": "04-10-2017 00:09:21 UTC",
  "status": "available"
}
Response Example (422 Unprocessable Entity) 
{
  "code": 422,
  "type": "Validation error",
  "message": "Your cheese is not mouldy enough"
}
Store

Find purchase order by ID

GET /store/order/{orderId}

For valid response try integer IDs with value >= 1 and <= 10. Other values will generate exceptions.

orderId

ID of cheese that needs to be fetched

type
integer (int64) , { x ∈ ℤ | 1 ≤ x ≤ 10 }
in
path
200 OK
Order

Successful operation

404 Not Found
NotFoundError

Order not found

Response Example (200 OK) 
{
  "cheeseId": "1",
  "complete": "true",
  "id": "1",
  "quantity": "66",
  "shipDate": "04-10-2017 00:09:21 UTC",
  "status": "available"
}
Response Example (404 Not Found) 
{
  "code": 404,
  "type": "Not found",
  "message": "Your cheese has already been eaten"
}
Store

Delete purchase order by ID

DELETE /store/order/{orderId}

For valid response try integer IDs with positive integer value. Negative or non-integer values will generate API errors.

orderId

ID of the order that needs to be deleted

type
integer (int64) , { x ∈ ℤ | x ≥ 1 }
in
path
404 Not Found
NotFoundError

Order not found

Response Example (404 Not Found) 
{
  "code": 404,
  "type": "Not found",
  "message": "Your cheese has already been eaten"
}

Customer

Customer methods contain operations relating to customer accounts.

Customer

Create customer account

POST /customer

This can only be done by the logged in customer.

Customer

Created customer object

Request Example
{
  "id": 1,
  "username": "gordo",
  "firstName": "Alotta",
  "lastName": "Cheese",
  "email": "love@cheese.com",
  "password": "secret",
  "phone": "+3344556677",
  "customerStatus": "obese"
}
default

Successful operation

Customer

Create multiple customers

POST /customer/createMultiple

Create a list of customers from the given input array.

List of created customer objects

Customer
Request Example
[
  {
    "id": 1,
    "username": "gordo",
    "firstName": "Alotta",
    "lastName": "Cheese",
    "email": "love@cheese.com",
    "password": "secret",
    "phone": "+3344556677",
    "customerStatus": "obese"
  }
]
default

Successful operation

Customer

Customer login

POST /customer/login

Log a customer into the system and create a new user session.

username

The username for login

type
string
in
query
password

The password for login in clear text

type
string
in
query
200 OK

Successful operation

422 Unprocessable Entity
ValidationError

Invalid username/password supplied

Response Example (200 OK) 
"string"
Response Example (422 Unprocessable Entity) 
{
  "code": 422,
  "type": "Validation error",
  "message": "Your cheese is not mouldy enough"
}
Customer

Customer logout

GET /customer/logout

Log the currently the authenticated customer out of the system and end the user session.

default

Successful operation

Customer

Get customer by username

GET /customer/{username}

Get customer by their customer username.

username

The username of the customer to be fetched.

type
string
in
path
200 OK
Customer

Successful operation

404 Not Found
NotFoundError

Customer not found

Response Example (200 OK) 
{
  "id": 1,
  "username": "gordo",
  "firstName": "Alotta",
  "lastName": "Cheese",
  "email": "love@cheese.com",
  "password": "secret",
  "phone": "+3344556677",
  "customerStatus": "obese"
}
Response Example (404 Not Found) 
{
  "code": 404,
  "type": "Not found",
  "message": "Your cheese has already been eaten"
}
Customer

Update customer

PUT /customer/{username}

This can only be done by the logged in customer.

Customer

Customer object to be updated.

username

Username of the customer to update.

type
string
in
path
Request Example
{
  "id": 1,
  "username": "gordo",
  "firstName": "Alotta",
  "lastName": "Cheese",
  "email": "love@cheese.com",
  "password": "secret",
  "phone": "+3344556677",
  "customerStatus": "obese"
}
400 Bad Request

Invalid customer supplied

404 Not Found
NotFoundError

Customer not found

Response Example (404 Not Found) 
{
  "code": 404,
  "type": "Not found",
  "message": "Your cheese has already been eaten"
}
Customer

Delete customer

DELETE /customer/{username}

Datate a customer by their username.

username

Username of the customer to delete.

type
string
in
path
400 Bad Request

Invalid username supplied

404 Not Found
NotFoundError

Customer not found

Response Example (404 Not Found) 
{
  "code": 404,
  "type": "Not found",
  "message": "Your cheese has already been eaten"
}

Schema Definitions

Order: object

id: integer (int64)
cheeseId: integer (int64)
quantity: integer (int32)
shipDate: string (date-time)
status: string , x ∈ { placed , approved , delivered }

Order Status

complete: boolean
Example
{
  "cheeseId": "1",
  "complete": "true",
  "id": "1",
  "quantity": "66",
  "shipDate": "04-10-2017 00:09:21 UTC",
  "status": "available"
}

Category: object

id: integer (int64)
name: string
Example
{
  "id": 1,
  "name": "Italian Cheese"
}

Customer: object

id: integer (int64)
username: string
firstName: string

Customer first name

lastName: string

Customer last name

email: string
password: string
phone: string
customerStatus: string , x ∈ { skinny , average , fat , obese }

Customer status (the heavier the better)

Example
{
  "id": 1,
  "username": "gordo",
  "firstName": "Alotta",
  "lastName": "Cheese",
  "email": "love@cheese.com",
  "password": "secret",
  "phone": "+3344556677",
  "customerStatus": "obese"
}

Tag: object

id: integer (int64)
name: string
Example
{
  "id": 1,
  "name": "Manchego"
}

Error: object

code: integer (int32)
type: string
message: string
Example
{
  "code": "integer (int32)",
  "type": "No cheese found",
  "message": "No cheese for you!"
}

ValidationError: object

code: integer (int32)
type: string
message: string
Example
{
  "code": 422,
  "type": "Validation error",
  "message": "Your cheese is not mouldy enough"
}

NotFoundError: object

code: integer (int32)
type: string
message: string
Example
{
  "code": 404,
  "type": "Not found",
  "message": "Your cheese has already been eaten"
}

Cheese: object

id: integer (int64)
category: Category
name: string
photoUrls: string[]
tags: object[]
status: string , x ∈ { available , pending , sold }

Cheese status in the store

Example
{
  "id": 1,
  "category": {
    "id": 1,
    "name": "Italian Cheese"
  },
  "name": "Gorgonzola",
  "photoUrls": [
    "https://wannabechef.com/gorgonzola.jpg"
  ],
  "tags": [
    {
      "id": 1,
      "name": "Manchego"
    }
  ],
  "status": "available"
}
Documentation by Spectacle