The purpose of this website is to fully describe the API of Odyssee: how it works, what you can do with it, the restrictions and some example code.
This website is composed of 2 parts :
- Help GuideAll information required to understand how the API works, how to commmunicate with it and how integration can be done.
- ReferenceGenerated documentation about the entities (objects), their properties (fields names and types) and their methods.
As a first quick exercise, let's build a request to the API together. Imagine you want to add a company to Odyssee each time a company is created in your ERP
A request to the API is always composed of 3 parts: 1) Request URL, 2) Header and 3) Body.
1) Request URL
To work on the companies use the following request Url :https://developers.odysseemobile.com/api/Company
As we are adding a created company, use the method POST
You need authentication to communicate with the API. (Go to "Authentification" for more info)
For this example we will use the following credentials :
Domain=TESTAPI , Username=APIUSer, Password=123456
Using the following format:
username:password@domain
filled with the above mentioned credentials, we get:
APIUser:123456@TESTAPI
If we then encode it in Base 64, we get:
QVBJVXNlcjoxMjM0NTZAVEVTVEFQSQ==
Finally the line on the header for authentification will be :
Authorization: Basic QVBJVXNlcjoxMjM0NTZAVEVTVEFQSQ==
Accept / Content-type : XML or JSON
The API support the 2 formats. By default and if nothing is found on the HTTP REQUEST, API will uses JSON.
If you want to receive data in XML format, use the following on the header
Accept: application/xml
If you want to send data (POST/PUT) in XML format, use the following on the header
Content-Type: application/xml
XML format is more easy to read, and used on this tutorial, let's use it.
Request Header
Authorization: Basic QVBJVXNlcjoxMjM0NTZAVEVTVEFQSQ== Accept: application/xml Content-Type: application/xml
I don't supply a line prefer: return=minimal
because i want to have the the full represention of the object when adding / updating and not just have the id. Returning only th id
should always beeing used when entity is not needed, for optimalization.
By browsing the Reference documentation of the API, you can determine the fields you need/want to use. For this exercise we will fill the following:
code, name,email,phone,vat_reg_code
For testing purposes, I will not specify the mandatory fields : sales_territory_id
and sales_organization_id
)
Request body
123456
Odyssee Mobile info@odysseemobile.com +32 2 513 48 19 BE0459288169
Let's test this URL, Header and Body and check the response message...
HTTP Error 422 sales_territory_id, sales_territory_code or sales_territory must be provided
As we can see, the API returns an error and a message (Go to "Handling error" for more info).
We need to fill the mandatory field sales_territory_id
.
Because I don't want to synchronize the object Territories or Organization, I will use the concept of embedded entities and just supply its code
.
All new database have by default 1 organization with code=DEFAULT
and 1 territory with code=DEFAULT
Request body
123456
Odyssee Mobile info@odysseemobile.com +32 2 513 48 19 BE0459288169 DEFAULT DEFAULT
The response we get now is the following:
HTTP Response 201.(Entity Created) with the objectfalse 12345678-1234-1234-1234-123456789012 123456
Odyssee Mobile ...21374b4a-0c88-4df3-bb6b-134cb62d2c70 0ea11d61-4e52-4eee-a945-bd8c26b52b45
As we can see, the id (PrimaryKey) has been filled and all properties are returned and
sales_territory+sales_organization_id
have been filled with their Guid Primary Key
Let's now verify the company has well been created.
For this we use the same Request URL but add the id of the company behind it, as follows:
Request Url :https://developers.odysseemobile.com/api/Company(12345678-1234-1234-1234-123456789012)
,
As we are now reading the database, the method used is GET
The response we get now is the following:
false 12345678-1234-1234-1234-123456789012 123456
Odyssee Mobile 2015-03-28T12:14:50.28Z ...
That's all !
In this example we have created a company in the odyssee database using an API call and then verified it was well created by our first call.
Congratulations, you have now done your 2 first API calls!