Example: Managing an API
This section explains everything you would want to know about an API and how to manage it with an example API phonestore. You can model an API that serves to expose API data and functionality as a collection of resources. Each resource is accessible with unique Uniform Resource Identifiers (URLs). In your API, you expose a set of HTTP operations (methods) to perform on a specific resource and capture the request and response messages and status codes that are unique to the HTTP method and linked within the specific resource of the API.
The basic elements of an API are:
The API itself (for example,
phonestore)
Its resource (
phones), available on the unique base URL (
/phones)
The defined HTTP method (
GET) for accessing the resource (
phones)
Parameters for request representations (
412456)
A request generated for this method (
Request 123)
A response with the status code received for this request (
Response ABCD)
The example API phonestore that we consider here is defined to support an online phone store application. Assume, this sample phonestore API currently has a database that defines the various brands of phones, features in the individual phones, and the inventory of each phone. This API is used as a sample to illustrate how to model URL patterns for resources, resource methods, HTTP headers and response codes, content types, and parameters for request representations to resources.
Base URL
The base URL of an API is constructed 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:
http://www.phonestore.com:8080/api
API Parameters
Parameters defined at the higher API level are inherited by all Resources and Methods included in the individual resources.
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, there are a number of ways to represent the data in the phone store database as an API. The verbs in the HTTP request maps to the operations that the database supports, such as select, create, update, delete.
Each resource has to be addressed by a unique URI. Along with the URI you're going to expose for each resource, you also need to 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
An URL identifies the location of a specific resource.
For example, for the online phonestore API, the resources have the following URLs:
URL | Description |
http://www.phonestore.com/api/phones | Specifies the collection of phones contained in the online store. |
http://www.phonestore.com/api/phones/412456 | Accesses a phone referenced by the product code 412456. |
http://www.phonestore.com/api/phones/412456/reviews | Specifies a set of reviews posted for a phone of code 412456. |
http://www.phonestore.com/api/phones/412456/reviews/78 | Accesses a specific review referenced by the unique ID 78 contained in the reviews of the phone of code 412456. |
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 patters are as follows:
Collection URL: http://phonestore.com/api/phones
Unique URL: http://phonestore.com/api/phones/412456/features to retrieve a collection resource describing the key features of phone whose product code is 412456.
Resource Parameters
Parameters defined at the higher Resource level are inherited by all Methods in the particular resource; it does not affect the API.
Resource Methods
Individual resources can define their capabilities using supported HTTP methods. To invoke an API, the client would 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 would make a service call HTTP GET on the following URL:
http://www.phonestore.com/phones/412456/features
Supported HTTP Methods
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 our sample Phone Store API:
Resource URI | HTTP Method | Description |
/phones/orders | GET | Asks for a representation of all of the orders. |
/phones/orders | POST | Attempts to create a new order, returning the location (in the Location HTTP Header) of the newly created resource. |
/phones/orders/{order-id} | GET | Asks for a representation of a specific Order resource. |
/phones/orders/{order-id} | DELETE | Requests the deletion of a specified Order resource. |
/phones/orders/{order-id}/status | GET | Asks for a representation of a specific Order's current status. |
/phones/orders/{order-id}/paymentdetails | GET | Asks for a representation of a specific Order's payment details. |
/phones/orders/{order-id}/paymentdetails | PUT | Updates a specific Order's payment details |
Method Parameters
Parameters defined at the lower 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. This indirectly 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. This indirectly 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 included in the API. Any parameter value you specify at the higher API level overrides the parameter value you set at the lower resource level or the lower method level if the parameter names are the same.
For example, if you have a header parameter 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 below the API. Such a parameter can be defined as a parameter at the API level.
At an API level, API Gateway allows you to 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 you specify at the higher resource level overrides the parameter value you set at the lower method level if the parameter names are the same. In contrast, the lower resource level parameters do not affect the higher API level parameters.
Consider the sample phonestore API maintains a database of reviews about different phones. Here is a request to display information about a particular user review, 78 of the phone whose product code is 412456.
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 below the particular resource. Such a parameter can be defined as a parameter at the resource level.
At a resource level, API Gateway allows you to 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 you set at the method level are used for the HTTP method execution. They are useful to restrict the response data returned for a HTTP request. Any parameter value you specify at the lower method level is overridden by the value set at higher API-level parameter or the higher resource-level parameter if the names are the same. In contrast, the lower 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 contributed by user Allen in 2013 about a phone whose product code is 412456.
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, API Gateway allows you to define the following types of parameters:
Query-String parameter
Header parameter
Parameter Types
API Gateway supports three types of parameters in REST API: Query-String, Header, and Path.
Let's have a look at different parameter types to see how they can be used for parameterizing the resources.
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 value is the itemIDValue. Query parameters are often used when filtering or paging through HTTP GET requests.
Now, consider the online phonestore API. A customer, when trying to fetch a collection of phones, might wish to add options, such as, android v4.3 OS and 8MP camera. The URI for this resource would look like:
/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, Software AG recommends that you prefix the header name with x-.
HTTP/1.1 defines the headers that can appear in a 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 wishes to fetch details about a phone {phone-id} whose product code is 412456. The URI for this resource would look like:
/phones/412456
Important:
As a best practice, Software AG recommends that you adopt the following conventions when specifying 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 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.
API Gateway supports the following data types for parameters:
Data Type | Description |
String | Specifies a string of text. |
Date | Specifies a date stamp that represents a specific date. The date input parameters allow year, month, and day input. This data type only accepts date values in the format yyyy-mm-dd |
Time | Specifies a timestamp that represents a specific time. The time input parameters allow hour and minute. This data type only accepts date values in the format hh:mm:ss |
Date/Time | Specifies a timestamp that represents a specific date and/or time. The date/time input parameters allow year, month, and day input as well as hour and minute. Hour and minute default to 0. This data type only accepts date values in the format yyyy-mm-dd; and time values in the format hh:mm:ss |
Integer | Specifies an integer value for the data type. This is generally used as the default data type for integral values. |
Double | Specifies the double data type value. This is a double-precision 64-bit IEEE 754 floating point and is generally used as the default data type for decimal values. |
Boolean | Specifies a true or false value. |
Supported HTTP Status Codes
An API response returns a HTTP status code that indicates success or failure of the requested operation.
API Gateway allows you to 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. The HTTP specification defines several status codes that are typically understood by clients.
API Gateway includes a set of predefined content types that are classified in the following taxonomy categories:
Category | Description |
1xx | Informational. |
2xx | Success. |
3xx | Redirection. Need further action. |
4xx | Client error. Correct the request data and retry. |
5xx | Server error. |
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 will respond:
Resource URI | Supported HTTP Methods | Supported HTTP Status Codes |
/phones/orders | GET | 200 (OK, Success) |
/phones/orders | POST | 201 (Created) if the Order resource is successfully created, in addition to a Location header that contains the link to the newly created Order resource; 406 (Not Acceptable) if the format of the incoming data for the new resource is not valid |
/phones/orders/{order-id} | GET | 200 (OK); 404 (Not Found) if Order Resource not found |
/phones/orders/{order-id} | DELETE | 200 (OK); 404 (Not Found) if Order Resource not found |
/phones/orders/{order-id}/status | GET | 200 (OK); 404 (Not Found) if Order Resource not found |
/phones/orders/{order-id}/paymentdetails | GET | 200 (OK); 404 (Not Found) if Order Resource not found |
/phones/orders/{order-id}/paymentdetails | PUT | 201 (Created); 406 (Not Acceptable) if there is a problem with the format of the incoming data on the new payment details; 404 (Not Found) if Order Resource not found |
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
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
Sample 3 - Create a phone
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>