Page Comparison

...

The syntax of a REST API is as follows.

<api xmlns="http://ws.apache.org/ns/synapse"      name="APINameAPI_NAME"      context="/APIContextURI_PATH_OF_API" [hostname="stringHOST_NAME_OF_SERVER"]  [port="integerPORT_NUMBER"]>
   	<resource [methods="OPTIONS DELETE GET" GET|POST|PUT|DELETE|OPTIONS|HEAD|PATCH"] [uri-template="/URI_TEMPLATE"|url-template"mapping="URL_MAPPING"]>
    	  <inSequence>
        ...
      </inSequence>?
      <outSequence>
         ...
      </outSequence>?
	  <faultSequence>
         ...
      </faultSequence>?
	</resource>
</api>

...

An API definition is identified by the <api> tag. Each API must specify a unique name and a unique URL context (see below). An API is made of one or more resources, which is a logical component of an API that can be accessed by making a particular type of HTTP call. For example:

<api name="API_1" context="/order">
    <resource url-mapping="/list" inSequence="seq1" outSequence="seq2"/>
</api>

Once a request is dispatched to a resource it will be mediated through the in-sequence of the resource. At the end of the in-sequence the request can be forwarded to a back-end application for further processing. Any responses coming from the back-end system are mediated through the out-sequence of the resource. You can also define a fault-sequence to handle any errors that may occur while mediating a message through a resource.

...

• 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 POST, GET, PUT, DELETE, OPTIONS and HEAD in requests to clarify the purpose of the request. The POST, GET, PUT and 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., /Service/1.0.0), you can update it when you upgrade the same API (e.g., /Service/1.0.1).
• Secure your services using OAuth2, OpenID, or another authentication/authorization mechanism. See also Securing APIs.

...