API BASICS
API BASICS

API Architecture

The ON!Track Unite APIs are built around REST architecture and are specified to be compliant with the Open API (Swagger) format. All communications are done over SSL with a fine-grained access control system and encoded in JSON (including error codes).

API Versioning

ON!Track Unite follows the path-based major version pattern to indicate the backward compatibility with other systems using the following pattern:

/unite/v{api_version}/{resource}

An API does not introduce any breaking change within the same major version it may however introduce minor and backward compatible changes and deprecations over time. Once the next major API version is planned and implemented, it will follow the same versioning policies during its introduction and lifetime.

Breaking changes are:

    removing a path
    removing a method
    changing a property from optional to required in a request body
    changing a property from required to optional in a response body

Non-breaking changes are:

    adding a path
    adding a method
    changing a property from required to optional in a request body
    changing a property from optional to required in a response body

API Lifecycle

At most two versions of the same API endpoint can co-exist at any time.

A new version of an existing API is announced 3 months before its release; after that, the old version is kept in a deprecated status for 12 months and in a retired status for 3 months before being finally decommissioned.

Versioning

Active

An active API version is the current and fully supported API. It is the recommended version for general consumption.

An API in this status is deployed on the production environment and will eventually be deprecated when superseded by a newer major version.

Full documentation is provided for this version, which is available at the day of launch. It supports bug fixes, security patching, and new features. The launch is planned to happen 3 months before the active version is deprecated.

Deprecated

A deprecated API version has been suppressed by a newer API version. It is recommended to refer to the active version for consumption. This type is deployed on the production environment along with its successor API.

This version provides full documentation, and it is supported for 12 months from the deprecation date. Bug Fixes will be applied for 6 months. New consumers will be denied access to deprecated APIs after a 3 months grace period.

Retired

A retired API version is no longer supported. It includes any API that has been deprecated for more than 12 months. Any consumer using a retired API must migrate to an active API during the 3-months period. This type is deployed on the production system in the production stage along with its successor API and will eventually be decommissioned.

This version provides full documentation. New consumers will be denied access to retired APIs. Notifications regarding the retirement are announced 180 respective 90 days before retirement. The retirement itself is also announced.

Decommissioned

A decommissioned API version is no longer available on production. This occurs after three (3) months of inactivity in Retired state. Neither documentation nor support for this version is provided. Notifications are sent out 90 days before decommissioning.

RESTful concepts

For the ON!Track Unite APIs a data-oriented design paradigm is followed, as it is the natural way to expose data over the internet. It is a widely adopted industry standard and is the recommended way to design applications that are meant to leverage the basic building blocks of the web like the Uniform resource identification as described in RFC3986 or the HTTP protocol - RFC7230.

Resources

The ON!Track Unite solution is designed and built around the REST architectural style as described by Roy Fielding.

HTTP Methods

The following table provides an overview of the general concept of HTTP Verb usage in ON!Track Unite. It covers the basic CRUD operation definition, yet custom methods are also supported in specific use cases.

MethodHTTP VerbDescription
ListGETRetrieve a list of resources and apply collection patterns, e.g. filter.
GetGETRetrieve a single resource using an identifier, e.g. the resource id.
CreatePOSTCreate a new resource within the respective collection providing required data.
UpdatePUTUpdate a existing resource identified by the resource URI, e.g. /assets/123.
DeleteDELETEDelete a resource from the system identified by its resource URI.

HTTP Status Codes

The following table gives you an overview of the general usage of HTTP status codes in Unite and their association with the respective methods and operations.

MethodHTTP VerbError Codes
ListGET200, 401, 403, 500
GetGET200, 401, 403, 404, 500
CreatePOST200, 201, 400, 401, 403, 409, 422, 500
UpdatePUT200, 204, 400, 401, 403, 409, 422, 500
DeleteDELETE204, 400, 401, 403, 404, 500

The error code 429 is given when the throttling limits have been reached.

Error Handling

For Unite we use the IETF standard Problem JSON for the representation of API errors mentioned before. This allows participants to quickly identify the most important information necessary to resolve the problem.

{
  "type": "https://ontrack3.hilti.com/problem/bad_request",
  "title": "Bad Request",
  "status": 400,
  "detail": "The server could not understand the request due to invalid syntax.",
  "instance": "/assets/123",
  "errors": [
    {
      "code": 20178,
      "message": "Scan code and Inventory number cannot be identical",
      "fieldName": "scanCode/inventoryNumber"
    }
  ]
}

API Design Patterns

Pagination

A query-based approach to pagination using the offset and limit parameters is used as opposed to the page-based approach. All listable collections support pagination through the pagination fields and provide the results within a metadata envelope.

offset: Integer value, defaults to 0. limit: Integer value, defaults to 50.

Example Request:

The following request will receive the first 50 items from the assets collection.

GET /unite/v1/assets?offset=0&limit=50 HTTP/1.1
Host: localhost

Example Response:

For collection listings, a standard envelope providing metadata about the collection as a utility is provided.

200 OK

{
    result: [Array of Resources],
    offset: 0,
    limit: 50,
    totalRecords: 100
}

Result Ordering

All listable collections support result ordering, irrespective of the collection size. The List method supports it through the orderBy field. The default sorting order is ascending (+) and can be descending (-) too. Sorting by multiple fields is supported with comma-separated fieldnames. The sorting uses semantics equal to the filter expressions. This means you can use the sorting order only once. The default sorting order is ascending.

?orderBy=stringValue

Examples:

    “?orderBy=firstName”  ascending by default
    “?orderBy=+firstName” ascending
    “?orderBy=-firstName” descending

Filter and queries

Unite provides functionality to filter or search queries for lists of data provided by the Unite API. Please use the following Syntax get more detailed requested results.

Syntax for filter/query parameter Filters can only be used for the exact value which is filtered for. For a query free text values can be used.
  • Filter parameter: ?filter=attributeToFilterBY:eq%3DstringValue
  • Query parameter: ?query=stringValue

Examples:

    “?filter=model:eq%3DAnglegrinder ABC” filter by model "Anglegrinder ABC"
    “?query=Hilti” search by text "Hilti"

Useful links to standards