Introduction
Request Types
NTRglobal API attemps to conform to the design principles of Representational State Transfer (REST). REST is a design pattern based on simplicity and how Web pages work - it is a HTTP GET or POST action.

The NTRglobal REST Endpoint URL is https://apifree.ntrglobal.com/

To request a device object with the identifier 3120 in XML format, invoke it in this way using a HTTP GET:

https://apifree.ntrglobal.com/devices/3120.xml To request a collection of devices in JSON format, invoke it in this way:

https://apifree.ntrglobal.com/devices.json The following table shows how the HTTP protocol verbs which are typically used to implement NTR global API


ResourceA collection of objectsA single object
GETList the IDs and other details of the collection membersRetrieve a representation of the addressed member of the collection
PUT Update the addressed member of the collection
POSTCreate a new entry in the collection. A new ID is assigned and returned by the operation. 
DELETE Delete the addressed member of the collection.
In order to create a member or update an existing member of a collection we need to specify the data in the body of the request in XML or JSON format.


This format must be specified in the content/type header of the HTTP request.


More information about REST can be found here:
http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm



Response Types
The NTRglobal API provides you with several response types, depending on your skills and preferences you can use:

  • XML
  • JSON
All responses are UTF-8 encoded.

How to Specify a Response Type

In order to specify the response type you have to add it to the end of the URL like if it were the extension of a file. If it is not specified by default, the response will be in XML.

https://apifree.ntrglobal.com/devices.xml
https://apifree.ntrglobal.com/devices.json
Request and response Content Type

The response indicates the response type in the HTTP Content-Type header:

  • XML: Content-Type: application/xml
  • JSON: Content-Type: application/json
Note: this header is mandatory in POST and PUT operations because you need to identify the format of the request body.



Error Codes
All methods from the NTRglobal API should have a common response status codes based in HTTP status standard codes (RFC2616). Any application that understands HTTP error codes will be able to collect API errors.

Error NumberDescriptionHTTP Header Error
400Bad Request400
401Unauthorized401
403Forbidden403
404Not Found404
500Internal Server Error500
503Service Unavailable503
1000Device not found404
1001Read only parameter403
1002Parameter not valid403
1100Folder not found404
1101Folder name already in use in the level selected403
1102Folder not empty403
1200User not found404
1300Support session not found404
The error message is returned in the same format as the request.

<error>
        <code>1001</code>
        <description>Unrecognized argument</description>
</error>