HTTP and Web API

Introduction

Web APIs use HTTP to communicate. HTTP governs all communications on the internet by describing a method for exchanging files on the network (HyperText Transfer Protocol). These files can be in any digital format possible.

HTTPS is the secure version of the protocol. It uses x509 security certificates to certify communications. In general, API providers use globally trusted certificates, but in some cases it will be necessary to manually approve them on the platform.

Using the secure version of the protocol is highly recommended, it provides the same level of security as a VPN!

Protocol Details

Queries

The protocol requires four elements to configure a query:

1. A URL that locates a resource.

2. A method that defines the query type.

3. Headers that configure the query.

4. A request body that contains the content to send.

The URL

The URL contains

• The address of the host, the server (hostname):

an IP address or domain name to identify the physical address of the service to contact. examples: btib.fr, backend.sigfox.com or 192.168.3.56.

• The access route (query or path):

This is the path to the requested resource, like files on a computer.
This query, often also called URI, allows a piece of data to be located. It does not necessarily represent a file on the server, most often it is a calculated resource.
examples: /api/v1/btib.json or/api/v1/data

• The parameters:

Most often used to modify the conditions for calculating the data transmitted by the server. examples: limit=10 or lang=FR

The Method

The method is the request type. There is a limited number of these. As stated in the table below, some methods do not accept body parts and the first 4 methods are used in RESTful APIs.

For more information about HTTP methods, refer to the following article: Wikipedia

Headers

Headers are pairs of types {key, value}. The pairs have been standardized by the IETF and a non-exhaustive list is available at this address: Wikipedia

Headers, although standardized, can also be specifically defined by a service. These specific headers often have a name that includes an ' X- ' prefix, which makes it possible to quickly differentiate them from standard headers.

examples:

`Authorization: Bearer aWdyempnaGpzqIGVjdnRqsaGd ........ Ynpqa2doa2ZXRoZ2JmbHplamNucmZqemxrc2Vm`
`Content-Type: application/json`

Body

Contains the data to transfer. This may be bytes representing any file or a text representing structured data such as JSON. We will return to this last category later.

The body is considered to be the message for writing requests, (mainly POST and PUT).

Read requests rarely contain a body, all parameters are sent in the url or the headers, (GET is the reading method).

Responses

Responses contain the following elements:

1. A code that indicates the processing status of the request.

2. Headers that parameterize the response and provide information about its content.

3. A response body that contains the content.

Status Code

This can be a value between 100 and 600. Each one hundred corresponds to a different main status. For example the 2xx represent successes, while 4xx are resources not found. Each error code has a message.

For a detailed list, refer to the following article: Wikipedia.

Headers

See the previous section.

Body

See the previous section.

The JSON Format

JSON allows the formatting of 6 different types of data. Hereinafter we will call any type of data in JSON a value.

A JSON file represents a jumble of objects and tables that contain values.

• An Object contains a key -> value association table. The key is a representation in the form of a text.
  It appears in a JSON file in the format: {"key": value, "key2": value2}, (keys in quotation marks followed by a colon and a value. Each pair is separated by a comma.)

• An Array contains a list of values, regardless of type.
  It appears in a JSON file as: [value1, value2], (square brackets containing a comma-separated list of values).

• A Boolean contains a Boolean value (true or false).
  It appears in a JSON file as: true or false.

• A Number contains a numeric value, which can be floating.
  It appears in a JSON file as: 1234.56, (decimals are denoted by a period, not a comma),

• A String is a chain of characters. It appears in a JSON file as: "my-text", (the text is enclosed between quotation marks).

• A null. The reserved keyword null encodes empty data, (not to be confused with "null" which is a non empty text).

example:

{
	"fruits": [
		{ 	
			"kiwis": 3,
			"mangos": 4,
			"apples": null
		},
		{ 	
			"basket": true 
		}
	],
	"vegetables": {
		"potatoes": "amandine",
		"leeks": false
	},
	"meats": ["fish","chicken","beef"]
}

 
For more details on the JSON format: JSON.org

The NDJSON Format

For performance reasons, the json returned by the API can be a NDJSON, a Newline delimited JSON.
For example:

The RestNetwork will handle this format as an array of json elements.
The above JSON will be transformed to 

[
  {"some":"thing"},
  {"foo":17,"bar":false,"quux":true}, 
  {"may":{"include":"nested","objects":["and","arrays"]}}
]