About REST Service Assets
CentraSite's REST framework enables you to model APIs conforming to the (Resource Oriented Architecture) ROA design. For example, you might model an API that serves to expose the web service data and functionality as a collection of resources. Each resource will be 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 will be unique to the HTTP method and linked within the specific resource of the API.
The basic elements of a REST API in the CentraSite registry are as follows:
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)
Instructions throughout this guide use the term REST API when referring to REST Service assets.
About REST Applications (APIs)
In CentraSite, you document a REST API as an asset instance of the type REST Service or Virtual REST Service.
These APIs are typically collections of resources.
For example, consider an API that is defined to support an online phone store application. Assume, this sample Phone Store API currently has a database that defines the various brands of phones, features in the individual phones, and the inventory of each phone.
The Phone Store 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
REST (API) Parameters
Parameters defined at the higher API level are inherited by all Resources and by all Methods included in the individual Resources.
CentraSite permits different types of parameters at the API level, as described later in this topic.
REST Resources
Resources are the basic components of an API. Examples of resources from an online Phone Store 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. CentraSite's flexible metadata store captures the relationships of APIs with resources and ensures that the APIs are available in the right way.
For example, consider the case of an online Phone Store API. In this example, 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 needs to be addressable 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 direct the API what needs to be done with the addressed resource.
Resource URLs
An URL identifies the location of a specific resource.
For example, consider the case of our sample Phone Store API designed to support an online phone store application. The resources will 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. |
CentraSite supports the following patterns of resource URL: a collection of resources or a particular resource.
For example, consider the above example of an online Phone Store API.
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.
CentraSite permits different types of parameters at the Resource level, as described later in this topic.
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
CentraSite supports the standard HTTP methods for modeling APIs: GET, POST, PUT, DELETE, HEAD, OPTIONS, PATCH, TRACE, and CONNECT.
Important:
During virtualization of a REST Service, CentraSite does not support the following HTTP methods: HEAD, OPTIONS, TRACE, and CONNECT.
This is because, when a Virtual REST Service is published to Mediator gateway, CentraSite only supports the HTTP methods: GET, POST, PUT, PATCH, and DELETE, at run-time.
The following table describes the semantics of HTTP methods for our sample Phone Store API:
Resource URI | Supported HTTP Methods | Description |
/phones | GET | List all phones. |
/phones | POST | Creates a new phone with product code 412456. |
/phones/412456 | GET | Retrieves details of a phone whose product code is 412456. |
/phones/412456 | DELETE | Removes a phone whose product code is 412456. |
/phones/412456?fields=(make,features, bodytype) | GET | Retrieves additional details (such as Brand, Features, Body Type) of a phone whose product code is 412456. |
/phones/412456/make | GET | Identifies the brand of a phone whose product code is 412456. |
/phones/search?q=(make,eq,apple) | GET | Retrieves a list of all phones whose brand is Apple. |
/phones/412456?make=apple&features=3g | PUT | Updates a phone whose product code is 412456, brand is Apple, and also 3G compatible. |
/phones/412456/ | PATCH | Partial update for a specific phone. |
For information on the HTTP methods that CentraSite ships, in CentraSite Control, go to Administration > Taxonomies. On the Taxonomies page, enable the Show all Taxonomies option. Navigate to HTTP Methods in the list of taxonomies.
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.
CentraSite permits different types of parameters at the Method level, as described later in this topic.
REST 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 CentraSite, 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, say you have a header parameter called API Key that is used for consuming an API.
x-CentraSite-APIKey:a4b5d569-2450-11e3-b3fc-b5a70ab4288a
This parameter is specific to the entire API and to the individual components - resources and methods directly below the API. Such a parameter can be defined as a parameter at the API level.
At an API level, CentraSite allows you to define the following types of parameters:
Query-String parameter
Header parameter
Form 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 will not affect the higher API level parameters.
Consider our sample Phone Store 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, CentraSite allows you to define the following types of parameters:
Path parameter
Query-String parameter
Header parameter
Form 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 will not affect the higher API level or Resource level parameters.
For example, the Phone Store 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, CentraSite allows you to define the following types of parameters:
Query-String parameter
Header parameter
Form parameter
Parameter Types
CentraSite supports four types of parameters in REST API: Query-String, Path, Header, and Form.
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 Phone Store API. A customer, when trying to fetch a collection of phones, may wish to add options, such as, android v4.3 OS and 8MP camera. The URI for this resource could look like this:
/phones?features=androidosv4.3&cameraresolution=8MP
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 above online Phone Store API example. A customer may wish to fetch details about a phone {phone-id} whose product code is 412456. The URI for this resource could look like this:
/phones/412456
Important:
As a best practice, we recommend 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.
Header Parameters
Header parameters are HTTP headers. Headers often contain metadata information for the client, or server.
x-CentraSite-APIKey:a4b5d569-2450-11e3-b3fc-b5a70ab4288a
You can create custom headers, as needed. As a best practice, we recommend 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.
Form Parameters
Form parameters and values are encoded in the request message body, in the format specified by the content type (application/x-www-form-urlencoded).
features=androidosv4.3&cameraresolution=8MP
Important: Although CentraSite allows you to define parameters of the type Form at the API level, these parameters are not supported at run-time.
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.
CentraSite supports the following data types for parameters:
Data Type | Description |
String | Specifies a string of text. |
URL | Holds a URL/URI. This type of parameter only accepts values in the form: protocol://host:port/path Where: protocol is any protocol that java.net.URL supports. host is the name or IP address of a host machine. port is the port on which the host machine is listening. path (optional) is the path to the requested resource on the specified host. |
Boolean | Specifies a true or false value. |
Email | Specifies an email address. This data type only accepts values in the format: anyString@anyString |
Number | Specifies a numeric value. |
Duration | Specifies a value that represents a period of time as expressed in years, months, days, hours, minutes, and seconds. This duration is specified using an xs:duration format. It specifies a duration in terms of years (either 0 or 1), months, days, hours, minutes, and seconds. |
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. |
IP Address | Specifies a numeric IP address in the v4 or v6 format. |
Supported Content Types
Clients can optionally specify the content-type format they want the response to use.
CentraSite includes a set of predefined content types that are classified in the following taxonomy categories:
Predefined Taxonomy Category | Description |
Applications | An application content-type value to transmit API data or binary data and among other uses to implement an electronic mail file transfer service. Example: - application/xml - application/json |
Audio Files | An audio content-type value for transmitting audio or voice data. Example: - audio/basic - audio/mp4 |
Image Files | An image content-type value, for transmitting still image (picture) data. Example: - image/gif - image/png |
Text Files | A text content-type value to represent textual information in a number of character sets and formatted text description languages in a standardized manner. Example: - text/html - text/plain |
Video Files | A video content-type value for transmitting video or moving image data, possibly with audio as part of the composite video data format. Example: - video/mpeg |
Supported HTTP Status Codes
An API response returns a HTTP status code that indicates success or failure of the requested operation.
CentraSite allows you 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.
CentraSite includes a set of predefined response codes that are classified in the following categories:
Predefined Response Code Categories | Description |
1xx | Informational. |
2xx | Success. |
3xx | Redirection. Need further action. |
4xx | Client error. Correct the request data and retry. |
5xx | Server error. |
For information on the status codes that CentraSite supports out-of-the-box, in CentraSite Control, go to Administration > Taxonomies.
On the Taxonomies page, enable the Show all Taxonomies option. Navigate to HTTP Status Codes in the list of taxonomies.
HTTP/1.1 defines all the legal status codes. Examine these codes to determine which are appropriate for your API.
Consider the case of online Phone Store 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 | 204 (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 |
/phones/orders/{order-id}/paymentdetails | PATCH | 200 (ok); 404 (Not Found) if Order Resource not found |
REST Servers
REST Servers are an array of server objects, which provide connectivity information to a target server. REST Service endpoints are defined as REST Servers. The REST Servers form the base endpoint, with which API can be invoked. CentraSite allows you to configure multiple Server URL's for the REST Service. REST Server consist of Server URL and Server Variables. The server URL of an API is constructed by the domain, port, and server variables by enclosing them in curly braces. Use these variables to add a default value, and optionally one or more values and a description.
For example:
url: https://{subdomain}.site.com/{version} // Server URL
description: The main prod server
variables:
subdomain: // Server Variables enclosed in curly braces in Server URL
default: production // default value for Server Variables
version:
enum: // Possible values for Server Variables
- v1
- v2
default: v2
The variable values are replaced to form endpoint for API.
For example:
https://production.site.com/v1
https://production.site.com/v2
Links
Links allow the developer of the native API to define the relationship and traversal mechanism between a response and other operations. You can include links to other methods that are related to the response. This enables an API client to dynamically navigate the methods that are exposed by the API. For example, a method that returns the temperature in Fahrenheit for a given place may also include links to methods that return: a) the temperature in Centigrade; and b) the temperature of the place on a given day of the year.
Note:
You can define the complete response, or any part of it (response body schema, header parameter, or link), in the Components page; and reuse it wherever required by giving a reference.
Callbacks
A callback is an asynchronous API request that originates from the API server and is sent to the client in response to an earlier request sent by that client. APIs can use callbacks to signal an event of interest and share data related to that event. API clients that are interested in an event or data related to that event, include a callback URL in the request they send to the API.
Sample Requests and Responses
To illustrate the usage of an API, you provide sample request and response messages. Consider the sample Phone Store API that maintains a database of phones in different brands. The Phone Store 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
Sample 2 - Find a phone that does not exist
Client Request
GET /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
HTTP/1.1 404 Not Found
Accept: application/xml
Connection: Keep-Alive
User-Agent: Mozilla/4.0 (compatible; MSIE5.01; Windows NT)
Server: Apache/2.2.14 (Win32)
Sample 3 - Create a phone
Client Request
Server Response
Sample 4 - Adjusting the phone name
Client Request
Server Response