In this document:
The following HTTP responses are used in the APS Protocol:
Code |
Explanation |
---|---|
Success, data returned |
|
Success, a new resource created |
|
Success, no data returned |
|
Success, partial data returned |
More details on HTTP/1.1 responses are available at RFC-2616-10.
When interacting with application endpoints, the APS controller expects the following response codes according to the operation.
Note
Any response code different from expected is considered a failure. In this case, the APS controller forwards the response to the initiator of the operation.
Operation |
Request operation |
Response code |
Description |
---|---|---|---|
POST |
200 OK
201 CREATED
202 ACCEPTED
204 NO_CONTENT
|
Resource created, properties returned
Resource created, properties returned
Operation in progress, async phase is required
Resource created, no properties returned
|
|
DELETE |
200 OK
204 NO_CONTENT
405 METHOD_NOT_ALLOWED
|
Resource deleted, no content returned
Resource deleted, no content returned
Method not allowed for the specified URL
|
|
PUT |
200 OK
204 NO_CONTENT
|
Resource updated, properties returned
Resource updated, no properties returned
|
|
POST |
200 OK
204 NO_CONTENT
|
Service upgraded, content returned
Service upgraded, no content returned
|
|
POST |
200 OK
204 NO_CONTENT
|
Event notification accepted
Event notification accepted
|
|
POST |
200 OK
204 NO_CONTENT
404 NOT_FOUND
405 METHOD_NOT_ALLOWED
501 NOT_IMPLEMENTED
|
Link established
Link established
Failure for unknown URL or unknown reasons
Method not allowed for the specified URL
Functionality not supported
|
|
DELETE |
200 OK
204 NO_CONTENT
404 NOT_FOUND
405 METHOD_NOT_ALLOWED
501 NOT_IMPLEMENTED
|
Link deleted
Link deleted
Failure for unknown URL or unknown reasons
Method not allowed for the specified URL
Functionality not supported
|
|
GET |
200 OK |
Resource properties including Counters usage are returned |
|
GET |
200 OK
204 NO_CONTENT
404 NOT_FOUND
405 METHOD_NOT_ALLOWED
501 NOT_IMPLEMENTED
|
Properties with default values are returned
No content returned
Failure due to unknown URL or unknown reasons
Method not allowed for the specified URL
Functionality not supported
|
|
GET |
200 OK
204 NO_CONTENT
404 NOT_FOUND
405 METHOD_NOT_ALLOWED
501 NOT_IMPLEMENTED
|
Environment configuration returned
No content returned
Failure due to unknown URL or unknown reasons
Method not allowed for the specified URL
Functionality not supported
|
Below is a detailed description of each HTTP response.
The request is successful. The information returned with the response depends on the method used in the request, for example:
GET: an entity corresponding to the requested resource is sent in the response.
PUT: a resource property was updated.
In the following example, the properties of a resource are requested.
Request:
GET /aps/2/resources/60a8e022-abac-4f79-9048-076716ab4b36
Accept: application/json
Response:
HTTP/1.1 200 OK
Content-type: application/json
Content-length: 1234
{
...
The request was successful and resulted in the creation of a new resource.
The newly created resource can be referenced by the URL(s) returned in the entity of the response,
with the most specific URL for the resource given by the Location header field.
The response must include an entity containing a list of resource characteristics and locations
from which the user or user’s agent can choose the one most appropriate.
The entity format is specified by the media type given in the Content-Type
header.
The origin server must create the resource before returning the 201 status code.
Request:
POST /aps/2/resources
Content-type: application/json
Content-length: 1234
{
...
}
Response:
HTTP/1.1 201 Created
Content-type: application/json
Content-length: 1234
Location: /aps/2/resources/60a8e022-abac-4f79-9048-076716ab4b36
{
...
}
The server has fulfilled the request but does not need to return an entity body. The 204 response must not include a message body, therefore it is always terminated by the first empty line after the header fields.
Request:
DELETE /aps/2/resources/60a8e022-abac-4f79-9048-076716ab4b36
Response:
HTTP/1.1 204 No Content
The server has fulfilled the partial GET request for the resource.
The request must have a Range header field (RFC-2616
section 14.35) indicating the desired range,
and may have an If-Range
header field (RFC-2616 section 14.27) to make the request conditional.
The response must include the Content-Range
header (RFC-2616 section 14.16) indicating
the range included with this response, or a multipart/byteranges Content-Type
including Content-Range
fields
for each part. If the Content-Length
header is present in the response, its value must match the actual number
of OCTETs transmitted in the message body.
A cache must not combine a 206 response with other previously cached content.
A cache that does not support the Range
and Content-Range
headers must not cache 206 (Partial) responses.
Request:
GET /aps/2/resources?start=0&limit=10
Response:
HTTP/1.1 206 OK
Content-Type: application/json; charset=UTF-8
Content-Range: items 0-9/100
...
[
...
]
If an error occurs on the application side, the APS controller expects to receive a JSON object containing
the error
and message
fields:
error
: the identifier of the error message
message
: message text; it can be used as a translation key if needed
For example:
HTTP/1.1 500 Internal Server Error
{
"message": "Internal Server Error: Resource repository is exhausted on the remote Application side",
"error": "ApplicationUnknownError",
}
In the endpoint PHP code, to return an error message, you can throw an exception as in following example:
throw new \Exception("Resource repository is exhausted on the remote Application side");
The possible cases are compiled in the table.
APPLICATION RESPONSE |
APS CONTROLLER RESPONSE |
---|---|
{
“error”: “FailedToDoWhatIWanted”,
“message”: “This message should be shown to the user”
}
|
{
“error”: “FailedToDoWhatIWanted”,
“message”: “This message should be shown to the user”
}
|
<some>xml</some> |
{
“error”: “ApplicationUnknownError”,
“message”: “<some>xml</some>”
}
|
{
“error”: “FailedToDoWhatIWanted”
}
|
{
“error”: “FailedToDoWhatIWanted”,
“message”: “Application returned error with an empty message”
}
|
{
“message”: “Show something to the user”
}
|
{
“error”: “ApplicationUnknownError”,
“message”: “Show something to the user”
}
|
|
{
“error”: “ApplicationUnknownError”,
“message”: “Application returned error with an empty message”
}
|