OpenAPI Description

OpenAPI is an API description format that is readable both by humans and machines. The description file (the spec file) is written in JSON (specifically JSON Schema) or YAML and contains all the details of a REST API for every available type of request and response.

This means you can autogenerate documentation, tools, server/client code, tests, automation, and more using only the OpenAPI spec file to drive the requests.

---

EVRYTHNG OpenAPI File

The OpenAPI file describing the EVRYTHNG API can be found in the openapi GitHub repository.

You can also import it as an npm module for JavaScript and Node.js projects:

npm i --save evrythng-swagger

This can extend and build upon the EVRYTHNG API in an automated and reliable fashion, using your favourite Swagger/OpenAPI ecosystem clients, tools, and documentation generators of choice besides those that we provide, such as Swagger UI.

---

Anatomy

The main file (openapi.json) describes all the endpoints in the EVRYTHNG
API. These are listed in the paths object:

"paths": {
  "/access": {
    ...
  },
  "/accesses": {
    ...
  },
  "/accesses/{accessId}": {
    ...
  },
  ...
}

For each endpoint, each available HTTP method is listed as an operation:

"/access": {
  "get": {
    ...
  },
},
...

Each operation contains the information about that request, including
parameters, payload schemas, response codes, response schemas, and example
responses:

"get": {
  "tags": [
    "Access"
  ],
  "summary": "Read key access information",
  "description": "Read key access information for the authenticating key.",
  "responses": {
    "200": {
      "description": "The access information for the authenticating key.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/KeyAccessDocument"
          },
          "example": {
            "account": "UFNCRXfCVM87QNawaE8rrKqc",
            "actor": {
              "type": "operator",
              "id": "U2NCaXfCBgPaQ5wRwhTsWnmc"
            }
          }
        }
      }
    }
  },
  "x-api-keys": [
    "Operator",
    "Application",
    "Trusted Application",
    "Application User",
    "Device"
  ],
  ...
}

A reference to schemas objects is used through the $ref keyword, referencing an
object elsewhere in the file, such as components/schemas. In the
example above (KeyAccessDocument):

"components": {
  "schemas": {
    "KeyAccessDocument": {
      "additionalProperties": false,
      "type": "object",
      "description": "Object describing the account and actor associated with a key",
      "properties": {
        "account": {
          "type": "string",
          "description": "Account ID for this key",
          "readOnly": true,
          "pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$"
        },
        "actor": {
          "$ref": "#/components/schemas/ActorDocument"
        }
      }
    },
    ...
  },
  ...
}

These definitions detail which fields are expected and allowed for each request
or response payload schema, using the standard JSON Schema format. See the
OpenAPI specification for more information about the structure of an API spec.

Extensions

The following vendor-specific extensions are implemented:

x-api-keys

Details which API keys can be used for this operation. Possible values are:
Operator, Application, Trusted Application, Application User, and
Device. See the
API Keys and Key Permissions
page in the EVRYTHNG Developer Hub for more information about API keys.

x-filterable-fields

Details which fields on this resource are filterable using
filters.