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 (URIs). 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 considered 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
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 has 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 patterns 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
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 the 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
- 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.
- 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.
- 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
.
- Query-String parameter
- Header parameter
Parameter Types
API Gateway supports three types of parameters in REST API: Query-String, Header, and Path.
The following example explains how you can use different parameter types 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 either by 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.
android v4.3 OS
and
8MP
camera. The URI
for this resource would look like:
/phones?features=androidosv4.3&cameraresolution=8MP
?
like the example seen below:
http://pie-3HKYMH2:5555/gateway/PetstoreAPI/1.0.3/store/inventory?APIKey=faab7ac6-97a4-4228-908d-f1930faba470
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
- 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 formatyyyy-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 formathh: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 formatyyyy-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
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>