Getting Started

The Unikey Public API connects your website or application to the Kevo ecosystem.

Below, you will find a collection of guidelines and tips on header use, request formatting, and general API usage that will be useful in avoiding common problems while building your Unikey Public API integration.

The Basics

The Unikey Public API is an OAuth 2.0-authenticated, RESTful JSON API.

Sending Requests

The vast majority of endpoints within the API are configured using the following guidelines. If an endpoint breaks with the conventions outlined below, the endpoint’s documentation will highlight this divergence from the norm.

Expected Headers

All calls made to the API must display the following headers to remain valid:

Please refer to the OAuth page for info on ACCESS_TOKEN.

HTTP Verbs

The API accepts calls using the following http verbs.

Requests on a Specific Entity Item

The API demands that requests concerned with acting on a single resource instance, regardless of action, follow the RESTfull standard:

Primary resource:

/resource-name/{resource-id}

Child resource:

/parent-resource/{parent-id}/child-resource/{child-id}

The id reference for a resource MUST be inserted into the URL and NOT provided as a property in the JSON request body.

Correct Example:

Request Method / URL:

GET /ekeys/c23a1bd9-e512-49b1-9855-882d43a71873

Incorrect Example:

Request Method / URL:

GET /ekeys

JSON Request Body:

{
  "id": "c23a1bd9-e512-49b1-9855-882d43a71873"
}

Correct Example:

Request Method / URL:

PUT /ekeys/c23a1bd9-e512-49b1-9855-882d43a71873

JSON Request Body:

{
  "name": "New eKey Name",
  "type": "guest"
}

Incorrect Example:

Request Method / URL:

PUT /ekeys

JSON Request Body:

{
  "id": "c23a1bd9-e512-49b1-9855-882d43a71873",
  "name": "New eKey Name",
  "type": "guest"
}

JSON Formatting Conventions

The API both expects and returns lower_snake_case key names in JSON communications.

JSON Request Conventions

Behavior of null Property Values in Update Requests

The API is configured to intrepret a null property value differently than a missing property value.

Intended Behavior:

- Property Value == null: Reset the indicated property to its default value.

- Property Value == missing: Leave the property unchanged.

Value(s) Reset to Default:

Request Method / URL:

PUT /ekeys/c23a1bd9-e512-49b1-9855-882d43a71873

JSON Request Body:

{
  "name": "New eKey Name",
  "schedule_start": null,
  "schedule_end": null
}

Changes name to “New eKey Name” and resets schedule_start and schedule_end to their default values.

Value(s) Left Unchanged:

Request Method / URL:

PUT /ekeys/c23a1bd9-e512-49b1-9855-882d43a71873

JSON Request Body:

{
  "name": "New eKey Name"
}

Changes name to “New eKey Name” and leaves schedule_start and schedule_end unchanged.

JSON Response Conventions

References to Related/Child Objects

The standard approach within API for illustrating relationships between resource objects is illustrated using a Primary/Foreign Key model. The id of the related resource will be present as a foreign key in the primary resource’s response object and any referenced id will usually be among the last properties returned within a response object. Typically, the API will NOT nest the data of any related resource objects within the response unless it is to improve the performance of certain operations. If an endpoint breaks with this convention, its documentation witll highlight the fact.

Correct Example

JSON Response Body:

{
  "id": "c23a1bd9-e512-49b1-9855-882d43a71873",
  "name": "eKey Name",
  "lock_id": "65f1daa2-1a4e-488a-ad46-07a375bc743c"
}

Incorrect Example

JSON Response Body:

{
  "id": "c23a1bd9-e512-49b1-9855-882d43a71873",
  "name": "eKey Name",
  "lock": {
    "id": "65f1daa2-1a4e-488a-ad46-07a375bc743c", 
    "name": "Test Lock"
  }
}

¹ This code will be what was returned from the OAuth token grant API.

² This header is optional, but it is useful for internal record-keeping purposes and including it is encouraged!