Page Comparison

...

Representational State Transfer (REST) provides a lightweight approach for building distributed systems. Instead of relying on overly complicated protocol stacks and heavyweight middleware, REST facilitates communication between systems by leveraging simple message formats and open protocols that power the Web. This section introduces the fundamentals of working with REST APIs. It illustrates the concepts through the XML configuration. For information on adding an API through the Management Console UI, see Adding APIs in the Management Console. 

Defining an API

The syntax of a REST API is as follows.

<api name="API_NAME" context="URI_PATH_OF_API" [hostname="HOST_NAME_OF_SERVER"]  [port="PORT_NUMBER"]>
	<resource [methods="GET|POST|PUT|DELETE|OPTIONS|HEAD|PATCH"] [uri-template="URI_TEMPLATE"|url-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). A REST 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.

...

You can define a URL mapping to a set of operations as shown in the API_1 definition, or you can define separate mappings for separate operations as shown in API_2. Also note the last resource definition in API_3, which does not specify a URL mapping nor a URI template. This is called the default resource of the API. Each API can have at most one default resource. Any request received by the API that does not match any of the enclosed resource definitions will be dispatched to the default resource of the API. In the case of API_3, a DELETE request on the URL “/payments” will be dispatched to the default resource as none of the other resources in API_3 are configured to handle DELETE requests.

For a comprehensive example of using REST APIs with the ESB, see the article How to GET a Cup of Coffee the WSO2 Way.

Adding APIs in the Management Console

...

1. In the Management Console, click the Main tab.
   

   

2. Under Manage -> Service Bus, click APIs.
   The Deployed APIs dialog appears, displaying the APIs you've already created.  Before you create a new API, you should browse the list to see whether an API already exists that will suit your needs. You can easily find an existing API by entering all or part of its name in the Search field and then clicking the Search icon.
3. Click Add API.
   
   The Add API dialog appears.
   
   
4. Specify the following:
   
   • A unique name for this API.
   • The context, and optionally the hostname and port (see Specifying the context for more information).
5. Click Add Resource, and then scroll down to see the additional fields.
6. Specify the HTTP method to use for this invocation (see Best practices for designing REST APIs for more information).
7. In the URL Style list, select whether you're specifying a URL mapping or URI template, and then specify the pattern in the box that appears (see Using patterns with resources for more information). 
8. Specify the In, Out, and Fault sequences as needed by taking one of the following approaches for each:
   
   • To omit the sequence, leave it set to None.
   • To create a new sequence, click Define Inline, click Create, and then define the sequence as described in Adding a Mediation Sequence.
   • To use an existing sequence in the registry, click Pick From Registry, and then select the sequence from the local, Configuration, or Governance registry (see Working with the Registry).
   • To use an existing sequence in the Synapse configuration, click Use Existing Sequence and select it from the drop-down list.
9. Click Update to apply the resource to the configuration.
10. Click Add Resource again and repeat these steps to add additional resources as needed. When you have finished defining the API, click Save.

...