Developer Hub

Welcome to the EVRYTHNG Developer Hub! Here you will find all the information you need to create your EVRYTHNG apps and integrations. We have conceptual guides, walkthroughs, and tutorials as well as a complete API reference.

Featured Pages

Swagger API Description

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

This means that it is possible to automatically generate documentation, as well as tools, server/client code, tests, automation, and more using only the Swagger file to drive the requests themselves.


EVRYTHNG Swagger File

The Swagger file describing the EVRYTHNG API can be found in the swagger GitHub repository.

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

npm i --save evrythng-swagger

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


Anatomy

The Swagger file (swagger.json) describes all the endpoint, parameters, and payloads 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 a Swagger 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.",
      "schema": { "$ref": "#/definitions/KeyAccessDocument" },
      "examples": {
        "application/json": {
          "account": "UFNCRXfCVM87QNawaE8rrKqc",
          "actor": {
            "type": "operator",
            "id": "U2NCaXfCBgPaQ5wRwhTsWnmc"
          }
        }
      }
    }
  },
  "x-api-keys": [ 
    "Operator", "Application", "Trusted Application", "Application User", "Device" 
  ]
}

A reference to schema objects is implemented via the $ref keyword, referencing an object elsewhere in the file, such as the definitions object. In the case of the example above the definition of the KeyAccessDocument object can be found:

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

These definitions detail which fields are expected and allowed for each request
or response payload schema, which documentation generators can use to guide users, and tests/tools can use to intelligently make and process API requests and responses.


Extensions

The following vendor-specific extensions are implemented:

x-api-key

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

x-filterable-fields

Details which fields on each resource type are filterable using filters.