All docs This doc

Versions Compared

Key

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

An API is one way of triggering a mediation flow defined in the ESB of WSO2 Enterprise Integrator (WSO2 EI). Alternatively, you can use Proxy ServicesInbound Endpoints, or Scheduled Tasks.  APIs allow you to send messages directly to the ESB profile,  which will then execute a specific logic based on the instructions in the HTTP call.

Info

To get started with REST APIs in the ESB, follow the tutorial on sending a simple message to a service.

The following topics provide additional information on how to configure an API in the ESB profile.

Table of Contents
 

Using REST with APIs

You can create APIs that allow messages to be sent over the HTTP and HTTPS transports. Furthermore, you can configure REST endpoints in an API by directly specifying HTTP verbs (such as POST and GET), URI templates, and URL mappings. Alternatively, you can use the HTTP Endpoint to define REST endpoints using URI templates.

The structure of APIs in the ESB profile is based on REST architectural principles. This section highlights some of the basic architectural principles of REST based on the following resources:

Overview of REST APIs

Each API must specify a unique name and a unique URL Context. 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.  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.

Code Block
languagexml
<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>

Example APIs

Let's look at some sample API configurations to understand how we use context, resources, and patterns to control how requests are processed.

Code Block
languagexml
<api name="API_1" context="/order">
    <resource url-mapping="/list" inSequence="seq1" outSequence="seq2"/>
</api>
 
<api name="API_2" context="/user">
    <resource url-mapping="/list" methods="GET" inSequence="seq3" outSequence="seq4"/>
    <resource uri-template="/edit/{userId}" methods="PUT POST" inSequence="seq5" outSequence="seq6"/>
</api>

<api name="API_3" context="/payments">
    <resource url-mapping="/list" methods="GET" inSequence="seq7" outSequence="seq8"/>
    <resource uri-template="/edit/{userId}" methods="PUT POST" outSequence="seq9">
        <inSequence>
             <log/>
             <send>
   <endpoint key="BackendService"/>
             </send>
        </inSequence>
    </resource>
    <resource inSequence="seq10" outSequence="seq11"/>
</api>

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.

Generating Swagger documents for the APIs

API documentation is important to guide the users on what they can do using specific APIs.

Note

Note: Swagger documents for APIs will be generated by default from EI-6.6.0 onwards.

Following steps will explain how to generate Swagger documentation for the REST APIs in earlier versions of WSO2 EI.

Tip

You need to have created a REST API to view the documentation for that API.

  1. Add the following configuration under the HttpGetRequestProcessors tag of the <EI_HOME>/conf/carbon.xml file to generate the Swagger JSON or YAML files.

    Code Block
    <Processor>
       <Item>swagger.json</Item>
       <Class>org.wso2.carbon.mediation.transport.handlers.requestprocessors.swagger.format.SwaggerJsonProcessor</Class>
    </Processor>
    <Processor>
       <Item>swagger.yaml</Item>
       <Class>org.wso2.carbon.mediation.transport.handlers.requestprocessors.swagger.format.SwaggerYamlProcessor</Class>
    </Processor>
  2. Open the terminal, navigate to the <EI_HOME>/bin directory and start the WSO2 EI profile.

    Linux/Mac./integrator.sh
    Windowsintegrator.bat --run
  3. Generate the Swagger docs:

    JSON
    Enter the following on the browser and the JSON content will appear on the browser screen: http://<EI_HOST>:8280/<API_NAME>?swagger.json
    • By default, <EI_HOST> is localhost. However, if you are using a public IP, the respective IP address or domain needs to be specified.
    • Enter the APIs name for <API_NAME>.

      Note

      The API name is case sensitive. Therefore, make sure to the enter the API name correctly. Else, the JSON file will not download.

    Example: http://localhost:8280/HealthcareAPI?swagger.json

    Generate Swagger docs for tenants

    If you want to generate the Swagger JSON file for a tenant, you need to enter the following on the browser. http://<EI_HOST>:8280/t/<TENANT_DOMAIN>/<API_NAME>?swagger.json
    • By default, <EI_HOST> is localhost. However, if you are using a public IP, the respective IP address or domain needs to be specified.
    • Enter the value of the tenant domain for <TENANT_DOMAIN>.
    • Enter the APIs name for <API_NAME>.

    Example: http://localhost:8280/t/abc.com/HealthcareAPI?swagger.json

    YAML
    Enter the following on the browser and the YAML file will download to your machine: http://<EI_HOST>:8280/<API_NAME>?swagger.yaml
    • By default, <EI_HOST> is localhost. However, if you are using a public IP, the respective IP address or domain needs to be specified.
    • Enter the APIs name for <API_NAME>.

      Note

      The API name is case sensitive. Therefore, make sure to the enter the API name correctly. Else, the YAML file will not download.

    Example: http://localhost:8280/HealthcareAPI?swagger.yaml

    Generate Swagger docs for tenants
    If you want to generate the Swagger YAML file for a tenant, you need to enter the following on the browser.

    http://<EI_HOST>:8280/t/<TENANT_DOMAIN>/<API_NAME>?swagger.yaml
    • By default, <EI_HOST> is localhost. However, if you are using a public IP, the respective IP address or domain needs to be specified.
    • Enter the value of the tenant domain for <TENANT_DOMAIN>.
    • Enter the APIs name for <API_NAME>.

    Example: http://localhost:8280/t/abc.com/HealthcareAPI?swagger.yaml

  4. Copy the content of the JSON or YAML file to the Swagger Editor or any other tool and check out the documentation of the API.