HTTP API

Inventory Service1.2.0

A sample HTTP API that keeps stock levels for a warehouse. It is published on this site to show how an OpenAPI description becomes a reference page. The service is illustrative and is not deployed.

Quantities are whole units. Every change is recorded as a movement: a receipt, a sale, or a count. See the HTTP API reference guide for how this page is produced.

Servers

https://inventory.example.com/v1
https://staging.inventory.example.com/v1

Items

List items

GET/items

Returns items in SKU order, one page at a time.

Parameters

Name	In	Type	Required	Description
`after`	query	string	No	Return items whose SKU sorts after this value.
`limit`	query	integer (int32)	No	Largest number of items to return, from 1 to 200.

Responses

Status	Description	Content
200	A page of items.	`application/json` ItemPage

Create an item

POST/items

Registers a new SKU with a quantity of zero.

Request body Required

application/json NewItem

Responses

Status	Description	Content
201	The item was created.	`application/json` Item
409	An item with this SKU already exists.	`application/json` Problem

Get an item

GET/items/{sku}

Parameters

Name	In	Type	Required	Description
`sku`	path	string	Yes	The stock keeping unit.

Responses

Status	Description	Content
200	The item.	`application/json` Item
404	No item has this SKU.	`application/json` Problem

Retire an item

DELETE/items/{sku}

Retires an item whose quantity is zero. Retired items keep their history.

Parameters

Name	In	Type	Required	Description
`sku`	path	string	Yes	The stock keeping unit.

Responses

Status	Description	Content
204	The item was retired.
409	The item still has stock.

Movements

Record a movement

POST/items/{sku}/movements

Applies a receipt, sale, or count to an item and returns the new quantity.

Parameters

Name	In	Type	Required	Description
`sku`	path	string	Yes	The stock keeping unit.
`Idempotency-Key`	header	string	No	A client-chosen key that makes retries safe.

Request body Required

application/json Movement

Responses

Status	Description	Content
200	The item after the movement.	`application/json` Item
422	A sale would make the quantity negative.	`application/json` Problem

Schemas

Item

object

One stock keeping unit and the quantity on hand.

Property	Type	Required	Description
`sku`	string	Yes	The stock keeping unit.
`name`	string	No	A display name.
`quantity`	integer (int64)	Yes	Units on hand.

ItemPage

object

One page of items.

Property	Type	Required	Description
`items`	array of Item	Yes	Items in SKU order.
`next`	string	No	The value to pass as `after` for the next page, absent on the last page.

Movement

object

A change to an item's quantity.

Property	Type	Required	Description
`kind`	MovementKind	Yes
`quantity`	integer (int64)	Yes	Units received or sold, or the counted quantity.

MovementKind

string

What a movement does to the quantity.

Allowed values: received, sold, counted

NewItem

object

The fields of an item to create.

Property	Type	Required	Description
`sku`	string	Yes	The stock keeping unit.
`name`	string	No	A display name.

Problem

object

An error response.

Property	Type	Required	Description
`code`	string	Yes	A stable error code.
`message`	string	Yes	A readable explanation.