Working with APIs

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 Services, Inbound 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.

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

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:

• Architectural Styles and the Design of Network-based Software Architectures
• Restful Service Best Practices

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.

<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.

<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. Follow the steps given below to generate Swagger documentation for the REST APIs you created in WSO2 EI.

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.

   <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
   Windows	integrator.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>. 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>. 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.