What's an API?

In computer programming, an application programming interface (API) is a set of subroutine definitions, protocols, and tools for building application software. In general terms, it is a set of clearly defined methods of communication between various software components. (Wikipedia)

In simpler terms:

• You use an API to submit a question to a server. That's the request.
• The server replies with an answer. That's the response.

Here we are focusing on Web APIs, also known as Web Services. More precisely, this article focuses on a particular (and the most popular) variant of Web APIs, known as*RESTful Web API/Services*. Therefore, we are going to talk about:

• sending an HTTP Web request, using either a GET or POST verb and some parameters
• receiving a response message either in JSON or XML format.

Once you figure out which API you want to use in Intuiface, you can go to the API Explorer article to see how to create the Interface Asset to access it.

Identify the API service you need

If you are using your own private API, jump to the next step

If you don't yet know which public API you are going to use, but you know you want to display a live weather forecast, sports results, stock exchange data, etc., you can search for it using your favorite search engine using the API keyword. For example:

• weather API
• real estate API

You'll likely find some useful results on the ProgrammableWeb website, a valuable resource for finding the best API for your needs.

Found an interesting API? Ask yourself these questions:

• About the service itself
  • Does it offer the service you are looking for?
  • Does the request support enough parameters to address all your scenarios?
  • Does the response contain all the information you require (and possibly even more)?
• About user accounts and pricing
  • Does the API require account creation? Accounts are typically required by APIs that enforce quotas on usage.
  • Is the API free to use? If not, does the free plan provide a quota large enough for your needs?
• Does the API use an authentication mechanism supported by Intuiface? See this section for details.

During your investigation, you will probably have to create several accounts to be able to test multiple services before choosing the right one. We recommend that you to create a dedicated email address to handle these accounts.

Find the right API documentation

Once you have identified which service you want to use, you need to find the API documentation. Use the keywords REST API documentation when performing your search. For example, in Google you could try:

• open weather map REST API documentation
• zoopla REST API documentation

Once you have found the documentation - e.g. current weather provided by OpenWeatherMap - find the Request URL. It can be displayed either as

• classic HTTP URL (GET requests only), such as api.openweathermap.org/data/2.5/weather?q=London
• cURL statement, such as the example below produced by Airtable

Both the HTTP URL and the cURL syntax are accepted by API Explorer.

Request Authentication

Once you have found the Request URL, you need to verify that it is ready to be pasted into the API Explorer.

Hint: if the URL contains something like YOUR_API_KEY, APIKEY, APP_ID or anything equivalent, it means you need to replace this generic part with your own credentials for this service.

Continuing with the above example from OpenWeatherMap, its API documentation illustrates how to include an account-specific API key in the request. We now have the following request URL: api.openweathermap.org/data/2.5/weather?q=London&APPID=123456789

If you try a request URL without any credentials while the service requires one, API Explorer will tell you that something is missing so you can fix it easily.

Request Methods

A REST-based Web Service uses an HTTP method, also known as an HTTP verb. Intuiface API Explorer currently supports the GET and POST verbs.

GET requests should only be used to retrieve information. This is the type of request performed by your Web browser when you navigate to a URL -> you get the content of a webpage to display in your browser. GET requests are sometimes used to send commands to a system since they are simple enough to be called directly from within a Web browser, no additional tool required.

POST requests are meant to send information to a server. For example, it could include the contents of a Web form.

You will not have to choose between GET or POST, you only need to follow the service documentation. If nothing is specified, consider it to be a GET request.

Request Parameters

A Web Service request is composed of:

• one host: the server address, ex: api.openweathermap.org
• one endpoint: the path to the Web Service you are targeting on the host, e.g.: data/2.5/weather
• zero or more parameters, e.g.: q=London&APPID=123456789

The parameters can be located in 4 different places:

• the query.
• the header.
• the body.
• the path, i.e. in the endpoint itself.

You can specify in API Explorer each parameter's location. See next sections for details.

Query parameter

A query parameter is embedded within the request URL. Each parameter is comprised of a name-value pair parameterName=parameterValue. The first parameter is located after the question mark ?, after the endpoint. Each additional query parameter is separated from the previous one with an ampersand &

All types of HTTP requests can have query parameters (e.g. GET, POST, ...)

Header parameter

A header parameter is not directly visible in the request URL but sent along with it. It is usually used for authentication parameters or to specify the expected response format

All types of HTTP requests can have header parameters (e.g. GET, POST, ...)

Body parameter

When using a POST request, you can also add some parameters in the request body. There are various existing formats but API Explorer currently only supports two: 1) x-www-form-urlencoded, and 2) raw JSON. The format will depend on the associated header:

• content-type=application/x-www-form-urlencoded header: each key-value pair is sent with an = symbol between key and value and a & between each pair.
• no header or content-type=application/json header: each key-value pair will be encapsulated in a JSON object.

Path parameter

A parameter can also be embedded in the endpoint itself and we will call it a Path parameter. It goes before any question mark ? after which you will find the Query parameters.
The creation of a Path parameter is a little bit different, since it can't be added after typing the host + endpoint values. See the animation below:

And what if the player is offline?

If a Player had Internet access then goes offline, each Interface Asset will keep the last response it received and will not update its data until the response is not an error.

What you can't do yet is:

• Relaunch the Player and still have the data
• While offline, re-send a REST request with the same parameters than a previous one (not the last) and use this previous respond we had for this request if offline.