REST API¶

Introduction¶

A REST API in WSO2 Micro Integrator is analogous to a web application deployed in the web container. 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. An API is made of one or more Resources, which are logical components of an API that can be accessed by making a particular type of HTTP call.

A REST API resource is used by the Micro Integrator to process messages before forwarding them to the relevant endpoint. Just as Proxy Services and Inbound Endpoints, the REST API resource uses mediators and sequences to define the mediation logic for processing messages. The API resource mediates incoming requests, forwards them to a specified endpoint, mediates the responses from the endpoint, and sends the responses back to the client that originally requested them. The In sequence handles incoming requests and sends them to the back-end service, and the Out sequence handles the responses from the back-end service and sends them to the requesting client. You can also define a fault sequence to handle any errors that may occur while mediating a message through a resource.

We can create an API resource to process defined HTTP request methods. 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.

Properties¶

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

REST API Properties (Required)¶

The following properties are required in order to create the REST API artifact.

Property Description

Name A unique name for the new API.

Context URL An API in WSO2 Micro Integrator is analogous to a web application deployed in the Micro Integrator. 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 only processes requests that fall under its URL context. For example, if a particular API is anchored at the context /test, the API only handles HTTP requests with a URL path that starts with /test.

REST API Properties (Optional)¶

The following properties are optional properties you can configure when creating a REST API artifact.

Property	Description
Hostname	The Host at which the API is anchored. 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.
Port	The Port of the REST API. If you do not enter a value, `8280` is considered the default hostname. If required, you can bind a given API to a user-defined port number.
Version	The Micro Integrator 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.
Path to Swagger Definition	The path to a custom Swagger definition (YAML/JSON file) that is stored in a registry project in your workspace. Once this API is created and deployed in the Micro Integrator, users will be able to access this custom Swagger definition and not the default Swagger definition of the API. See the instructions on using Swagger documents for more information.

REST API Resource Properties¶

When you 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 us 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 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”. It is possible to retrieve the exact values of the two variables using the "get-property" XPath extension of the Micro Integrator and prefixing the variable with "uri.var".
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: 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)
Protocol	Specify the HTTP methods that the resource should handle. This provides additional control over what requests are handled by a given resource.