HTTP Responses

Response Groups

The following HTTP responses are used in the APS Protocol:

Code	Explanation
200 OK	Success, data returned
201 Created	Success, a new resource created
204 No Content	Success, no data returned
206 Partial Content	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
provision	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
unprovision	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
configure	PUT	200 OK 204 NO_CONTENT	Resource updated, properties returned Resource updated, no properties returned
upgrade	POST	200 OK 204 NO_CONTENT	Service upgraded, content returned Service upgraded, no content returned
notify	POST	200 OK 204 NO_CONTENT	Event notification accepted Event notification accepted
link	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
unlink	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
retrieve	GET	200 OK	Resource properties including Counters usage are returned
get Default values	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 Configurations	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.

Success Responses

200 OK

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

{
  ...

201 Created

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.

Example

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

{
  ...
}

204 No Content

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

206 Partial 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
...

[
  ...
]

Error Responses

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” }

← Message Formats

Resource Query Language →