Odyssee Mobile

API User Guide

XML and JSON are both designed to form a simple and standardized way of describing different kind of hierarchical data structures and to facilitate their transportation and consumption in a standardized way.

The Odyssee API is compatible with both formats. But there are some limitation with XML especially with ODATA (Paging and $select).

If you do not have any specific requierments, we suggest using JSON, for the following reasons:

  • Light : the lenght of the message will be smaller than using XML
  • Popular : you can find a lot of tools and libraries on the Internet to easily manipulate JSON objects
  • OData Paging : Paging is working direclty and you have the @odata.nextLink field on the HTTP Result
  • OData Select : ou can use the $select statement on the URL


Take a look at the following example:

XML :

<employees>
    <employee>
        <name>John Crichton</name>
        <gender>male</gender>
    </employee>
    <employee>
        <name>Aeryn Sun</name>
        <gender>female</gender>
    </employee>
</employees>

JSON :

{
    "employees": [
    {
        "name": "John Crichton",
        "gender": "male"
    },
    {
        "name": "Aeryn Sun",
        "gender": "female"
    }
    ]
}


XML: Extensible Markup Language

  1. An open standard for describing data defined by the World Wide Web Consortium (W3C).
  2. XML lets Web developers and designers create customized tags that offer greater flexibility in organizing and presenting information.
  3. XML defines rules to mark-up a document in a way that allows the author to express semantic meaning in the mark-up. XML does not necessarily restrict the author to certain tags (elements) as HTML does.
  4. XML defines rules to mark-up a document in a way that allows the author to express semantic meaning in the mark-up. XML does not necessarily restrict the author to certain tags (elements) as HTML does.
  5. Internet media type: application/xml

Because XML can include requirements that can brings bugs and make the work of developpers harder, we adapt our API to make life easier.
2 concepts on XML API are not applied here:

  1. Following XML Schema when doing POST/PUT
  2. The order of the field on the XML is not important on this API.
  3. Namespace on XML declaration
  4. There is no need to specify a namespace on the request body, like
    <jobs xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
        <name></name>
        ...
    </jobs>
    
    You can avoid it , like
    <jobs>
        <name></name>
        ...
    </jobs>
    

JSON: JavaScript Object Notation

  1. A lightweight text-based open standard designed for human-readable data interchange.
  2. A text-based format for exchanging objects.
  3. It is an alternative to XML that is more concise because, unlike XML, it is not a markup language that requires open and close tags.
  4. It is derived from the object literals of JavaScript.
  5. Design goals were for it to be minimal, portable, textual, and a subset of JavaScript.
  6. Internet media type: application/json