Example - Managing an API

Base URL

You can create the base URL of an API by the domain, port and context mappings of the API. For example, if the server name is www.phonestore.com, port is 8080, and the API context is api. The full Base URL is as follows.

http://www.phonestore.com:8080/api

Higher Level API Parameters

All resources and methods that are included in the individual resources inherit the parameters that are defined at the higher API level.

API Resources

Resources are the basic components of an API. Examples of resources from an online phonestore API include a phone, an order from a store, and a collection of customers. After you identify a service to expose as an API, you define the resources for the API.

For example, for the online phonestore API, you can represent the data in the phone store database as an API in various ways. The verbs in the HTTP request map to the operations that the database supports, such as select, create, update, delete.

Each resource must addressed by a unique URI. With the URI, you are going to expose for each resource you must also decide what can be done to each resource. The HTTP methods passed as part of an HTTP request header directs the API on what needs to be done with the addressed resource.

Resource URLs

A URL identifies the location of a specific resource.

For example, for the online phonestore API, the resources have the following URLs:

webMethods API Gateway supports the following patterns of resource URL: a collection of resources or a particular resource.

For example, in the online phonestore API, the patterns are as follows:

Pattern for a Collection URL. http://phonestore.com/api/phones

Pattern for a Unique URL. http://phonestore.com/api/phones/412456/features to retrieve a collection resource that describes the key features of phone whose product code is 412456

Resource Parameters

All Methods in the particular resource inherit all parameters that are defined at the higher Resource level. This inheritance does not affect the API.

Resource Methods

Individual resources can define their capabilities by using supported HTTP methods. To invoke an API, the client might call an HTTP operation on the URL associated with the API's resource. For example, to retrieve the key feature information for phone whose product code is 412456, the client might make a service call HTTP GET on the following URL.

http://www.phonestore.com/phones/412456/features

Supported HTTP Methods

webMethods API Gateway supports the standard HTTP methods for modeling APIs: GET, POST, PUT, DELETE, and PATCH.

The following table describes the semantics of HTTP methods for the sample Phone Store API:

Method Parameters

Parameters that are defined at the sub method level apply only to that particular method; it does not affect either the API or the resource.

API Parameters

Parameters specify additional information to a request. You use parameters as part of the URL or in the headers or as components of a message body.

Parameter Levels

A parameter can be set at different levels of an API. When you document a REST API in API Gateway, you define parameters at the API level, Resource level, or Method level to address the following scenarios:

• If you have the parameter applicable to all resources in the API, then you define this parameter at the API level. The parameter at the API level implies that the parameter is propagated to all resources and methods under the particular API.
• If you have the parameter applicable to all methods in the API, then you define this parameter at the resource level. The parameter at the resource level implies that the parameter is propagated to all methods under the particular resource.
• If you have the parameter applicable only to a method in the API, then you define this parameter at the method level.

API-level Parameters

Setting parameters at the API level enables the automatic assignment of the parameters to all resources and methods that are included in the API. Any parameter value that you specify at the higher API level overrides the parameter value that you set at the sub resource level or the sub method level if the parameter names are identical.

For example, if you have a header parameter that is called API Key that is used for consuming an API.

x-Gateway-APIKey:a4b5d569-2450-11e3-b3fc-b5a70ab4288a

This parameter is specific to the entire API and to the individual components that is resources and methods, directly inside the API. Such a parameter can be defined as a parameter at the API level.

At an API level, you can define the following types of parameters.

• Query-String parameter
• Header parameter

Resource-level Parameters

Setting parameters at the resource level enables the automatic assignment of the parameters to all methods within the resource. Any parameter value that you specify at the higher resource level overrides the parameter value that you set at the sub method level if the parameter names are the same. In contrast, the parameters at the sub resource level do not affect the higher API level parameters.

Consider the sample phonestore API maintains a database of reviews about different phones. A request to display information about a particular user review, 78 of the phone whose product code is 412456 is as follows.

GET /phones/412456/user_reviews/78

In the example, /user_reviews/78 parameter narrows the focus of a GET request to review /78 within a particular resource /412456.

This parameter is specific to the particular resource phone whose product code is 412456 and to any individual methods that are directly within the particular resource. Such a parameter can be defined as a parameter at the resource level.

At a resource level, you can define the following types of parameters:

• Query-String parameter
• Header parameter
• Path parameter

Method-level Parameters

If you do not set parameters at the API level or resource level, you can set them at a method level. Parameters that you set at the method level are used for the HTTP method execution. They are useful to restrict the response data returned for an HTTP request. Any parameter value that you specify at the sub method level is overridden by the value set at the higher API-level parameter or the higher resource-level parameter if the names are identical. In contrast, the sub method-level parameters do not affect the higher API-level or resource-level parameters.

For example, the phonestore API described might have a request to display information that the user Allen in 2013 about a phone whose product code is 412456 contributes.

GET /phones/412456/user_reviews/78?year=2013&name=Allen

In this example, year=2013 and name=Allen narrow the focus of the GET request to entries that user Allen added to user review 78 in 2013.

At a method level, you can define the following types of parameters.

• Query-String parameter
• Header parameter

Parameter Types

webMethods API Gateway supports three types of parameters in REST API: Query-String, Header, and Path.

You can use different parameter types for parameterizing the resources as follows.

Query-String Parameters

Query-String parameters are appended to the URI after a ? with name-value pairs. The name-value pairs sequence is separated by either a semicolon or an ampersand.

For instance, if the URL is http://phonestore.com/api/phones?itemID=itemIDValue, the query parameter name is itemID, and the value is the itemIDValue. Query parameters are often used when you filter or page through HTTP GET requests.

Now, consider the online phonestore API. A customer, when you try to fetch a collection of phones, you might want to add options, such as, android v4.3 OS and 8MP camera. The URI for this resource looks like as follows.

/phones?features=androidosv4.3&cameraresolution=8MP

Header Parameters

Header parameters are HTTP headers. Headers often contain metadata information for the client or server.

x-Gateway-APIKey:a4b5d569-2450-11e3-b3fc-b5a70ab4288a

You can create custom headers, as required. As a best practice, you prefix the header name with x-.

HTTP/1.1 defines the headers that can appear in an HTTP response in three sections of RFC 2616: 4.5, 6.2, and 7.1. Examine these codes to determine which are appropriate for the API.

Path Parameters

Path parameters are defined as part of the resource URI. For example, the URI can include phones/item, where /item is a path parameter that identifies the item in the collection of resource /phones. Because path parameters are part of the URI, they are essential in identifying the request.

Now, consider the online phonestore API. A customer wants to fetch details about a phone {phone-id} whose product code is 412456. The URI for this resource might look like:/phones/412456

Note: As a best practice, adopt the following conventions when you specify a path parameter in the resource URI.

• Append a path parameter variable within curly {} brackets.
• Specify a path parameter variable such that it exactly matches the path parameter that is defined at the resource level.

Parameter Data Types

When you add a parameter to the API, you specify the parameter's data type. The data type determines what kind of information the parameter can hold.

webMethods API Gateway supports the following data types for parameters:

Supported HTTP Status Codes

An API response returns an HTTP status code that indicates the success or failure of the requested operation.

You can specify HTTP codes for each method to help clients understand the response. While responses can contain an error code in XML or other format, clients can quickly and more easily understand an HTTP response status code. Clients typically understand the status codes that the HTTP specification defines.

webMethods API Gateway includes a set of predefined content types that are classified in the following taxonomy categories.

HTTP/1.1 defines all the legal status codes. Examine these codes to determine which are appropriate for your API.

Now, consider the online phonestore API. The following table describes the HTTP status codes that each of the URIs and HTTP methods combinations respond.

Sample Requests and Responses

To illustrate the usage of an API, you provide a sample request and response messages. Consider the sample phonestore API that maintains a database of phones in different brands. The phonestore API might provide the following examples to illustrate its usage:

Sample 1 - Retrieve a list of phones

Client Request

GET /phones HTTP/1.1
User-Agent: Mozilla/4.0 (compatible; MSIE5.01; Windows NT)
Host: www.api.phonestore.com
Accept-Language: en-us
Accept-Encoding: text/xml
Connection: Keep-Alive

Server Response

HTTP/1.1 200 OK
Date: Mon, 29 August 11:53:27 GMT
Server: Apache/2.2.14 (Win32)
Last-Modified: Mon, 18 July 2016 09:18:16 GMT
Content-Length: 356
Content-Type: text/xml
<phones>
	<phone>
		<name>Asha</name>
		<brand>Nokia</brand>
		<price currency="irs">11499</price>
		<features>
			<camera>
				<back>3</back>
			</camera>
			<memory>
				<storage scale="gb">8</storage>
				<ram scale="gb">1</ram>
			</memory>
			<network>
				<gsm>850/900/1800/1900 MHz</gsm>
			</network>
		</features>
	</phone>
	<phone>
		<name>Nexus7</name>
		<brand>Google</brand>
		<price currency="irs">16499</price>
		<features>
			<camera>
				<front>1.3</front>
				<back>5</back>
			</camera>
			<memory>
				<storage scale="gb">16</storage>
				<ram scale="gb">2</ram>
			</memory>
			<network>
				<gsm>850/900/1800/1900 MHz</gsm>
				<HSPA>850/900/1900 MHz</HSPA>
			</network>
		</features>
	</phone>
</phones>

Client Request

GET /phones/phone-4156 HTTP/1.1
User-Agent: Mozilla/4.0 (compatible; MSIE5.01; Windows NT)
Host: www.api.phonestore.com
Accept-Language: en-us
Accept-Encoding: text/xml
Connection: Keep-Alive

Server Response

POST /phones/phone HTTP/1.1
User-Agent: Mozilla/4.0 (compatible; MSIE5.01; Windows NT)
Host: www.api.phonestore.com
Accept-Language: en-us
Accept-Encoding: text/xml
Content-Length: 156
Connection: Keep-Alive
<phones>
	<phone>
		<name>iPhone5</name>
		<brand>Apple</brand>
		<price currency="irs">24500</price>
		<features>
			<camera>
				<front>1.2</front>
				<back>8</back>
			</camera>
			<memory>
				<storage scale="gb">32</storage>
				<ram scale="gb">2</ram>
			</memory>
			<network>
				<gsm>850/900/1800/1900 MHz</gsm>
				<HSPA>850/900/1900 MHz</HSPA>
			</network>
		</features>
	<phone>
</phones>

Sample 3 - Create a phone

POST /phones/phone HTTP/1.1
User-Agent: Mozilla/4.0 (compatible; MSIE5.01; Windows NT)
Host: www.api.phonestore.com
Accept-Language: en-us
Accept-Encoding: text/xml
Content-Length: 156
Connection: Keep-Alive
<phones>
	<phone>
		<name>iPhone5</name>
		<brand>Apple</brand>
		<price currency="irs">24500</price>
		<features>
			<camera>
				<front>1.2</front>
				<back>8</back>
			</camera>
			<memory>
				<storage scale="gb">32</storage>
				<ram scale="gb">2</ram>
			</memory>
			<network>
				<gsm>850/900/1800/1900 MHz</gsm>
				<HSPA>850/900/1900 MHz</HSPA>
			</network>
		</features>
	<phone>
</phones>

Server Response

HTTP/1.1 200 OK
Date: Mon, 29 August 11:53:27 GMT
Server: Apache/2.2.14 (Win32)
Last-Modified: Wed, 18 June 2014 09:18:16 GMT
Content-Type: text/xml
Content-Length: 15
<id>2122</id>