This documentation is for WSO2 Enterprise Service Bus version 5.0.0. For the latest ESB, view the latest WSO2 Enterprise Integrator documentation.

All docs This doc

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

An API allows you to send a message directly into the ESB and perform specific logic on it based on the instructions in the HTTP call. This section introduces the fundamentals of creating APIs in the ESB. It illustrates the concepts through the XML configuration.

For information on adding an API via the ESB tooling plug-in, see Working with APIs via WSO2 ESB Tooling.

For information on adding an API through the Management Console UI, see Adding Working with APIs in via the Management Console. 

Defining an API

The syntax of a REST API is as follows.

...

Code Block
languagehtml/xml
<api xmlns="http://ws.apache.org/ns/synapse" name="EventDelayOrderAPI" context="/orderdelayAPI"> 
    <resource methods="POST" url-mapping="/"> 
       <inSequence> 
          <property name="REST_URL_POSTFIX" action="remove" scope="axis2"></property> 
          <send> 
             <endpoint> 
                <address uri=
"jms:/DelayOrderTopic?transport.jms.ConnectionFactoryJNDIName=TopicConnectionFactory&
java.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory&
java.naming.provider.url=tcp://localhost:61616&transport.jms.DestinationType=topic">
              </address> 
             </endpoint> 
          </send> 
       </inSequence> 
    </resource> 
 </api>

 Notice that we have specified the REST_URL_POSTFIX property with the value set to "remove". When invoking this API, even if the request contains a trailing slash after the context (e.g., POST http://127.0.0.1:8287/orderdelayAPI/ instead of POST http://127.0.0.1:8287/orderdelayAPI), the endpoint will be called correctly. AnchoraddAPIsaddAPIs

Adding APIs in the Management Console

You can easily add APIs using the Management Console.

To add an API:

  1. In the Management Console, click the Main tab. Then click APIs to open the Deployed APIs page.
  2. Click Add API to open the Add API page.

    Image Removed

  3. Enter values for the following parameters in the header of the page as required.

    Parameter NameDescriptionData TypeRequired/OptionalBest Practices
    API NameA unique name for the API.StringRequired 
    ContextThis parameter specifies a URL context to which the requests processed by the REST API should be limited. See Specifying the Context for further information.StringRequiredVersion 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)
    Host NameThe host at which the API is anchored.StringOptional 
    PortThe port of the REST API.IntegerOptional 
    Add ResourceClick this link to add one or more At least one resource is required.

    Create at most only one default resource (a resource with neither a uri-template nor a url-mapping) for each API.

    The parameters that can be configured for each resource is described in detail in the next section.

  4. Click Add Resource to expand the page and display the Resource section.
    Image Removed
    Configure the following parameters for the resource.

    Parameter NameDescriptionData TypeRequired/Optional
    MethodsSelect the required check boxes to indicate the HTTP method to be used to invoke the REST API. See Best practices for designing REST APIs for more information.booleanRequired
    URL StyleSelect a value for his parameter to indicate whether you are specifying a URL mapping or a URI template. A new data field named URL-Mapping or URI-Template will appear based on the selection. Enter the required pattern in this data field.stringRequired
    In Sequence

    This specifies the mediation flow for incoming messages. Possible values are as follows.

      • None: Select this to omit the sequence.
      • Define Inline: Select this if you want to define a new sequence and then define the sequence as described in Adding a Mediation Sequence.
      • Pick From Registry: Select this to use an existing sequence saved in the Registry.
      • Use Existing Sequence: Select this to use an existing sequence that already exists in the Synapse Configuration.
     One of the four options should be selected.
    Out Sequence

    This specifies the mediation flow for outgoing messages. Possible values are as follows.

    • None: Select this to omit the sequence.
    • Define Inline: Select this if you want to define a new sequence and then define the sequence as described in Adding a Mediation Sequence.
    • Pick From Registry: Select this to use an existing sequence saved in the Registry.
    • Use Existing Sequence: Select this to use an existing sequence that already exists in the Synapse Configuration.
     One of the four options should be selected.
    Fault Sequence

    This specifies the mediation flow for messages with errors. Possible values are as follows.

    • None: Select this to omit the sequence.
    • Define Inline: Select this if you want to define a new sequence and then define the sequence as described in Adding a Mediation Sequence.
    • Pick From Registry: Select this to use an existing sequence saved in the Registry.
    • Use Existing Sequence: Select this to use an existing sequence that already exists in the Synapse Configuration.

     

     One of the four options should be selected.

    Click Update to update the resource to the configuration. Repeat this step to enter as many resources as required.

  5. Click Save to save the API. The API would now appear in the list of deployed APIs.

Deleting APIs in the Management Console

The following procedure is used to delete an API.

...

Basic REST architectural principles

...