- Use meaningful resource names to clarify what a given request does. A RESTful URI should refer to a resource that is a thing instead of an action. The name and structure of URIs should convey meaning to those consumers.
- Use plurals in node names to keep your API URIs consistent across all HTTP methods.
- Use HTTP methods appropriately. Use
HEAD in requests to clarify the purpose of the request. The
DELETE methods map to the CRUD methods Create, Read, Update, and Delete, respectively. Each resource should have at least one method.
- Create at most only one default resource (a resource with neither a uri-template nor a url-mapping) for each API.
- Offer both XML and JSON whenever possible.
- Use abstraction when it's helpful. The API implementation does not need to mimic the underlying implementation.
- Implement resource discoverability through links (HATEOAS). As mentioned in the previous section, the application state should be communicated via hypertext. The API should be usable and understandable given an initial URI without prior knowledge or out-of-band information.
- Version your APIs as early as possible in the development cycle. At present, the ESB identifies each API by its unique context name. If you introduce a version in the API context (e.g., /Service1Service/1.0.0), you can update it when you upgrade the same API (e.g., /Service/Service11.0.1).
- Secure your services using OAuth2, OpenID, or another authentication/authorization mechanism. See also Securing APIs.