API: Basic concepts

An overview of the basic concepts of the Leaps API. The examples are based on the Geodis Leaps system, but the same applies to any other Leaps system, just replaced the URL etc.

Accessing the API

The API is accessed using the following URL:

https://portal.ff.geodis.com/api/endpoint.php

All communication with the API is facilitated using UTF-8 encoded JSON.

When communicating with the API, the JSON should be provided in the parameter json using either POST or GET ex.

https://portal.ff.geodis.com/api/endpoint?json=...

Other Leaps systems use other URLs.

Definitions

All communications are facilitated using JSON. In this documentation we use the following terms, to reference different JSON structures.

Set

A set is defined as field:value pairs, defined in JSON as:

{field1: value1, field2: value2,...}

A value can be a basic type, another set or a collection.

Collection

A collection is defined as a list of values, defined in JSON as:

[value1, value2,...]

A value can be a basic type, a set or another collection.

Basic types

The API uses the following basic types:

Type	Example	Format, when sending to API	Format, when receiving from API
string	Hello World	Hello World	Hello World
number (integer)	29	29	29
float	12.59	12.59 / 12,59	12.59
boolean	true	true / 1 / yes	1
	false	false / 0 / no	0
email	test@invalid.inv	test@invalid.inv	test@invalid.inv
date	5. august 2011	2011-08-05	2011-08-05
		05-08-2011
		5-8-2011
		05/08/2011
		(etc)
time	18:45	18:45:00	18:45:00
		18:45
		18.45
		(etc)
binary	N/A	N/A	N/A

Concept

The API is used to pass one or more commands to Leaps. The commands are given in a collection, which again is wrapped in an envelope containing identification information such as the API-key, user name and/or password.

When all commands has been executed, a structure is returned with the result of each command.

Envelope

All communication to the API must be contained in an envelope, as described in this section. The envelope is a set containing the following fields:

portal	string	A portal ID (provided by Geodis)
apikey	string	An API key (provided by Geodis)
username	string	A user name (provided by Geodis)
password	string	A password (provided by Geodis)
commands	collection	A collection of the commands which are to be executed.

The envelope can also contain the following field:

haltonerror	0 or 1	If set to 1, the API will halt execution if a command throws an error, otherwise the API will just continue to the next command (default behavior)
imei	string	If the client is a mobile phone, then the phone can identify itself using its phone number.
remoteagent	string	The API client can identify itself by providing a short identifier string, which will be recorded in the Leaps log and help troubleshooting.

An example envelope can look like this in JSON:

{"portal": "xxx","apikey":"","username":"xxx","password":"xxx","commands": []}

If there is an error in the envelope, the following set will be returned:

status	boolean	Always 0 when an error occurred.
msg	string	An error message.
date	date	The date on the server, when the envelope was received.
time	time	The time on the server, when the envelope was received.

If the envelope is correct, the following set will be returned:

status	boolean	Always 1 when envelope is correct. This isn't an indicator for whether the commands executed.
msg	string	OK
results	collection	A collection of results for each of the provided commands.
date	date	The date on the server, when the command execution started
time	time	The time on the server, when the command execution started

Command

A command is a set containing at least the following field:

command

string

The command to be executed.

The rest of the fields in the set is determined by the command executed.

If the command fails it will return the following set:

status	boolean	Always 0 when an error occurred.
msg	string	An error message.

If the command succeeds it will return a set containing at least the following field:

status

boolean

Always 1 when command succeeded.

The rest of the fields in the set is determined by the command executed.

Testing the API / Example

Connection to the API can be tested using the Echo command, which take a parameter text which is just returned as a result in the field answer.

The JSON for calling the Echo command looks like this:

{"portal":"X","apikey":"","username":"X","password":"X","commands":[{"command":"Echo","text":"Hello World"}]}

(remember to substitute the X's for the info received from Geodis).

Using GET the command can be executed calling this URL:

https://portal.ff.geodis.com/api/endpoint.php?json={"portal":"X","apikey":"","username":"X","password":"X","commands":[{"command":"Echo","text":"Hello World"}]}

Some of the characters should be encoded, so the URLs ends up looking like this:

https://portal.ff.geodis.com/api/endpoint.php?json=%7B%22portal%22%3A%22X%22%2C%22apikey%22%3A%22X%22%2C%22username%22%3A%22X%22%2C%22password%22%3A%22X%22%2C%22commands%22%3A%5B%7B%22command%22%3A%22Echo%22%2C%22text%22%3A%22Hello+World%22%7D%5D%7D

If the envelope is correct, the server will respond with:

{"status":1,"msg":"OK","results":[{"status":1,"answer":"Hello World"}]}

LEAPS - teknisk dokumentation