Generated documentation

LabThings describes its HTTP API in two ways: with a Thing Description and with an OpenAPI document.

OpenAPI

OpenAPI is a standard way to describe an HTTP interface. It lists all of the possible HTTP requests that may be made, along with a description of each one, and a description of the possible responses. The OpenAPI document is generated automatically by fastapi, and may be downloaded at /openapi.json or viewed in a web browser at the /docs or /redoc endpoints of a running LabThings server. Both of the web browser views rely on JavaScript libraries that are not currently bundled with LabThings, so an internet connection is required to view them. The OpenAPI document is available without an internet connection.

Thing Description

Each Thing is documented by a Thing Description, which is a JSON document describing all of the ways to interact with that Thing (Interaction Affordances). The WoT standard defines the Thing Description and includes a JSON Schema against which it may be validated.

Thing Description documents are higher-level than OpenAPI and focus on the capabilities of the Thing. For example, they include a list of properties, where each action is described only once. LabThings treats the Thing Description as your public API, and as a general rule anything not described in the Thing Description is not available over HTTP.

Comparison of Thing Description and OpenAPI

Thing Description aims to be a neat way to describe the capabilities of a Thing, while OpenAPI focuses on detailed documentation of every possible interaction with the server. Thing Description is a newer and less well adopted standard that’s specific to the Web of Things, while OpenAPI has been around for a while and is widely used and understood as a general-purpose API description.

OpenAPI describes each HTTP endpoint individually. There are usually more HTTP endpoints than there are Interaction Affordances because a Property may have two endpoints, one to read its value and one to write it. Actions usually correspond to several endpoints; one to invoke the action, one to check the action’s status, one to cancel it, and another to retrieve its output once it has finished. In principle, client code based on a Thing Description should be more meaningful because related endpoints can be grouped together into properties or actions that correspond to structures in the programming language (like methods and properties in Python). However, OpenAPI is a much more widely adopted standard and so both forms of documentation are generated by LabThings-FastAPI.