Bookstore API

About this demo

This site is the living demo of periwinkle, a static API documentation generator for OpenAPI 3.x. It is built from a fictional bookstore contract on every push to main.

Get the source and usage instructions at github.com/phranck/periwinkle.

Integration guide

Integration essentials

Authentication

Never expose credentials in browser code.

Send the X-API-Key header with every request (scheme ApiKeyAuth). API key issued per account.
Send an Authorization: Bearer <token> header with every request (scheme BearerAuth). OAuth access token.

Requests

Use JSON request bodies and read JSON responses from https://api.bookstore.example.

Errors

Errors use standard HTTP status codes. Each operation below documents its error responses.

Rate limits

This is a demo deployment of a fictional API, so there are no real rate limits.

Versioning

This reference is generated from API version 1.2.3.

OpenAPI contract

The public OpenAPI contract is available at /periwinkle/openapi.json.

Authenticated request

# Requires the API key to be set in your shell environment.
curl https://api.bookstore.example/resource \
  -H "X-API-Key: ${API_KEY}" \
  -H "Content-Type: application/json"

Books

Browse and manage books.

All books

List all books

Parameters

limitquery: Maximum number of books to return.

Responses

200

A page of books.

Content-Type:application/json

Example request

curl "https://api.bookstore.example/books" \
  -H "X-API-Key: $API_KEY"

Create Book

POST/books Authentication required

Create a book

Request body

The book to create.

application/jsonBookInput

Responses

201

The created book.

Content-Type:application/jsonResponse Object:Book

400

Validation failed.

Content-Type:application/jsonResponse Object:ErrorResponse

Example request

curl -X POST "https://api.bookstore.example/books" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Fetch a single book

Fetch a single book, with reviews included (verbose)

Parameters

idpathRequired: Book identifier.

Responses

200

The requested book.

Content-Type:application/jsonResponse Object:Book

404

Not found.

Example request

curl "https://api.bookstore.example/books/{id}"

Authors

Author directory.

List Authors

List all authors

Responses

200

All authors.

Content-Type:application/json

Example request

curl "https://api.bookstore.example/authors" \
  -H "X-API-Key: $API_KEY"

Other

Search

Search books and authors

Parameters

qqueryRequired: Search phrase.

Responses

200

The best match.

Content-Type:application/jsonResponse Object:BookResponse Object:Author

Example request

curl "https://api.bookstore.example/search" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Schemas

Author

A book author.

Key	Key Presence	Value Type	Description
`id`	included	`integer`	None
`name`	included	`string`	None
`website`	optional	`string \| null`	None

{
  "type": "object",
  "description": "A book author.",
  "required": [
    "id",
    "name"
  ],
  "properties": {
    "id": {
      "type": "integer"
    },
    "name": {
      "type": "string"
    },
    "website": {
      "type": "string",
      "nullable": true
    }
  }
}

Book

A single book in the catalogue.

Key	Key Presence	Value Type	Description
`id`	included	`integer`	Unique identifier.
`title`	included	`string`	Display title.
author	optional	`Author`	A book author.
`id`	included	`integer`	None
`name`	included	`string`	None
`website`	optional	`string \| null`	None
category	optional	`Category`	Hierarchical catalogue category.
`id`	included	`integer`	None
`name`	included	`string`	None
parent	optional	`Category`	Hierarchical catalogue category.
`tags`	optional	`string[]`	None
`rating`	optional	`number \| null`	Average rating, when rated.

{
  "type": "object",
  "description": "A single book in the catalogue.",
  "required": [
    "id",
    "title"
  ],
  "properties": {
    "title": {
      "type": "string",
      "description": "Display title."
    },
    "id": {
      "type": "integer",
      "description": "Unique identifier."
    },
    "author": {
      "$ref": "#/components/schemas/Author"
    },
    "category": {
      "$ref": "#/components/schemas/Category"
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "rating": {
      "type": [
        "number",
        "null"
      ],
      "description": "Average rating, when rated."
    }
  }
}

BookInput

Key	Key Presence	Value Type	Description
`authorId`	optional	`integer`	None
`title`	included	`string`	None

{
  "type": "object",
  "required": [
    "title"
  ],
  "properties": {
    "title": {
      "type": "string"
    },
    "authorId": {
      "type": "integer"
    }
  }
}