Getting Started

Brain Web API

The Brain Web API is a RESTful API that allows your application to interact with our devices and Web services. All available data as represented by resources, can be accessed and manipulated over HTTP via resource URIs in a state-less operation and client-server communication architecture model.

URI format

The basic API URI format is as follows: scheme:[//host]path[?query]

Field	Example	Description
scheme	http or https	Brain uses Hypertext Transfer Protocol (Secure) as scheme
host	server.intellifi.nl	Address of the Brain server.
path	/api/resource-type/resource-id/	Path to resource-types and an individual resource. Each segment is separated with a slash (/).
query	?q1=value1&q2=value2	An optional query component that starts with question mark (?). Each extra query needs to be prefixed with an ampersand (&) delimiter for separation.

Full example: https://server.intellifi.nl/api/resource-type/?q1=value2&q2=value2

Resources

The Brain offers a collection of resource types. The lists below represents a limited overview. A full list can be found in the API itself using path /api or the Web API reference.

• spots: Smartspot device configuration and status.
• items: Items tagged with RFID, Bluetooth or other technologies.
• locations: Locations that can be used to report Items to.
• subscriptions: Event subscriptions and configuration.
• events: Events generated via the subscriptions.

Data encoding

The Web API uses JSON as its main encoding format. This means that the body for create and modify requests should be in JSON. The data of the returned responses is default returned as JSON but can be changed to CSV as well.

To change the output encoding to CSV, specify the .csv extension at the end of the path field for your URI. Example: https://server.intellifi.nl/api/resource-type.csv?q1=value1

Request methods

The following HTTP methods are generally supported across all resource types. It may also be possible that other HTTP methods are available for specific resources. Please see the Web API reference for more information.

• POST: Create a new resource.
• PUT: Modify one resource.
• GET: Get one, multiple or all resources.
• DELETE: Deletes a resource.

Required HTTP header

The following HTTP header needs to be added to all requests with a request body: 

Content-Type: application/json

Types of Access

All resource data

To access the data of a resource type, the path needs to contain the name of that resource type, for example items. Queries, depending on how specific they are, can return one, multiple or all resource data for that resource type. The following example returns all available data: https://server.intellifi.nl/api/resource-type

Single resource data

There are two options to access the data of a single resource:

1. Use the ID of the resource as query:
   • Format: https://server.intellifi.nl/api/resource-type?id={id}
   • Example: https://server.intellifi.nl/api/resource-type?id=5bb5eac4eb9a820e4940a9b7
2. Specify the resource ID at the end of the path:
   • Format: https://server.intellifi.nl/api/resource-type/{resource-id}
   • Example: https://server.intellifi.nl/api/resource-type/5bb5eac4eb9a820e4940a9b7

GET request

Returned data in case of the GET request on all resources within a resource type, use an envelope structure that contains a header and the result data. The header contains information about your request such as the total matches, number of returned resources and whether the returned data is paginated.

Pagination will occur when the amount of matching data is too large to return in a single response. The API returns the first chunk of data and offers a method the receive the following chunk for as long as needed to receive all data. For more information about pagination and how to use it see Pagination.

Note: When requesting a single resource using option 2 (see Types of Access above), won't return the data using this envelope structure.

API authentication

There are a two options to authenticate your application with the Web API. Both of these options use a API key. This key can be generated in User and API key management using the Management Console.

1. Add the HTTP Header X-Api-Key to the request and add the api key as header value,
   for example: X-Api-Key: 111111-2222-3333-444444444
2. Add the API key as query element to the URI,
   for example: https://server.intellifi.nl/api/resource-type/?key=111111-2222-3333-4444444444

A third way (but not meant for applications) is to login to the Brain Management Console. A session cookie will be created and grants you access to the API if you access it from your browser. Using this option, it's highly recommended to install a JSON viewer plugin to format the returned data. 

Advanced queries

Beside the standard queries using resource properties, the Brain offers advanced queries. More information about these queries and how to use them can be found in the Querying section.

Events and configuration

More information about how the Brain can generate events and how to configure this using event subscriptions can be found in the Events section.

Quick Start

OpenAPI Specification and Try-out

This API offers an OpenAPI specification and try-out that contains all detailed information about each resource type, their properties and how to access them. The specification file, generated reference documentation and try-out page can be found at intellifi-nl.github.io/brain-rest-api-spec and is also available on a Brain through the path /api-doc since Brain software version 2.8.0.

Tools

Here are a couple recommended tools that can help you to start discovering the web API capabilities without programming.

• Postman
• Curl