This is a short introduction to the basics of the Leaps API.

The examples assume that the Leaps system is portal.ff.geodis.com, but the same apply to other Leaps systems.

THIS SECTION IS NEW AND IS STILL UNDERGOING EDITING

Initial Configuration

In order to communicate with the Leaps API one needs a portal ID and a valid username / password on that portal. These three pieces of information should be stored in the external app, as they are used as identification against Leaps. Each component should be stored as strings.

Communication with the API is facilitated using JSON structures sent over HTTP(S). Therefore the external app should be able to handle both JSON data structures and HTTP(S) requests. The default character encoding is UTF-8.

The API is transactional meaning that every request is self contained, and so is the results returned. Each request are made up of an envelope, containing one or more commands.

The simplest of requests can look like this:

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

This request causes the API to respond with:

{"status":1,
 "msg":"OK",
 "results":[{"status":1,
             "answer":"Hello world"}],
 "date":"2013-01-01",
 "time":"09:25:47"}

Going over the request, it consists of first providing the four identifying parameters, and then an optional parameter remoteagent is used to identify the remote client. This makes debugging easier for Leaps personel when a lot of external systems are accessing the solution. The commands are then wrapped in the commands structure. In this example, only one command is given, but several commands could be given here.

The returned answer consists of an result envelope and the results lined up in the results structure. There is one result for each command passed.

Sending requests

Requests are preferably sent over HTTPS for security reasons, but can also be sent over normal HTTP with the normal risks of an unencrypted transaction.

The endpoint URL is https://portal.ff.geodis.com/api/endpoint.php and the request is passed as either a GET or POST parameter named json.

The example provided above, could be transmitted using GET as:

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

Common mistakes

Remember to URL-encode the parameter.

Remember that GET requests are limited in size. Prefer POST.

Remember that complex or large queries can take time to process, when setting timeouts.

Browser not supported