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

Resource	A collection of objects	A single object
GET	List the IDs and other details of the collection members	Retrieve a representation of the addressed member of the collection
PUT		Update the addressed member of the collection
POST	Create 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 Number	Description	HTTP Header Error
400	Bad Request	400
401	Unauthorized	401
403	Forbidden	403
404	Not Found	404
500	Internal Server Error	500
503	Service Unavailable	503
1000	Device not found	404
1001	Read only parameter	403
1002	Parameter not valid	403
1100	Folder not found	404
1101	Folder name already in use in the level selected	403
1102	Folder not empty	403
1200	User not found	404
1300	Support session not found	404

The error message is returned in the same format as the request.

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