Develop REST APIs in Policy Studio

REST API methods

Each REST API consists of zero or more REST API methods. Each method can provide custom polices for request, routing, and response processing. You can view the list of methods for a virtualized REST API by clicking the specific APIs node in the tree. The following example shows API methods for the virtualized Flickr REST API:

Define the REST API

Perform the following steps to define the REST API:

1. Right-click the APIs node, and select Add REST API to launch the wizard.
2. Enter a Name for the REST API (for example, Flickr API).
3. Enter a short Summary of the API functionality.
4. Enter the API Version. Defaults to 1.0.
5. For a detailed Description, select to Manually enter a description in the text box. Alternatively, select to Specify markdown file location. The default location is:

1. For details on writing documentation with Markdown, see http://daringfireball.net/projects/markdown/.
6. Click Next.

Specify exposure settings

Perform the following steps to configure how the REST API is exposed:

1. Specify the details for the inbound path that accepts requests:
   • Listening on HTTP: Select the HTTP Services group on which the API listens. Defaults to Default Services.
   • Virtual Host: Click the browse button to select a virtual host in the dialog. If no virtual host has already been configured, right-click the HTTP service node (for example, Default Services), and select Add a Virtual Host. For more details, see the topic on "Configuring virtual hosts" in the API Gateway Policy Developer Guide.
   • Base Path: Enter the base path prefix for the API (for example, /flickr/v1). This is the path that the API Gateway listens on for messages for the REST API. This path gives the API a namespace in the running API Gateway instance, under which its methods can reside (for example, /flickr/v1/getPhoto).
2. Click Finish.

Edit the REST API

When the REST API has been virtualized in the repository, it is displayed when you select the APIs node. At any stage, you can select the REST API in the panel on the right, and click Edit to edit any of its configuration settings. Similarly, click Remove to remove the API from the repository.

Define the method

Perform the following steps to define the REST API method:

1. Right-click a configured REST API node, and select Add API Method to launch the wizard.
2. Enter a Name for the REST API method (for example, Photo Search).
3. Enter a short Summary of the method functionality.
4. For a more detailed Description, select to Manually enter a description in the text box. Alternatively, select to Specify markdown file location. The default location is:

1. For details on writing documentation with Markdown, see http://daringfireball.net/projects/markdown/.
5. Click Next.

Specify exposure settings

Perform the following steps to configure the exposure settings:

1. Specify the details for the inbound path that accepts requests:
   • HTTP Method: Select the HTTP method (defaults to GET).
   • Using path: Enter the path for the REST API method (for example, /getPhoto).

Note

You can also specify path parameters (for example, an inbound path of /getPhoto/{userID}, where userID is a variable part of the path). When you specify an inbound path parameter, the parameter (in this case, userID) is automatically added in the Inbound parameters table below.

2. • Exposed on: Enter the base path that the method is exposed on. Defaults to the API base path (for example, /flickr/v1). For more details, see Specify exposure settings.
   • Resolved using: Select whether the path is resolved using Exact path match (default) or Longest path match. For more details on relative paths, see the API Gateway Policy Developer Guide.
2. Under Inbound parameters, click Add to specify a path parameter exposed by the method, and enter values for the following settings:
   • Name: Enter the parameter name (for example, userID).
   • Description: Enter a short parameter description.
   • Param Type: Select the parameter type from the list. Defaults to query.
   • Data Type: Select the data type from the list. Defaults to string.
   • Select whether the parameter is Required (unselected by default).
   • Select whether to Allow Multiple parameters (unselected by default).
   The inbound parameters entered in this table will be displayed on the API Manager page for this REST API method. For more details, see Example inbound parameters.
3. Select whether the inbound request should Fail if unspecified parameters are found (selected by default).
4. Under Content Types, select whether I wish to check inbound content types based on the following settings.
5. If selected, choose whether to Allow Content Types or Deny Content Types, and select the types that you wish to allow or deny.
5. Under Error Response Codes, click Add to specify an error response exposed by the method, and enter values for the following settings:
   • HTTP Response Code: Select or enter the response code name (for example, 400).
   • Reason: Select or enter the response code reason (for example, Bad Request).
   The response codes entered in this table will be displayed on the API Manager page for this REST API method.

Configure policies and monitoring settings

You can specify the following policy and monitoring settings for the API method:

1. Click Next, and select an optional Request Processing policy (for example, to check inbound requests for authentication or authorization).
2. Click Next, and select a required Routing policy, which configures how inbound requests are routed.

3. Click Next to select an optional Response Processing policy (for example, to validate or transform outbound responses). Alternatively, click Finish.

4. Click Next to select Monitoring options to configure how the API method is displayed in the API Gateway Manager and API Gateway Analytics consoles. Alternatively, click Finish. The monitoring options are as follows:
5. • Monitor API Service usage:
     Specifies whether to store message metrics for this API service. This is selected by default.
   • Monitor API Service usage per client:
     Specifies whether to generate reports monitoring which authenticated clients are calling which API services. This is selected by default.
   • Monitor client usage:
     If you want to generate reports on authenticated clients, but are not interested in which API services they are calling, select this option and deselect Monitoring service usage per client.
   • Message attribute:
     Enter the message attribute to use to identify authenticated clients. The default authentication.subject.id attribute stores the identifier of the authenticated user (for example, the user name or X.509 Distinguished Name).
5. Click Finish.

Edit the REST API method

When the API method has been virtualized in the repository, it is displayed under the APIs node. At any stage, you can select the REST API method in the panel on the right, and click Edit to edit any of its configuration settings. Similarly, click Remove to delete the API method from the repository.

{

   "id":"28a384e7-0b13-4679-ae1c-0c63666d3d8e"

   "activities": ["running", "swimming", "cycling"],

   "subObject": 

     "foo": "bar",

     "hello": "world",

     "yetAnotherObject": {

        "array": ["a", "b", "c"],

        "val": "greetings from yetAnotherObject"

      }

    }

}