...
| Description | JSON | XML |
|---|---|---|
| Format | {"total": <total toprocess>,"done": <done so far>} | <?xml version="1.0" encoding="UTF-8"?><response><total>total to process</total><done>done so far</done></response> |
| Example (Known) | {"total": 50123,"done": 10456} | <?xml version="1.0" encoding="UTF-8"?><response><total>50123</total><done>10456</done></response> |
| Example (Unknown) | {"done": 134} | <?xml version="1.0" encoding="UTF-8"?><response><done>134</done></response> |
| Example (Unknown) | {} | <?xml version="1.0" encoding="UTF-8"?><response/> |
200 OK: The standard payload is nothing for this status code. Many API calls will return a payload specific to the call.
201 Created: The standard payload for this status is the model and ID of the newly created entity, along with a URI to retrieve the details of the entity and the actual newly created entity. In addition, the URI will be in the Location: HTTP header. Specific calls may add an additional payload.
| JSON | XML | |
|---|---|---|
| Format | {"model": "<model name>","id": <id value>,"uri":http://<ip>/<plural-model-name>/<id>,"<model name>": { … }} | <?xml version="1.0" encoding="UTF-8"?><response><model>model name</model><id>id value</id><uri>http://<ip>/<plural-model-name>/<id>.xml</uri><model name> … </model name></response> |
| Example | {"model": "script","id": 45,"uri":"http://10.1.1.1/scripts/45""script": { "id":45, … }} | <?xml version="1.0" encoding="UTF-8"?><response><model>script</model><id>45</id><uri>http://10.1.1.1/scripts/45.xml</uri><script><id type="int">45</id>...</script></response> |
202 Accepted: The standard payload for this status is the same as for the 201 Created, except without the actual model data; it is the model and ID of the newly created entity, along with a URI to retrieve the details of the entity. The difference is that for a 201 Created code, the entity has already been created. For a 202 Accepted, the entity is in the process of being created. Thus, a request to the provided URL may return a 102 Processing instead of a 200 OK.
Just as with the 201 Created, the URI will be in the Location: HTTP header.
Specific calls may add an additional payload.
| JSON | XML | |
|---|---|---|
| Format | {"model": "<model name>","id": <id value>,"uri":"http://<ip>/<plural-model-name>/<id>"} | <?xml version="1.0" encoding="UTF-8"?><response><model>model name</model><id>id value</id><uri>http://<ip>/<plural-model-name>/<id>.xml</uri></response> |
| Example | {"model": "script","id": 45,"uri":"http://10.1.1.1/scripts/45"} | <?xml version="1.0" encoding="UTF-8"?><response><model>script</model><id>45</id><uri>http://10.1.1.1/scripts/45.xml</uri></response> |
301 Moved Permanently: No payload is present for this status code. The Location: header will indicate the redirect location. Typically used for a deprecated method that has a direct replacement.
400 Bad Request: The standard payload for this status code is an error code and message. The message may change based upon localization, therefore automated clients should use the error code. This basic format is called the error response format and is used for other 4xx status messages as well. See the following section, Standard Error Codes for details on the widely-used error responses.
| JSON | XML | |
|---|---|---|
| Format | {"error": "<error code>","message": "<errormessage>"} | <?xml version="1.0" encoding="UTF-8"?><response><error>error code</error><message>error message</message></response> |
| Example | {"error":"general/resource-in-use",message: "The requestedshared resource iscurrently in use. Pleasetry your request again ina few minutes."} | <?xml version="1.0" encoding="UTF-8"?><response><error>general/resource-in-use</error><message>The requested shared resourceis currently in use. Please try yourrequest again in a fewmintues.</message></response> |
The specific error codes returned will depend upon the API call, but certain error codes have pre-defined formats, as described below.
403 Forbidden: The standard payload is the error response format, with one of the following two error codes: “security/access-denied” or “security/authentication-required”.
404 Not Found: No standard payload is present for this status code, although some specific calls may define one.
409 Conflict: The standard payload is the error response format, which will include information on how to resolve the conflict.
410 Gone: This status code indicates that the API call requested is no longer available. A standard error/message payload may be present explaining the reason and providing direction for implementing the same functionality with the newer API.
413 Request Entity Too Large: The standard payload is the error response format, which will include details of what aspect of the request was too large (size or length of time, for example).