REST APIs¶

Introduction¶

A REST API in WSO2 Micro Integrator is a key component for exposing integration services. Each API is anchored at a user-defined URL context and will only process requests that fall under the given URL context.

An API should consist of one or more resources, which represent the logical components of an API that can be accessed via specific HTTP methods, such as GET, POST, PUT, DELETE PATCH, HEAD, or OPTIONS. The REST API resource uses sequences and mediators to define the mediation logic. The inSequence handles incoming requests and flows through the mediators. You can define a faultSequence to handle any errors that may occur while mediating a message in a resource.

Properties¶

See the topics given below for the list of properties that can be configured when creating a REST API artifact.

REST API Properties¶

The following properties are required fields.

Property	Description
Name	A unique name for the API.
Context URL	This is a part of the API's URL structure that defines the base path for the API. The context URL must be unique for an API deployed in WSO2 MI. The context URL is essential for routing HTTP requests to the correct API. For example, if the context URL is `/weather`, the API only handles HTTP requests with a URL path that starts with `/weather`.

The following properties are optional fields.

Property	Description
Version	The version is appended to the context URL as part of the base path. This allows different versions of an API to coexist while ensuring that each version can be invoked independently. This ensures that older versions of the API can continue to function without disruption when newer versions are introduced.
Hostname	The Host at which the API is exposed. If you do not enter a value, `localhost` is considered the default hostname. If required, you can bind a given API to a user-defined hostname. Add the defined hostname to the `/etc/hosts` file in your machine. Note This property has been deprecated and is no longer recommended for use.
Port	The Port of the REST API. If you do not enter a value, `8290` is considered the default hostname. If required, you can bind a given API to a user-defined port number. For this to work you have to use an inbound endpoint to expose the configured API. See the using inbound endpoint tutorial for more information. Note This property has been deprecated and is no longer recommended for use.

REST API Resource Properties¶

When you are creating a REST API artifact, you need to configure the API resource. Listed below are the properties you can configure when defining an API resource.

Property Description

URI Style This allows you to restrict the type of HTTP requests processed by a particular resource. A resource can be associated with a user-defined URL mapping or a URI template.

URI Template

This property is enabled only if URI Template is specified as the URI style. A URI template represents the structure of the URLs 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.

Info

URI templates can be used when you need to match dynamic path segments from the incoming URL and map them to variables in your integration logic.

Some examples of valid URI templates are as follows:

URI Template	Sample URL	Description
`/order/{orderId}`	`/order/A0001`	The identifiers within curly braces are considered variables. The value `A0001` is assigned to the variable `orderId`.
`/dictionary/{char}/{word}`	`/dictionary/c/cat`	In this case, the value `c` is assigned to the variable `char` and the value `cat` is assigned to the variable `word`.

Info

It is possible to retrieve the exact values of the two variables using the get-property expression and prefixing the variable with uri.var.

For example: <property name="char" expression="get-property('uri.var.char')"/>

Note

When there are multiple resources that match the same or similar URI templates, the redirecting resource depends on the order in which the resources are defined. Therefore, it is recommended to avoid defining multiple resources with same or similar URI templates.

URL Mapping

This property is enabled only if URL Mapping is specified as the URI style.
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:

Type	URI Template	What will match	What will not match
Path mappings	`/news/`	`/news/`,`/news/southern`	`/news2/`
Extension mappings	`.jsp`	`/image.jsp`,`/news/weather.jsp`	`/abc.png`
Exact mappings	`/news`	`/news`	`/news/abc.png`

For example, if the URL mapping is /news/ and the HTTP method is GET, the resource will only process GET requests with a URL path that matches the pattern /news/. Therefore, the following example requests will be processed by the resource:
GET /test/news/east GET /test/news/a?arg1=hello
The following example requests would not be handled by this resource:
GET /test/new/east (URL pattern does not match) POST /test/news/east (HTTP verb does not match)

Protocol Specify the HTTP protocol that the resource should handle. This provides additional control over what requests are handled by a given resource. Possible Values are HTTP and HTTPS.