simplespec.md

Simple spec for small HTTP JSON APIs using JSON Schema

Throughout the spec we use JSON schema documents

Documentation

/docs serves a list of your endpoints.

["products", "orders", "customers"]

/docs?full=1 serves an object of all your endpoints with the full spec of each endpoint

{
  "products": "<products_spec>",
  "orders": "<orders_spec>",
  "customers": "<customers_spec>"
}

You can get the spec of individual endpoints by going to /docs/<name>:

For example, for /docs/products:

{
  "GET": {
    "description": "Fetch a single product by id.",
    "auth": "bearer",
    "query": {
      "required": ["id"],
      "id": {"type": "string"}
    },
    "responses": {
      "200": {"schema": "product"},
      "not_ok": {"schema": "general_error"}
    }
  },
  "PUT": {
    "description": "Save or update a product by id.",
    "auth": "bearer",
    "body": {"schema": "product"},
    "responses": {
      "200": {"schema": "product"},
      "not_ok": {"schema": "general_error"}
    }
  }
}

In the above, the "body", "query" entries, and "responses" are either JSON Schemas or references to schemas.

Schemas

/schemas serves a list of your template schemas, such as "product".

["product", "order", "customer", "general_error", "parameter_error"]

If you request /schemas?full=1, then you get an object with all schema data included:

{
  "product": "<product_schema>",
  "order": "<order_schema>",
  "customer": "<customer_schema>",
  "general_error": "<general_error_schema>",
  "parameter_error": "<parameter_error_schema>"
}

If you request /schemas/<name>, then you get the full JSON schema:

For example, for /schemas/product:

{
  "type": "object",
  "description": "A product that is offered for sale.",
  "properties": {
    "name": {
      "type": "string",
      "description": "Name of the product"
    },
    "id": { "type": "integer" }
  },
  "additionalProperties": false
}

API

/api serves the actual api, such as /api/products, /api/orders, etc as described in /docs.

For example, if you had an entry in /docs/customers, then the endpoint will be /api/customers.

Server status

/status Gives arbitrary server status (eg. version, repo url, status of connection to other servers, etc.)

/schemas/status Can give the JSON schema for the server status endpoint (optional)