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 Swagger 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.

Add a new cheese to the store

POST /cheeses

Cheese object to be added to the store

Request Example
{
  "category": {
    "$ref": "#/definitions/Category"
  },
  "id": "integer(int64)",
  "name": "string",
  "photoUrls": "array",
  "status": "string",
  "tags": "array"
}
200 OK

Successful operation

405 Method Not Allowed

Invalid input

Response Example (200 OK)
{
  "category": {
    "$ref": "#/definitions/Category"
  },
  "id": "integer(int64)",
  "name": "string",
  "photoUrls": "array",
  "status": "string",
  "tags": "array"
}
cheesy_auth write:cheeses , read:cheeses

Update an existing cheese

PUT /cheeses

Cheese object that needs to be updated

Request Example
{
  "category": {
    "$ref": "#/definitions/Category"
  },
  "id": "integer(int64)",
  "name": "string",
  "photoUrls": "array",
  "status": "string",
  "tags": "array"
}
400 Bad Request

Invalid ID supplied

404 Not Found

Cheese not found

405 Method Not Allowed

Validation exception

cheesy_auth write:cheeses , read:cheeses

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

Successful operation

400 Bad Request

Invalid tag value

Response Example (200 OK)
[
  {
    "category": {
      "$ref": "#/definitions/Category"
    },
    "id": "integer(int64)",
    "name": "string",
    "photoUrls": "array",
    "status": "string",
    "tags": "array"
  }
]
cheesy_auth write:cheeses , read:cheeses

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

Successful operation

400 Bad Request

Invalid ID supplied

404 Not Found

Cheese not found

Response Example (200 OK)
{
  "category": {
    "$ref": "#/definitions/Category"
  },
  "id": "integer(int64)",
  "name": "string",
  "photoUrls": "array",
  "status": "string",
  "tags": "array"
}
Response Example (400 Bad Request)
{
  "code": "integer(int32)",
  "message": "string",
  "type": "string"
}
Response Example (404 Not Found)
{
  "code": "integer(int32)",
  "message": "string",
  "type": "string"
}

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
405 Method Not Allowed

Invalid input

cheesy_auth write:cheeses , read:cheeses

Deletes a cheese

DELETE /cheeses/{cheeseId}
api_key

(no description)

type
string
in
header
cheeseId

Cheese ID to delete

type
integer (int64)
in
path
400 Bad Request

Invalid ID supplied

404 Not Found

Cheese not found

Response Example (400 Bad Request)
{
  "code": "integer(int32)",
  "message": "string",
  "type": "string"
}
Response Example (404 Not Found)
{
  "code": "integer(int32)",
  "message": "string",
  "type": "string"
}
cheesy_auth write:cheeses , read:cheeses

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

Successful operation

400 Bad Request

Invalid status value

Response Example (200 OK)
[
  {
    "category": {
      "$ref": "#/definitions/Category"
    },
    "id": "integer(int64)",
    "name": "string",
    "photoUrls": "array",
    "status": "string",
    "tags": "array"
  }
]
Response Example (400 Bad Request)
{
  "code": "integer(int32)",
  "message": "string",
  "type": "string"
}
cheesy_auth write:cheeses , read:cheeses

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

Successful operation

Response Example (200 OK)
{
  "category": {
    "$ref": "#/definitions/Category"
  },
  "id": "integer(int64)",
  "name": "string",
  "photoUrls": "array",
  "status": "string",
  "tags": "array"
}
cheesy_auth write:cheeses , read:cheeses

Store

Store methods provide access to cheese store orders.

Return cheese inventories by status

GET /store/inventory

Returns a map of status codes to quantities.

200 OK

Successful operation

Response Example (200 OK)
{
  "additionalProperties": {
    "format": "int32",
    "type": "integer"
  },
  "type": "object"
}

Place a cheese order

POST /store/order

Place an order to purchase cheese from the store.

Order to place for purchasing the cheese.

Request Example
{
  "cheeseId": "integer(int64)",
  "complete": "boolean",
  "id": "integer(int64)",
  "quantity": "integer(int32)",
  "shipDate": "string(date-time)",
  "status": "string"
}
200 OK

Successful operation

400 Bad Request

Invalid Order

Response Example (200 OK)
{
  "cheeseId": "integer(int64)",
  "complete": "boolean",
  "id": "integer(int64)",
  "quantity": "integer(int32)",
  "shipDate": "string(date-time)",
  "status": "string"
}

Find purchase order by ID

GET /store/order/{orderId}

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

orderId

ID of cheese that needs to be fetched

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

Successful operation

400 Bad Request

Invalid ID supplied

404 Not Found

Order not found

Response Example (200 OK)
{
  "cheeseId": "integer(int64)",
  "complete": "boolean",
  "id": "integer(int64)",
  "quantity": "integer(int32)",
  "shipDate": "string(date-time)",
  "status": "string"
}

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
400 Bad Request

Invalid ID supplied

404 Not Found

Order not found

Customer

Customer methods contain operations relating to customer accounts.

Create customer account

POST /customer

This can only be done by the logged in customer.

Created customer object

Request Example
{
  "customerStatus": "integer(int32)",
  "email": "string",
  "firstName": "string",
  "id": "integer(int64)",
  "lastName": "string",
  "password": "string",
  "phone": "string",
  "username": "string"
}
default

Successful operation

Create multiple customers

POST /customer/createMultiple

Create a list of customers from the given input array.

List of created customer objects

Request Example
[
  {
    "customerStatus": "integer(int32)",
    "email": "string",
    "firstName": "string",
    "id": "integer(int64)",
    "lastName": "string",
    "password": "string",
    "phone": "string",
    "username": "string"
  }
]
default

Successful operation

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

400 Bad Request

Invalid username/password supplied

Response Example (200 OK)
{
  "type": "string"
}

Customer logout

GET /customer/logout

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

default

Successful operation

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

Successful operation

400 Bad Request

Invalid username supplied

404 Not Found

Customer not found

Response Example (200 OK)
{
  "customerStatus": "integer(int32)",
  "email": "string",
  "firstName": "string",
  "id": "integer(int64)",
  "lastName": "string",
  "password": "string",
  "phone": "string",
  "username": "string"
}

Update customer

PUT /customer/{username}

This can only be done by the logged in customer.

Customer object to be updated.

username

Username of the customer to update.

type
string
in
path
Request Example
{
  "customerStatus": "integer(int32)",
  "email": "string",
  "firstName": "string",
  "id": "integer(int64)",
  "lastName": "string",
  "password": "string",
  "phone": "string",
  "username": "string"
}
400 Bad Request

Invalid customer supplied

404 Not Found

Customer not found

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

Customer not found

Models

Category: object

id: integer (int64)
name: string

Cheese: object

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

cheese status in the store

Customer: object

id: integer (int64)
username: string
firstName: string
lastName: string
email: string
password: string
phone: string
customerStatus: integer (int32)

Customer Status

Error: object

code: integer (int32)
type: string
message: string

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

Tag: object

id: integer (int64)
name: string