Buggy API

A deliberately buggy shopping cart API for API testing practice.

The Buggy API is a small public Shopping Cart practice API mounted at /shop.

It is deliberately buggy by default. Start the app with -shopbugs=none to run the clean business rules.

Use POST /shop/register to create a cart and receive a bearer token. Product catalogue data is read-only; cart item writes happen through /shop/carts/{cartId}/items.

Model

Things

product

A safe fixed catalogue item with internally maintained stock.

Fields:

Fieldname	Type	Description
id	AUTO_INCREMENT	Unique product identifier. Field is an ID and should not be amended or set
Example: "42"
productCode	ENUM	Safe catalogue code for the product. Value must be an Enum (BOOK_REST, CD_HEADERS, MUG_TESTER, USB_CABLE, PEN_RED, POSTER_API, BLURAY_HTTP, DVD_BUGS, PUZZLE_CACHE, STICKER_HTTP, PUZZLE_PROXY, NOTEBOOK_LOGS, STICKER_PACK, POSTER_BUG, BOOK_API, BOOK_TESTS, MUG_CLIENT, NOTEBOOK_GRID, GAME_JSON, USB_HUB, CD_STATUS, GAME_TOKENS, PEN_BLUE, DVD_STATUS) value Value is mandatory
Example: "PEN_BLUE"
category	ENUM	Safe category for the product. Value must be an Enum (cd, game, electronics, art, dvd, book, homeware, stationery, blu-ray) value Value is mandatory
Example: "stationery"
unitPrice	FLOAT	Current unit price used for new cart lines. Value must be a Float of min 0.010000 and max 500.000000 Value is mandatory
Example: "1.00"
stock	INTEGER	Current available stock count maintained by the API. Value must be an Integer of min -1000 and max 9999 Value is mandatory
Example: "0"

Example JSON Output from API calls


{
  "id": 42,
  "productCode": "PEN_BLUE",
  "category": "stationery",
  "unitPrice": 1.0,
  "stock": 0
}

Example JSON Input to API calls


{
  "id": 1,
  "productCode": "PEN_BLUE",
  "category": "stationery",
  "unitPrice": 1.0,
  "stock": 0
}

Example XML Input to API calls


<product>
  <unitPrice>1.0</unitPrice>
  <productCode>PEN_BLUE</productCode>
  <id>1</id>
  <category>stationery</category>
  <stock>0</stock>
</product>

cart

A user's shopping cart, created through registration.

Fields:

Fieldname	Type	Description
id	AUTO_INCREMENT	Unique cart identifier. Field is an ID and should not be amended or set
Example: "18"
token	AUTO_GUID	Protected bearer token for cart mutation. Field is an ID and should not be amended or set Value is mandatory
Example: "b4f27a2c-d8d9-48d0-a68c-f5bfb9eb6a0f"
state	ENUM	Lifecycle state of the cart. Value must be an Enum (closed, abandoned, open) value Value is mandatory
Example: "closed"
createdTick	INTEGER	Internal tick when the cart was created. Value must be an Integer of min 0 and max 999999
Example: "0"
updatedTick	INTEGER	Internal tick when the cart was last changed. Value must be an Integer of min 0 and max 999999
Example: "0"
checkoutTick	INTEGER	Internal tick when checkout last completed. Value must be an Integer of min 0 and max 999999
Example: "0"

Views:

View	Request Fields	Response Fields	Input Allowed Fields
PublicCart	id, state, createdTick, updatedTick, checkoutTick	id, state, createdTick, updatedTick, checkoutTick	id, state, createdTick, updatedTick, checkoutTick

Example JSON Output from API calls


{
  "id": 18,
  "token": "b4f27a2c-d8d9-48d0-a68c-f5bfb9eb6a0f",
  "state": "closed",
  "createdTick": 0,
  "updatedTick": 0,
  "checkoutTick": 0
}

Example JSON Input to API calls


{
  "id": 1,
  "state": "closed",
  "createdTick": 0,
  "updatedTick": 0,
  "checkoutTick": 0
}

Example XML Input to API calls


<cart>
  <updatedTick>0</updatedTick>
  <createdTick>0</createdTick>
  <id>1</id>
  <state>closed</state>
  <checkoutTick>0</checkoutTick>
</cart>

cartitem

A product line in a shopping cart.

Fields:

Fieldname	Type	Description
id	AUTO_INCREMENT	Unique cart item identifier. Field is an ID and should not be amended or set
Example: "10"
productId	INTEGER	Product identifier requested for this cart line. Value must be an Integer of min 1 and max 24 Value is mandatory
Example: "1"
quantity	INTEGER	Requested quantity for this cart line. Value must be an Integer of min -1000 and max 9999 Value is mandatory
Example: "1"
unitPriceAtAdd	FLOAT	Product unit price captured when the line was added. Value must be a Float of min 0.000000 and max 500.000000
Example: "0.00"
stockAtAdd	INTEGER	Product stock captured when the line was added. Value must be an Integer of min -1000 and max 9999
Example: "0"

Views:

View	Request Fields	Response Fields	Input Allowed Fields
AddedCartItem	id, productId, quantity	id, productId, quantity, unitPriceAtAdd, stockAtAdd	id, productId, quantity, unitPriceAtAdd, stockAtAdd

Example JSON Output from API calls


{
  "id": 10,
  "productId": 1,
  "quantity": 1,
  "unitPriceAtAdd": 0.0,
  "stockAtAdd": 0
}

Example JSON Input to API calls


{
  "id": 1,
  "productId": 1,
  "quantity": 1,
  "unitPriceAtAdd": 0.0,
  "stockAtAdd": 0
}

Example XML Input to API calls


<cartitem>
  <quantity>1</quantity>
  <stockAtAdd>0</stockAtAdd>
  <productId>1</productId>
  <unitPriceAtAdd>0.0</unitPriceAtAdd>
  <id>1</id>
</cartitem>

Relationships

erDiagram
    CART ||--o{ CARTITEM : items
    PRODUCT ||--o{ CARTITEM : cartitems

items : cart =(items, max *)=> cartitem
cart : cartitem =(cart, max 1)=> cart
cartitems : product =(cartitems, max *)=> cartitem
product : cartitem =(product, max 1)=> product

API

The API takes body with objects using the field definitions and examples shown in the model.

End Points

/shop/products

e.g. /shop/products

This endpoint can be filtered with fields as URL Query Parameters.

e.g. /shop/products?unitPrice=1.00&productCode=PUZZLE_PROXY

This endpoint can be sorted with the _sortBy URL Query Parameter. Use _sortBy=+field or _sortBy=field for ascending order, and _sortBy=-field for descending order. Multiple fields can be combined with commas, e.g. _sortBy=+field,-other.

e.g. /shop/products?_sortBy=+id

GET /shop/products
- return all the instances of product

QUERY /shop/products
- query all the instances of product using application/x-www-form-urlencoded, application/jsonpath, application/vnd.thingifier.query+json query content

QUERY form content uses Content-Type: application/x-www-form-urlencoded with fields such as title=Task&_sortBy=-id.

QUERY JSONPath content uses Content-Type: application/jsonpath with an expression such as $['products'][?@['id'] == 'value'].

QUERY structured JSON content uses Content-Type: application/vnd.thingifier.query+json with a JSON query object.

HEAD /shop/products
- headers for all the instances of product

OPTIONS /shop/products
- show all Options for endpoint of /shop/products

/shop/products/:id

e.g. /shop/products/:id

GET /shop/products/:id
- return a specific instances of product using a id

HEAD /shop/products/:id
- headers for a specific instances of product using a id

OPTIONS /shop/products/:id
- show all Options for endpoint of /shop/products/:id

/shop/carts

e.g. /shop/carts

This endpoint can be filtered with fields as URL Query Parameters.

e.g. /shop/carts?checkoutTick=0

e.g. /shop/carts?_sortBy=+id

GET /shop/carts
- return all the instances of cart

QUERY /shop/carts
- query all the instances of cart using application/x-www-form-urlencoded, application/jsonpath, application/vnd.thingifier.query+json query content

QUERY form content uses Content-Type: application/x-www-form-urlencoded with fields such as title=Task&_sortBy=-id.

QUERY JSONPath content uses Content-Type: application/jsonpath with an expression such as $['carts'][?@['id'] == 'value'].

QUERY structured JSON content uses Content-Type: application/vnd.thingifier.query+json with a JSON query object.

HEAD /shop/carts
- headers for all the instances of cart

OPTIONS /shop/carts
- show all Options for endpoint of /shop/carts

/shop/carts/:id

e.g. /shop/carts/:id

GET /shop/carts/:id
- return a specific instances of cart using a id

HEAD /shop/carts/:id
- headers for a specific instances of cart using a id

DELETE /shop/carts/:id
- delete or abandon a cart using the cart bearer token

OPTIONS /shop/carts/:id
- show all Options for endpoint of /shop/carts/:id

/shop/carts/:id/items

e.g. /shop/carts/:id/items

This endpoint can be filtered with fields as URL Query Parameters.

e.g. /shop/carts/:id/items?quantity=1&productId=1

e.g. /shop/carts/:id/items?_sortBy=+id

GET /shop/carts/:id/items
- return all the cartitem items related to cart, with given id, by the relationship named items

QUERY /shop/carts/:id/items
- query all the cartitem items related to cart, with given id, by the relationship named items using application/x-www-form-urlencoded, application/jsonpath, application/vnd.thingifier.query+json query content

QUERY form content uses Content-Type: application/x-www-form-urlencoded with fields such as title=Task&_sortBy=-id.

QUERY JSONPath content uses Content-Type: application/jsonpath with an expression such as $['cartitems'][?@['id'] == 'value'].

QUERY structured JSON content uses Content-Type: application/vnd.thingifier.query+json with a JSON query object.

HEAD /shop/carts/:id/items
- headers for the cartitem items related to cart, with given id, by the relationship named items

OPTIONS /shop/carts/:id/items
- show all Options for endpoint of /shop/carts/:id/items

POST /shop/carts/:id/items
- add a product line to a cart using the cart bearer token

/shop/carts/:id/items/:relatedId

e.g. /shop/carts/:id/items/:relatedId

DELETE /shop/carts/:id/items/:relatedId
- delete a product line from a cart using the cart bearer token

OPTIONS /shop/carts/:id/items/:relatedId
- show all Options for endpoint of /shop/carts/:id/items/:relatedId

/shop/register

e.g. /shop/register

POST /shop/register
- create a new open cart and return its bearer token

/shop/checkout/:cartId

e.g. /shop/checkout/:cartId

POST /shop/checkout/:cartId
- checkout a cart using its bearer token in the Authorization header

Find OpenAPI file and OpenAPI Powered Client UIs like Swagger and Scalar here