com.atlassian.confluence.content.render.xhtml.migration.exceptions.UnknownMacroMigrationException: The macro 'next_previous_links2' is unknown.

Creating an API

Owned by Former user (Deleted)
Last updated: Jul 19, 2018
6 min read

You can create a new API or import an existing API from the file system using WSO2 EI tooling. You can also add an API resource to an existing API via WSO2 EI tooling.

Prerequisites

You need to have WSO2 EI tooling installed to create a new REST API or to import an existing API via tooling. For instructions on installing WSO2 EI tooling, see Installing Enterprise Integrator Tooling.

Step 1: Creating an ESB project

First, create an ESB Solution Project in ESB tooling. We will use this project to store the REST API file.

  1. Open the Developer Studio Dashboard (click Developer Studio > Open Dashboard) and click ESB Solution Project.

  2. Enter a name for the project and click Next.
  3. Enter the Maven information about the project and click Finish.
  4. The new project will be listed in the project explorer.

Step 2: Creating an API

Following sections describe how you can create a new API.

  1. In Eclipse, click the Developer Studio menu and then click Open Dashboard. This opens the Developer Studio Dashboard.

  2. Click REST API on the Developer Studio Dashboard.

    Importing a REST API?

    If you already have a REST API created, you have the option of importing the XML configuration. Select Import API Artifact and follow the instructions on the UI. To create a new API from scratch, continue with the following steps.

  3. Leave the first option selected and click Next.

  4. Specify the API name, context, hostname, and port. For more information, see Configuring Endpoints using REST APIs.

    NameEnter a unique name for the new API.
    Context URL

    An API in WSO2 EI is analogous to a web application deployed in the ESB profile. Each API is anchored at a user-defined URL context, much like how a web application deployed in a servlet container is anchored at a fixed URL context. An API will only process requests that fall under its URL context. For example, if a particular API is anchored at the context “/test”, the API will only handle HTTP requests with a URL path that starts with “/test”.

    If your ESB profile is deployed in multitenant mode, the tenant domain should be added to the API context. For example, the API is defined for tenant abc.com, and the context for the API is "/order", the context should be "/t/abc.com/order". When you define the API in Design View, the tenant domain will be appended to the context by the system. Therefore, you do not need to manually add the tenant domain.

    HostnameThe Host at which the API is anchored. If you don't enter a value, 'localhost' will be the default hostname. If required, you can bind a given API to a user-defined hostname.
    PortThe Port of the REST API. If you don't enter a value, '8280' will be the default hostname. If required, you can bind a given API to a user-defined port number.
    VersionThe 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). Version your APIs as early as possible in the development cycle.
  5. Click Finish. The REST API is created inside the src/main/synapse-config/api folder under the ESB Config project you specified.

  6. When you created the API, an API resource is created by default. If you want to add a new resource, click API Resource in the Tool pallet of the API section and simply drag and drop the resource to the REST API.

    About the default API Resource

    Each API can have at most one default resource. Any request received by the API but does not match any of the enclosed resource definitions will be dispatched to the default resource of the API. In 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. If you go to the Source view, the default resource will be as follows:

    <api context="/healthcare" name="HealthcareAPI" xmlns="http://ws.apache.org/ns/synapse"> <resource methods="GET"> <inSequence/> <outSequence/> <faultSequence/> </resource> </api>

Step 3: Configuring an API resource

In the Design view of the API Resource, click the resource icon to enable the Properties tab. You can now enter the configuration parameters as given below.

  1. Specify the HTTP methods that the resource should handle. This provides additional control over what requests are handled by a given resource.

  2. Select one of the values given below for the URL style property. A resource can be associated with a user-defined URL mapping orURI template. This allows us to restrict the type of HTTP requests processed by a particular resource.

    URL Template

    A URI template represents a class of URIs using patterns and variables. When a resource is associated with a URI template, all requests that match the template will be processed by the resource. Some examples of valid URI templates are as follows: 

    /order/{orderId}
    /dictionary/{char}/{word}

    The identifiers within curly braces are considered variables. For example, a URL that matches the template “/order/{orderId}” is as follows:

    /order/A0001

    In the above URL instance, the variable "orderId" has been assigned the value “A0001”. Similarly, the following URL adheres to the template “/dictionary/{char}/{word}”:

    /dictionary/c/cat 

    In this case, the variable “char” has the value “c” and the variable “word” is given the value “cat”. 

    The ESB profile provides access to the exact values of the template variables through message context properties. For example, if you have a resource configured with the URI template “/dictionary/{char}/{word}”, and a request “/dictionary/c/cat” is sent to the ESB profile, it will be dispatched to this resource, and we will be able to retrieve the exact values of the two variables using the "get-property" XPath extension of the ESB profile  and prefixing the variable with "uri.var." as shown in the following example: 

    <log level="custom">
   <property name="Character" expression="get-property('uri.var.char')"/>
   <property name="Word" expression="get-property('uri.var.word')"/>
</log>

    This log mediator configuration would generate the following output for the request “/dictionary/c/cat”:

    LogMediator Character = c, Word = cat 

    URL Mapping

    When a resource is defined with a URL mapping, only those requests that match the given pattern will be processed by the resource. There are three types of URL mappings:

    • Path mappings (/test/*, /foo/bar/*)

    • Extension mappings (*.jsp, *.do)

    • Exact mappings (/test, /test/foo)

    For example, if the URL mapping is “/foo/*” and the HTTP method is “GET”, the resource will only process GET requests with a URL path that matches the pattern “/foo/*”. Therefore, the following example requests will be processed by the resource:

    GET /test/foo/bar 
    GET /test/foo/a?arg1=hello 

    The following example requests would not be handled by this resource:

    GET /test/food/bar (URL pattern does not match)
    POST /test/foo/bar (HTTP verb does not match)

  3. Select the sequences: The resource also contains sequences (in-sequence/out-sequence/fault sequence), which contains the mediation logic to process the message.

Step 4: Defining the mediation logic

Now you can build your integration use case by adding the required mediation artifacts to the In sequence, Out sequence, and the fault sequence. 

Step 5: Deploying the API artifacts in the ESB server

You need to create a Composite Application project with a CAR file. You can then deploy the CAR file in the ESB server:

  1. Right-click the Project Explorer and click New > Project.
  2. From the window that opens, click Composite Application Project.

  3. Give a name to the Composite Application project and select the projects that you need to group into your C-App from the list of available projects. You need to select the ESB project, which contains the proxy service and security policy file respectively.

  4. Next, deploy the CAR file in the ESB server.

Step 6: Enabling logs for APIs (Optional)

The advantage of having per-API log files is that it is very easy to analyze/monitor the basic logs relevant to a REST API defined in the ESB. The API log is an additional log file, which will contain a copy of the logs to a particular REST API.

Below are the configuration details to configure the logs of a REST API called TestAPI using log4j properties. Open the <EI_HOME>/conf/log4j.properties file using your favorite text editor to configure log4j to log the API specific logs to a file. You can configure the logger for either INFO level logs or DEBUG level logs as follows:

INFO level

Add the following section to the end of the file to configure the logger for log messages where the Log Category is  INFO.

log4j.category.API_LOGGER=INFO, API_APPENDER
log4j.additivity.API_LOGGER=false
log4j.appender.API_APPENDER=org.apache.log4j.RollingFileAppender
log4j.appender.API_APPENDER.File=${carbon.home}/repository/logs/${instance.log}/wso2-ei-api${instance.log}.log
log4j.appender.API_APPENDER.MaxFileSize=1000KB
log4j.appender.API_APPENDER.MaxBackupIndex=10
log4j.appender.API_APPENDER.layout=org.apache.log4j.PatternLayout
log4j.appender.API_APPENDER.layout.ConversionPattern=%d{ISO8601} [%X{ip}-%X{host}] [%t] %5p %c{1} %m%n</pre>
DEBUG level

Add the following section to the end of the file to configure the logger for log messages where the Log Category is DEBUG.

log4j.category.API_LOGGER.TestAPI=DEBUG, TEST_API_APPENDER
log4j.additivity.API_LOGGER.TestAPI=false
log4j.appender.TEST_API_APPENDER=org.apache.log4j.DailyRollingFileAppender
log4j.appender.TEST_API_APPENDER.File=${carbon.home}/repository/logs/${instance.log}/TestAPI.log
log4j.appender.TEST_API_APPENDER.datePattern='.'yyyy-MM-dd-HH-mm
log4j.appender.TEST_API_APPENDER.layout=org.apache.log4j.PatternLayout
log4j.appender.TEST_API_APPENDER.layout.ConversionPattern=%d{ISO8601} [%X{ip}-%X{host}] [%t] %5p %c{1} %m%n

The above configuration creates a log file named TestAPI.log in the <EI_HOME>/repository/logs directory.

com.atlassian.confluence.content.render.xhtml.migration.exceptions.UnknownMacroMigrationException: The macro 'next_previous_links' is unknown.