Copyright © 2016 Open Geospatial Consortium. 13
Whenever a resource conflict would be caused by fulfilling the request. Duplicate entries, such as trying to create two customers with the same information, and deleting root
objects when cascade-delete is not supported are a couple of examples.
500 INTERNAL SERVER ERROR
Never return this intentionally. The general catch-all error when the server-side throws an exception. Use this only for errors that the consumer cannot address from their end.
For a full list of HTTP status codes, see IETF page
3
.
5.3.4 Create Fine-Grained Resources
When starting out, it’s best to create APIs that mimic the underlying application domain. However, it’s much easier to create larger resources later from collections of individual
resources than it is to create fine-grained or individual resources from larger aggregates.
5.3.5 Consider Connectedness
One of the principles of REST is connectedness via hypermedia. While services are still useful without them, APIs become more self-descriptive and discoverable when links are
returned in the response. At the very least, a ‘self’ link reference informs clients how the data was or can be retrieved. Additionally, utilize the HTTP Location header to contain a
link on resource creation via POST or PUT. For collections returned in a response that support pagination, ‘first’, ‘last’, ‘next’ and ‘prev’ links at a minimum are very helpful.
Regarding linking formats, there are many. The HTTP Web Linking Specification RFC5988
4
explains a link as follows: a link is a typed connection between two resources that are identified by
Internationalized Resource Identifiers IRIs [RFC3987
5
], and is comprised of: A context IRI,
a link relation type a target IRI, and
optionally, target attributes. A link can be viewed as a statement of the form “{context IRI} has a {relation type}
resource at {target IRI}, which has {target attributes}.”
3
http:www.ietf.orgassignmentshttp-status-codeshttp-status-codes.xml
4
http:tools.ietf.orgsearchrfc5988
5
http:tools.ietf.orgsearchrfc3987
14 Copyright © 2016 Open Geospatial Consortium.
Another often used solution is to place links in the HTTP Link header
6
as recommended in the specification, or embrace a JSON representation of this HTTP link style such as
Atom-style links, see: RFC4287
7
in your JSON representations. Link: https:www.example.comapiv1cars?offset=15limit=5;
rel=”next”,https:www.example.comapiv1cars?offset=50limit=3; rel=”last”,https:www.example.comapiv1cars?offset=0limit=5;
rel=”first”,https:www.example.comapiv1cars?offset=5limit=5; rel=”prev”
HTTP Header can be used to return additional information like the total count of entries, like X-Total-Count.
5.4 ROA vs SOA
