Wednesday, October 17, 2012

URL Template, URL Mapping and their usages in API Manager

 WSO2 API Manager is a complete solution for publishing APIs, creating and managing a developer community and for scalably routing API traffic. It leverages proven, production-ready, integration, security and governance components from the WSO2 Enterprise Service Bus, WSO2 Identity Server, andWSO2 Governance Registry. In addition, as it is also powered by the WSO2 Business Activity Monitor, the WSO2 API Manager is ready for massively scalable deployment immediately.

Here in this post i wanted to discuss about the differences between url-template and url-mapping. Also its really important understanding query parameters and path parameters and their usages. This is very important when it comes to API management as each API resource map to some sort of url template or url mapping. Most API management tool do not allow you to define resources in a very specific way. All of them allow you to define very simple url patterns like url mapping does. But with that you cannot validate complex url patterns before it send to actual back end service. We can use ril-template for that type of complex mappings. Lets see how we can do it.

URL Template
A URL Template is a way to specify a URL that includes parameters that must be substituted before the URL is resolved. The syntax is usually to enclose the parameter in Braces ({example}). The convention is for a parameter to not be Percent encoded unless it follows a Question Mark (?). Advantage of url template is you can define path parameters inside url template definition. See following example. We can define url template with exact number of parameters and their locations inside url and etc. Also see sample url which maps to that url template.

uri-template="/view/{symbol,symbol1}/test/{symbol3,symbol4}/test1"

Sample URL /view/12,12/test/14,15/test1

If someone has url like
 /view/12,12/test/14,15/test1/test2 or /view/12,12/test-change/14,15/test1

API gateway will simply reject that request saying no matching resource found. This is really usefull if you need to validate exact URL before it hits your API.

From next version of WSO2 API Manager(After 1.1.0) you will be able to define path parameters and query parameters both in url template. See following example.

uri-template="/view/{symbol,symbol1}/test/{symbol3,symbol4}/test1/*

This * mark says that you can have anything after test1/ so you can have any query paramaters after that point.

Sample URL /view/12,12/test/14,15/test1/data?name=sanjeewa&mood=hap

URL Mapping
URL Mapping allows users to create constant user friendly URLs and map them to resources. As API creator create the URLs, they can define human readable names for them. The self defined URLs can be published externally and thereby made available to API consumers. Most importantly you cannot have path parameters inside url mapping definition. You can have some sort for context for given resource. If you create API from WSO2 API Manager publisher UI it will automatically created API mapping for your API. If you need to define url template you have to go to sequence editor and edit it manually.

Query parameters and path parameters
Lets see what is query parameter and what is path parameter. In the World Wide Web, a query string is the part of a Uniform Resource Locator (URL) that contains data to be passed to web applications.

A URI path parameter is part of a path segment that occurs after its name. Path parameters offer a unique opportunity to control the representations of resources. If you have multiple parameters in between resources you can separate them by , or ;.

No comments:

Post a Comment