This documentation is for WSO2 Enterprise Integrator version 6.1.1 . View documentation for the latest release in the 6.x.x family and the latest release in the 7.x.x family.

All docs This doc

Versions Compared

Key

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

This page describes how you can work with APIs that allows messages to be sent directly to the ESB profile of WSO2 EI. It contains the following sections:

...

An API allows you to send a message directly into EI and the ESB profile and perform specific logic on it based on the instructions in the HTTP call. This section introduces the fundamentals of creating APIs in EI the ESB profile. It illustrates the concepts through the XML configuration.

...

An API definition is identified by the <api> tag. Each API must specify a unique name and a unique URL context (see below). 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. For example:

...

An API in WSO2 EI is analogous to a web application deployed in the EI runtimeESB 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”, only HTTP requests whose URL path starts with “/test” will be handled by that API.

...

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

WSO2 EI provides 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 WSO2 EIESB 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 WSO2 EI the ESB profile and prefixing the variable with "uri.var." as shown in the following example:

...

For a comprehensive example of using APIs with the ESB profile, see the article How to GET a Cup of Coffee the WSO2 Way.

...

Basic REST architectural principles

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

...

  • Use meaningful resource names to clarify what a given request does. A RESTful URI should refer to a resource that is a thing instead of an action. The name and structure of URIs should convey meaning to those consumers.
  • Use plurals in node names to keep your API URIs consistent across all HTTP methods.
  • Use HTTP methods appropriately. Use POST, GET, PUT, DELETE, OPTIONS and HEAD in requests to clarify the purpose of the request. The POST, GET, PUT and DELETE methods map to the CRUD methods Create, Read, Update, and Delete, respectively. Each resource should have at least one method.
  • Create at most only one default resource (a resource with neither a uri-template nor a url-mapping) for each API.
  • Offer both XML and JSON whenever possible.
  • Use abstraction when it's helpful. The API implementation does not need to mimic the underlying implementation. 
  • Implement resource discoverability through links (HATEOAS). As mentioned in the previous section, the application state should be communicated via hypertext. The API should be usable and understandable given an initial URI without prior knowledge or out-of-band information.
  • Version your APIs as early as possible in the development cycle. At present, the ESB identifies profile 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).
  • Secure your services using OAuth2, OpenID, or another authentication/authorization mechanism. See also Securing APIs .

...