Simple API Mode

A simple API, no auth protection so you can add and delete what you want in a multi-user mode.

Use the Content-Type header to define the payload content e.g.

Content-Type: application/json

Set Content-Type header to application/xml, text/xml, or a model-matching application/*+xml media type if you want to send in XML.

Content-Type: application/xml

Content-Type: text/xml

Content-Type: application/todo+xml

You can control the returned data format by setting the Accept header

You can request XML response by setting the Accept header.

i.e. for XML use

Accept: application/xml
Accept: text/xml
Accept: application/*+xml

You can request JSON response by setting the Accept header.

i.e. for JSON use

Accept: application/json

Additional response Accept headers are supported.

Accept: text/csv
Accept: text/plain
Accept: text/html
Accept: application/x-ndjson
Accept: application/jsonl
Accept: application/json-seq
Accept: text/tab-separated-values

Some requests can be filtered by adding query params of fieldname=value. Where only matching items will be returned.

Filter conditions can use field=value for equals, field!=value or field!value for not equals, field<value, field>value, field<=value, and field>=value for comparisons, field~=regex for regular expression matches, and field*=wildcard for wildcard matches where * matches many characters and ? matches one character. Multiple query params are combined as AND conditions.

e.g. /thing?size=2&status=true

Some requests can be sorted by adding the _sortBy query param with a field name. 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.

Model

Things

item

Fields:

Fieldname	Type	Description
id	AUTO_INCREMENT	Field is an ID and should not be amended or set
Example: "19"
type	ENUM	Value must be an Enum (cd, dvd, book, blu-ray) value Value is mandatory
Example: "cd"
isbn13	STRING	Value is mandatory Value must match the regex [0-9]{3}[-]?[0-9]{1}[-]?[0-9]{2}[-]?[0-9]{6}[-]?[0-9]{1} Maximum length allowed is 17
Example: "123-4-56-789012-3"
price	FLOAT	Value must be a Float of min 0.000000 and max 50000.000000 Value is mandatory
Example: "97.99"
numberinstock	INTEGER	Value must be an Integer of min 0 and max 100
Example: "0"

Example JSON Output from API calls


{
  "id": 19,
  "type": "cd",
  "isbn13": "123-4-56-789012-3",
  "price": 97.99,
  "numberinstock": 0
}

Example XML Output from API calls


<item>
  <price>97.99</price>
  <numberinstock>0</numberinstock>
  <isbn13>123-4-56-789012-3</isbn13>
  <id>19</id>
  <type>cd</type>
</item>

Example JSON Input to API calls


{
  "id": 1,
  "type": "cd",
  "isbn13": "123-4-56-789012-3",
  "price": 97.99,
  "numberinstock": 0
}

Example XML Input to API calls


<item>
  <price>97.99</price>
  <numberinstock>0</numberinstock>
  <isbn13>123-4-56-789012-3</isbn13>
  <id>1</id>
  <type>cd</type>
</item>

API

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

End Points

/simpleapi/items

e.g. /simpleapi/items

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

e.g. /simpleapi/items?numberinstock=0

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. /simpleapi/items?_sortBy=+id

GET /simpleapi/items
- return all the instances of item

QUERY /simpleapi/items
- query all the instances of item 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 $['items'][?@['id'] == 'value'].

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

HEAD /simpleapi/items
- headers for all the instances of item

POST /simpleapi/items
- we should be able to create item without a ID using the field values in the body of the message. A maximum of 100 items is allowed.

OPTIONS /simpleapi/items
- show all Options for endpoint of /simpleapi/items

/simpleapi/items/:id

e.g. /simpleapi/items/:id

GET /simpleapi/items/:id
- return a specific instances of item using a id

HEAD /simpleapi/items/:id
- headers for a specific instances of item using a id

POST /simpleapi/items/:id
- amend a specific instances of item using a id with a body containing the fields to amend

PUT /simpleapi/items/:id
- amend a specific instances of item using a id with a body containing the fields to amend

DELETE /simpleapi/items/:id
- delete a specific instances of item using a id

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

PATCH /simpleapi/items/:id
- patch a specific instance of item with a body containing the patch details

/simpleapi/randomisbn

e.g. /simpleapi/randomisbn

GET /simpleapi/randomisbn
- return a random ISBN that can be used for testing purposes with the Simple API.

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