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
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:
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:
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.
The error message is returned in the same format as the request.
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. |
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
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
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 |
<error> <code>1001</code> <description>Unrecognized argument</description> </error>