APIs

API Gateway provides the ability to view, create, and manage APIs, and publish the APIs to API Portal for consumption. API administrators and users with the appropriate functional privileges can use API Gateway to create and manage APIs, and publish the APIs to API Portal or service registries from where they can be consumed.

Overview

API Gateway supports the following API types:

Asynchronous APIs

The synchronous and asynchronous nature of an API is a function of the time frame from the request to the return of data. In the case of synchronous APIs, the expectation is that there would be an immediate return of data, read from a database, from the internet, from the disk, or any other I/O source of data. You would use synchronous APIs where data or service availability, resources and connectivity are high and low latency is a requirement. The application requests data and waits for it until a value is returned.

In the case of asynchronous APIs, the availability of a resource, service or data store may not be immediate. An asynchronous API returns a response acknowledging the receipt of the request and it continues with the processing of the data till it is done, and returns a response to the client only when the processing of the data is completed. You would use asynchronous APIs where data or service availability and connectivity are low or over-saturated with demand. These APIs may use the callback functionality to send the callback request to the requester when the requested resource is ready.

Few APIs may take a lot of time to complete their processes, for example, processes such as purging or archiving of events, and bulk processing operations. In such a scenario, a time-out may occur for these API invocations as it takes longer time in the synchronous way where there is a wait period for the return of the data.

Example: Let us consider an example of purging logs.

In the synchronous way, the client application sends a request to the native API to purge a set of logs with a filter specified. The native API in turn sends out a response with an acceptance along with a Job ID. The client uses this job ID to send out requests to the native API to check whether the job is completed. In this case the client may have to send out multiple requests to check whether the job is done.

To avoid the hassle of multiple calls to the native API and waiting for the job to get done, you can implement an API to behave asynchronously to avoid multiple checks. You can implement a REST API with a callback option that can be used to call back the requestor when the job is done. In this scenario, when the client application sends out a request to the native API to purge a set of logs with a filter specified, the native API in turn sends out a response with an acknowledgement of having received the request and makes a note of the callback request URL that it receives in the request. Now, the client does not have to send out multiple requests to the native API to check whether the job is done. Instead once the job is done, the native API uses the callback URL details to send out a response to the requestor regarding the status of the job being done.

API Gateway provides asynchronous form of API support for REST APIs. API Gateway provides the capability of defining the callback component with the supported method parameters while creating a REST API. For details on creating an API with the callback definition, see Creating a REST API. In addition you can configure API Gateway to accept the requests from the client that contain the callback request URL and wrap it with its own URL before routing it to the native API. This lets API Gateway track the requests that the client sends to the native API and the responses that are sent by the native API to the client. For details on how to configure the callback processor settings to enable processing the callback requests, see Configuring API Callback Processor Settings. When a client sends a request with the callback request URL to the native API, API Gateway identifies the callback request URL in the incoming request, depending on the configured callback processor settings wraps the request coming from the client with its own URL and routes it to the native API. When the requested resource is ready, the native API sends a request to the callback request URL it has received in the request it has received from API Gateway. API Gateway then routes this request to the client. You can configure API Gateway to enforce any of the response processing policies that suits your needs on the immediate responses as well as the callback requests being sent from the native API to the client.

The callback requests-related event types can be distinguished by a new field with the value set to true and displayed in the dashboard in the transaction event type. For a normal request this field is set as false. The following are the field names that are displayed for various configured destinations:

You can create and manage APIs from the Manage APIs page. The page lists all the APIs, their description, and version number. You can create an API, delete an API, view API details, activate or deactivate an API, publish or unpublish an API, and view API analytics from this page.

You can create an API in one of the following ways:

An API importer generates an API from a URL or an input file in one of the supported formats. For example, the RAML importer installed with API Gateway reads a RAML file and generates a REST API that the RAML definition describes. The importer also uploads the RAML file to the API Gateway repository and links the file to the REST API.

The table lists the API types and the file formats required as input to create an API using an importer:

API type File format
REST RESTful API Modeling Language (RAML)

Yet Another Markup Language (YAML)

JavaScript Object Notation (JSON)

OpenAPI Specification (OAS)
SOAP Web Service Definition Language (WSDL)
OData Entity Data Model (EDMX)
GraphQL GraphQL Schema Definition Language (GraphQL SDL)

Creating an API by Importing an API from a File

You must have the API Gateway’s manage APIs or activate/deactivate APIs functional privilege assigned to perform this task.

To create an API by importing an API from a file

  1. Click APIs in the title navigation bar.
    A list of available APIs appears.

  2. Click Create API.

  3. Select Import API from file.

  4. Click Browse to select a file.

  5. Select the required file and click Open.
    The Swagger parser is a self-contained file with no external references and can be uploaded as is. If the RESTful API Modeling Language (RAML) file to be imported contains external references, the entire set of files must be uploaded as a ZIP file with a structure as referenced by the RAML file.

  6. Type a name for the API name in the Name field.

    • If you provide an API name, this overwrites the API name mentioned in the uploaded file and the API is displayed with the name provided.
    • If you do not provide an API name, the API name mentioned in the uploaded file is picked up and the API is displayed with that name.
    • If you do not provide an API name and the uploaded file does not have an API name mentioned, then the API is displayed as Untitled.

  7. Select the required type.
    The available types are OpenAPI , RAML, Swagger, and WSDL, and GraphQL SDL.

  8. Provide a version for the API in the Version field.

  9. Select the team to which the API must be assigned in the Team field.
    This field appears only when the Team feature is enabled. It displays only the teams that you are a part of. If you have the User Management functional privilege, all teams are displayed. You can select more than one team. To remove a team, click the icon icon next to the team to be removed.

  10. Click Create.

    An API is created with default policies.

Note: Since the GraphQL API schema does not contain a native endpoint, you must manually update the Native endpoint URL in the API details section and the Endpoint URI in the routing policy after you create a GraphQL API.

Creating an API by Importing an API from a URL

You must have the API Gateway’s manage APIs or activate/deactivate APIs functional privilege assigned to perform this task.

To create an API by importing an API from a URL

  1. Click APIs in the title navigation bar.
    A list of available APIs appears.

  2. Click Create API.

  3. Select Importing API from URL.

  4. Type the URL from where the API is to be imported.

  5. Select Protected to make the API a protected API.

  6. Type a name for the API name in the Name field.

    • If you provide an API name, this overwrites the API name mentioned in the uploaded file and the API is displayed with the name provided.
    • If you do not provide an API name, the API name mentioned in the uploaded file is picked up and the API is displayed with that name.
    • If you do not provide an API name and the uploaded file does not have an API name mentioned, then the API is displayed as Untitled.

  7. Provide a description for the API in the Description field.

  8. Select the required type.
    The available types are OData, OpenAPI, RAML, Swagger, and WSDL, and GraphQL SDL.

  9. Provide a version for the API in the Version field.

  10. Select the team to which the API must be assigned in the Team field.
    This field appears only when the Team feature is enabled. It displays only the teams that you are a part of. If you have the User Management functional privilege, all teams are displayed. You can select more than one team. To remove a team, click the icon icon next to the team to be removed.

  11. Click Create.
    An API is created with default policies.

Note:

  • Creating an API by importing swagger files from an HTTPS URL that is using self-signed certificates may fail. To workaround this, you can set the system environment variable as: export TRUST\_ALL=true, so that the invalid certificates are ignored. Be aware that setting this variable makes the swagger-parser ignore all invalid certificates too. So this workaround has to be used with caution.
  • Since the GraphQL API schema does not contain a native endpoint, you must manually update the Native endpoint URL in the API details section and the Endpoint URI in the routing policy after you create a GraphQL API.

Creating an API from Scratch

You can create REST APIs from scratch, meaning that you create the asset and set its attributes manually.

Overview of Creating a REST API from Scratch

The Create REST API wizard breaks down the task of creating a REST API from scratch into logical steps. The following figure illustrates the different pages of the wizard:

Basic Information

The Basic Information page includes fields that allow you to identify, categorize, and group an API.

Technical Information

The Technical Information page includes fields that allow you to define one or more server URLs for the API. You can also define and include variables in the URLs.

You can also specify parameters for data that must be included in every request to the API. For example, if you want a specific query parameter to be included in every request, you can add a parameter of the type Query and specify the value that it must include.

Resources and methods

The Resources and methods page includes fields that allow you to define the API resources and methods, including callback methods. In this page, you can add all the resources and their methods that are exposed by the API.

At the resource level, you add a resource by defining the following properties: name, path, and supported methods. You can additionally add parameters for data that must be included in every request to that resource. For example, if the methods in a resource are invoked using URLs that have a query string; you can add a query string parameter that captures the queries sent by the clients.

At the method level, you identify a method by adding an operation id. In addition, you can add tags that help you to categorize and search for similar methods. You can also add parameters at the method level. Similar to the parameters at the API and resource levels, method parameters enable you to capture and process the data that is sent in a particular request. In the case of method parameters, the data in the request for that method is captured and processed.

Method Requests

In the request section of a method, you can define the schema for requests that contain a JSON or XML payload. As a method can support multiple content types, you need to add a content type and then define the schema supported by that content type.

You can enter a schema or select an existing schema or global schema that you have previously added on the Components page, Schemas section. You can also add a sample for the schema that you have added or selected. These samples can be used for API mocking. They can also be used by end users to get a better understanding of the API.

Method Responses

You can define responses for different HTTP status codes. API Gateway gives you the flexibility to define responses for a status codes series (such as the 2XX series or the 4XX series) or for specific response codes, such as 201 or 400.

Note: If you have defined the response for a series and specific numbers in that series, the more specific one is used. Example: If you have added an entry for 2XX and 201, a response with the HTTP status code 200 will be the same as 2XX. However, a response with the HTTP status code 201 will pick the one that is defined for 201.

For each status code in a method response, you define the following:

Method 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. For more information about Asynchronous APIs, see Asynchronous APIs.

To enable API Gateway to process callback messages, you must configure the Callback processor settings, as explained in Configuring API Callback Processor Settings.

If your API supports callbacks, you can use API Gateway to process the initial requests, the callback URLs sent by clients, and the response sent by the API—including the callback messages. Clients can provide the callback URL to API Gateway in any of the following ways:

You must define the relevant parameter to capture the callback URL to process it. API Gateway can wrap the client callback URLs with its own URL to process these requests if the callback URL path defined in the following formats. Otherwise, API Gateway sends the requests received from client as it receives it.

Format Description
{$request.query.param-name} Where param-name is the name of the query parameter that contains the callback URL.
{$request.header.header-name} Where header-name is the name of the header that contains the callback URL.
{$request.body#/field-name} Where field-name is a field in the request body. If the field is an array, use the syntax {$request.body#/field-name/arrayIndex}, where arrayIndex is the index of the callback URL in the array.
${response.header.header-name} and ${response.headers.header-name} Where header-name is any of the valid header.
${request.query.param-name} Where param-name is the name of the query parameter that contains the callback URL.
${response.payload.jsonPath[queryValue]} Where queryValue is a valid JSON path expression.
${response.payload.xpath[queryValue]} Where queryValue is a valid XPath path expression.

If you have enabled API Gateway to process callback messages, API Gateway wraps the callback URL provided by the client and sends an API Gateway URL to the native API. When the native API invokes the same callback URL, API Gateway processes the response and applies the policies that you have defined.

API Gateway can apply the following policies on the callback messages:

API mocking

API mocking allows you to simulate a native API that is not available. The mock response that you define is returned to the client that invokes the API, if the native API is not available. API mocking is not available while you are creating an API. To use API mocking, you must edit the API after creating it and enable API mocking.

You must enable API mocking for an API after creating the API. For more information about API mocking, see API Mocking.

Components

The Components page allows you to add reusable elements that you can use in other pages of the wizard. You can reference these global elements using the $ref variable. You can add the following global elements:

Documentation

In the view mode, the Documentation page provides the following links:

In the edit mode, the Documentation page allows you to add a file that contains any documentation that you want to include with the API. This file is accessible only from API Gateway.

Creating a REST API

You must have the API Gateway’s manage APIs or activate/deactivate APIs functional privilege assigned to perform this task.

You can create a REST API from scratch by providing the basic information, technical information, and defining the resources and methods as required.

To create a REST API from scratch

  1. Click APIs in the title navigation bar.
    A list of all existing APIs appears.

  2. Click Create API.

  3. Select Create from scratch.

  4. Select REST.

  5. Click Create.
    The Basic information page of the Create REST API wizard appears.

  6. Provide the following information in the Basic information section:

    Field Description
    Name Name of the API.
    Version Version of the API being created.
    Maturity state Maturity state of the API. Available values are: Beta, Deprecated, Experimental, Production, Test.

    The available values depend on the Maturity states configured in the apiMaturityStatePossibleValues property under Administration > Extended settings section.
    API grouping Group under which the API would be categorized.

    Available values are: Finance Banking and Insurance, Sales and Ordering, Search, and Transportation and Warehousing.

    The available values depend on the groups configured in the apiGroupingPossibleValues property under Administration > Extended settings section.
    Tags Keywords for categorizing, identifying, and organizing APIs. You select from the list of existing tags or create new tags.
    Description Description of the API.

  7. Click Continue to provide technical information for this API >.

    Note: Click Save to save the API at this stage and close the Create REST API wizard.

  8. Enter the details of the servers that serve the API in the Add server details section.

    a. Click Add server and provide a Server URL and Description.
    You can include variables in the server URL by enclosing them in curly braces. These variables are added to the list of variables. However, you have to edit these variables to add a default value, and optionally one or more values and a description.

    b. Click Add variables and provide the following values:

    • Name

    • Description

    • Default

    • Value

    Note: Click + to add the value that you have entered.

    c. Click Add to add the variable.

  9. Click Add Parameter and provide the following information to add the API-level parameters.

    Field Description
    Name Name of the parameter.
    Description Description of the parameter.
    Type Specifies the parameter type.

    Available values: Query-string, Header, Cookie.
    Data type Specifies the data type.

    Available values: String, Date, Date time, Integer, Double, Boolean, File.
    Required Specifies the parameter is required if selected.
    Repeat Select if the input parameter is of type array.
    Value Specifies the possible values.

    Note: You need to define parameters only for data that you want API Gateway to process.

  10. Type a Service registry display name.
    By default, the API will be displayed in service registries with the name: APIName_Version. If you want the API to be displayed in the service registries with a different name, you can type the name here.

  11. Click Continue to provide Resource and methods for this API>.

    Note: Click Save to save the API at this stage and close the Create REST API wizard.

  12. Add resources to the API using the Resources and methods page:

    a. Click Add Resources and provide the following information:

    Field Description
    Resource name Name of the resource.

    This is the display name of the resource and resource path is used for execution.
    Resource path Specifies the path of the resource.

    The resource path should contain a “/”.
    Description Description of the resource.
    Supported methods Select the methods that are supported by the API: GET, HEAD, POST, PUT, DELETE, PATCH.

    b. Click Add. The resource is added. You can add multiple resources, if required.

    c. Add Tags.

    d. Click Add Resource Parameter and provide the following information:

    Field Description
    Name Name of the parameter.
    Reference If you want to reuse a global parameter defined on the Components page, select the parameter from the drop-down list.
    Description Brief description of the parameter.
    Type Specifies the parameter type.

    Available values: Path, Header, Query-string, Cookie.
    Data type Specifies the data type.

    Available values: String, Date, Date time, Integer, Double, Boolean, File.
    Required Specifies the parameter is required if selected.
    Repeat Select if the input parameter is of type array.
    Value Specifies the possible values for the parameter.

    e. Click + Add to add the resource parameter.

  13. For each supported method that you have added for a resource, enter the following information:

    a. Common information

    Field Description
    Description Type a description for the operation.
    OperationId Type an operation ID.
    Tags Type or select the keywords that you want to add to the operation.

    b. Method parameters

    Field Description
    Name Name of the parameter.
    Reference If you want to reuse a global parameter defined on the Components page, select the parameter from the drop-down list.
    Description Brief description of the parameter.
    Type Specifies the parameter type.

    Available values: Query-string, Header, Cookie.
    Data type Specifies the data type.

    Available values: String, Date, Date time, Integer, Double, Boolean, File.
    Required Specifies the parameter is required, if selected.
    Repeat Select if the input parameter is of type array.
    Value Specifies the possible values for the parameter.

    c. Requests: You can select an existing global request defined on the Components page or specify a new request.

    To enter a new request, select New request and provide the following information:

    To add a new request that has to be processed, click Add Request + and provide the following information:

    • Content type: Select one and click Add.

    • Schema: Type a schema in the text box or select an existing schema from the Select a Schema list. You can also click Add global schema and create a new global schema on the Components page. After creating the global schema you can select it from the Select a Schema list.

    • Sample: Type a sample for selected schema. This sample can be used for API mocking, if required.

    To use an existing global request to process a request, select Global request and provide the following information:

    • Name:

    • Reference: select one and click Add.

    d. Responses: First, add a status code using the Status Code drop-down list.

    Next, click on the status code to select it. For the selected status code, you can select an existing global response defined on the Components page or enter a new response. To enter a new response, select New response and define the response by adding a schema and a sample for the response body, header parameters, and links.

    Note: You can also define the response for an HTTP status code series, such as 2** or 4**.

    To define a new response for the selected status code, click Add response + and provide the following information:

    • Content type: select one and click Add.

    • Schema: Type a schema in the text box or select an existing schema from the Select a Schema list. You can also click Add global schema and create a new global schema on the Components page. After creating the global schema you can select it from the Select a Schema list.

    • Sample: Type a sample for selected schema. This sample can be used for API mocking, if required.

    To use an existing global response, select Global response and provide the following information:

    • Name: Name of the response.

    • Reference: select one and click Add.

    To add a header parameter, click + Add header parameter and enter the following information to add a header parameter:

    Field Description
    Name Name of the parameter.
    Reference If you want to reuse a global parameter defined on the Components page, select the parameter from the drop-down list.
    Description Brief description of the parameter.
    Type Specifies the parameter type.

    Available values: Header.
    Data type Specifies the data type.

    Available values: String, Date, Date time, Integer, Double, Boolean, File.
    Required Specifies the parameter is required if selected.
    Repeat Select if the input parameter is of type array.
    Value Specifies the possible values for the parameter.

    Click + in the Value text box to add a value to the list, and click Add to add the header.

    To add a link, click + Add links and enter the following information to add a link:

    • Name: Name of the link.

    • Description: Description for the link.

    • Link: You can add a new link or select an existing global link that is defined on the Components page.

    To add a new link, select New link and enter the following information:

    • Type: Select OperationId for local operations only. OperationRef can be used for both local and external operations.

    • Value: If Type is OperationRef, provide a reference to the target operation using the JSON Reference syntax (using by the $ref keyword); and if the Type is OperationId provide the OperationId of the target operation.

    • Parameters: Specify the parameters of the target operation that are required to follow the link. Enter a Name and Value, and click Add.

    • Request body: Enter a request body only if the target operation has a body. Define the contents of the body of the target operation.

    To include an existing global link, select Global link and then select an existing global link from the Reference drop-down list.

    e. Callbacks: You can add the callbacks that are supported by the method.
    You can add new callbacks and select existing global callbacks.

    Note: For more information about using callbacks to develop asynchronous APIs, see Asynchronous APIs in Overview. For more information on defining and using callbacks in API Gateway, see Overview of Creating a REST API from Scratch.

    To specify a new callback, click + Add callbacks and define the callback:

    • Name: A name for the callback resource.

    • Click + Add resources and provide details of the API that serves as the callback API.

    Note: The user interface and procedure for defining a callback is similar to defining a resource and methods within the resource.

    To include a global callback defined on the Components page, provide the following information:

    • Name: Name of the callback resource.

    • Reference: If you want to reuse a global callback defined on the Components page, select the callback from the drop-down list and click Add.

  14. Click Continue to provide Mocking information for this API>.

    Note: Click Save to save the API at this stage and close the Create REST API wizard.

    The API mocking page appears. API mocking is not enabled for a new API: You must edit the API and enable API mocking after creating the API.

  15. Click Continue to define API components for this API>.
    Alternatively, you can click Components.

    Note: Click Save to save the API at this stage and close the Create REST API wizard.

  16. Define the reusable elements that you want to reuse in other pages of the Create REST API wizard.
    An API may have several elements that are common across resources and methods, such as schemas for response bodies. You can place such common elements in the Components section and reference them using the $ref alias.

    a. In the Schemas section, click + Add schema and provide the following information:

    Field Description
    Name Name of the schema.
    Schema type Specifies the schema type.

    Available types: Inline schema and External schema.
    Value Specifies the value for the schema type selected.

    For an inline schema, type the request and response values.

    For an external schema, click Browse to upload a schema.

    Click + Add to add the schema component.

    b. In the Parameters section, click + Add parameter and provide the following information:

    Field Description
    Name Name of the parameter.
    Description Description of the parameter.
    Type Specifies the parameter type.

    Available values: Path, Query-string, Header, and Cookie.
    Data type Specifies the data type.

    Available values: String, Date, Date time, Integer, Double, Boolean, and File.
    Required Specifies the parameter is required if selected.
    Repeat Select if the input parameter is of type array.
    Value Specifies the possible values for the parameter.

    Click + Add to add the parameter component.

    c. In the Headers section, click + Add header and provide the following information:

    Field Description
    Name Name of the header.
    Description Description of the header.
    Type Specifies the header type. This is fixed as Header for headers.
    Data type Specifies the data type.

    Available values: String, Date, Date time, Integer, Double, Boolean, and File.
    Required Specifies the header is required if selected.
    Repeat Select if the input parameter is of type array.
    Value Specifies the possible values for the header.

    Click + Add to add the header component.

    d. In the Examples section, click + Add examples and provide the following information:

    Field Description
    Name Name of the example.
    Summary Description of the example.
    Value The content of the example.

    Click + Add to add the example component.

    e. In the Links section, click + Add links and provide the following information:

    Field Description
    Name Name of the link.
    Description Description of the link.
    Type Specifies the link type: OperationId or OperationRef.
    Value Path to the target operation or a reference to the target operation.
    Parameter name Name of the parameter that needs to be passed as a parameter to the target operation.
    Parameter value Value for the parameter. Click + Add to add the parameter. You can additional parameters if required.
    Request body Payload of the request sent to the target operation.

    Click Add to add the link component.

    f. In the Callbacks section, click + Add callback and provide the following information:

    i. Type a name for the callback.

    ii. Click + Add resources.

    iii. Type the Callback path.

    iv. Select the supported methods.

    v. Click Add.

    vi. For each method that you have just added, complete the next two steps.

    vii. Click + Add Resource Parameter and add the required resource parameters.
    The procedure for adding resource parameters is given in Step 11d.

    viii. Define the selected methods. The procedure for defining methods is given in Step 12.

    g. In the Request Bodies section, click + Add request and provide the following information:

    Field Description
    Name Name of the request.
    Content type Select a content type from the list.
    Schema You can also select an existing schema.
    Sample Type a sample of the schema.

    Click Add to add the request component.

    h. In the Responses section, click + Add Response and provide the following information:

    Field Description
    Name Name of the response.
    Content type Click Add.
    Schema You can also select an existing schema.
    Sample Type a sample of the schema.
    Header Parameter Click + Add Header Parameter and provide the required information. Then, click + Add to add the header parameter.
    Links Click + Add Links and provide the required information. Then, click Add to add the link.

    Click Add to add the response component.

  17. Click Continue to provide API documents for this API>.

    Note: Click Save to save the API at this stage and close the Create REST API wizard.

    The Documentation page appears.

  18. Type a display name and click Browse to select a file.

  19. Click + Add to upload the file and add a new row.

  20. Click Save to save your changes and create the API.

Creating a REST API

You must have the API Gateway’s manage APIs or activate/deactivate APIs functional privilege assigned to perform this task.

You can create a REST API from scratch by providing the basic information, technical information, and defining the resources and methods as required.

To create a REST API from scratch

  1. Click APIs in the title navigation bar.
    A list of all existing APIs appears.

  2. Click Create API.

  3. Select Create from scratch.

  4. Click Create.
    The Basic information page of the Create REST API wizard appears.

  5. Provide the following information in the Basic information section:

    Field Description
    Name Name of the API.
    Version Version of the API being created.
    Team Team to which the application must be assigned to. You can select more than one team. To remove a team, click the icon icon next to the team to be removed.
    Maturity state Maturity state of the API. Available values are: Beta, Deprecated, Experimental, Production, Test.
    The available values depend on the Maturity states configured in the apiMaturityStatePossibleValues property under Administration > Extended settings section
    API grouping Group under which the API would be categorized.
    Available values are: Finance Banking and Insurance, Sales and Ordering, Search, and Transportation and Warehousing.
    The available values depend on the groups configured in the apiGroupingPossibleValues property under Administration > Extended settings section
    Tags Keywords for categorizing, identifying, and organizing APIs. You select from the list of existing tags or create new tags.
    Description Description of the API.

  6. Click Continue to provide technical information for this API >.

    Note: Click Save to save the API at this stage and close the Create REST API wizard.

  7. Enter the details of the servers that serve the API in the Add server details section.

    a. Click Add server and provide a Server URL and Description.
    You can include variables in the server URL by enclosing them in curly braces. These variables are added to the list of variables. However, you have to edit these variables to add a default value, and optionally one or more values and a description.

    b. Click Add variables and provide the following values:

    • Name
    • Description
    • Default
    • Value

    Note: Click + to add the value that you have entered.

    c. Click Add to add the variable.

  8. Click Add Parameter and provide the following information to add the API-level parameters.

    Field Description
    Name Name of the parameter.
    Description Description of the parameter.
    Type Specifies the parameter type.
    Available values: Query-string, Header, Cookie.
    Data type Specifies the data type.
    Available values: String, Date, Date time, Integer, Double, Boolean, File.
    Required Specifies the parameter is required if selected.
    Repeat Select if the input parameter is of type array.
    Value Specifies the possible values.

    Note: You need to define parameters only for data that you want API Gateway to process.

  9. Type a Service registry display name.
    By default, the API will be displayed in service registries with the name: APIName_Version. If you want the API to be displayed in the service registries with a different name, you can type the name here.

  10. Click Continue to provide Resource and methods for this API>. >Note: Click Save to save the API at this stage and close the Create REST API wizard.

  11. Add resources to the API using the Resources and methods page:

    a. Click Add Resources and provide the following information:

    Field Description
    Resource name Name of the resource.
    This is the display name of the resource and resource path is used for execution.
    Resource path Specifies the path of the resource.
    The resource path should contain a “/”.
    Description Description of the resource.
    Supported methods Select the methods that are supported by the API: GET, HEAD, POST, PUT, DELETE, PATCH.

    b. Click Add. The resource is added. You can multiple resources, if required.

    c. Add Tags.

    d. Click Add Resource Parameter and provide the following information:

    Field Description
    Name Name of the parameter.
    Reference If you want to reuse a global parameter defined on the Components page, select the parameter from the drop-down list.
    Description Brief description of the parameter.
    Type Specifies the parameter type.
    Available values: Path, Header, Query-string, Cookie.
    Data type Specifies the data type.
    Available values: String, Date, Date time, Integer, Double, Boolean, File.
    Required Specifies the parameter is required if selected.
    Repeat Select if the input parameter is of type array.
    Value Specifies the possible values for the parameter.

    e. Click + Add to add the resource parameter.

  12. For each supported method that you have added for a resource, enter the following information:

    a. Common information:

    Field Description
    Description Type a description for the operation.
    OperationId Type an operation Id.
    Tags Type or select the keywords that you want to add to the operation.

    b. Method parameters

    Field Description
    Name Name of the parameter.
    Reference If you want to reuse a global parameter defined on the Components page, select the parameter from the drop-down list.
    Description Brief description of the parameter.
    Type Specifies the parameter type.
    Available values: Query-string, Header, Cookie.
    Data type Specifies the data type.
    Available values: String, Date, Date time, Integer, Double, Boolean, File.
    Required Specifies the parameter is required, if selected.
    Repeat Select if the input parameter is of type array.
    Value Specifies the possible values for the parameter.

    c. Requests: You can select an existing global request defined on the Components page or specify a new request. To enter a new request, select New request and provide the following information:
    To add a new request that has to be processed, click Add Request + and provide the following information:

    • Content type: Select one and click Add.
    • Schema: Type a schema in the text box or select an existing schema from the Select a Schema list. You can also click Add global schema and create a new global schema on the Components page. After creating the global schema you can select it from the Select a Schema list.
    • Sample: Type a sample for selected schema. This sample can be used for API mocking, if required.

    To use an existing global request to process a request, select Global request and provide the following information:
    • Name:
    • Reference: select one and click Add.

    d. Responses: First, add a status code using the Status Code drop-down list.
    Next, click on the status code to select it. For the selected status code, you can select an existing global response defined on the Components page or enter a new response. To enter a new response, select New response and define the response by adding a schema and a sample for the response body, header parameters, and links.

    Note: You can also define the response for an HTTP status code series, such as 2** or 4**.

    To define a new response for the selected status code, click Add response + and provide the following information:

    • Content type: select one and click Add.
    • Schema: Type a schema in the text box or select an existing schema from the Select a Schema list. You can also click Add global schema and create a new global schema on the Components page. After creating the global schema you can select it from the Select a Schema list.
    • Sample: Type a sample for selected schema. This sample can be used for API mocking, if required.

    To use an existing global response, select Global response and provide the following information:

    • Name: Name of the response.
    • Reference: select one and click Add.

    To add a header parameter, click + Add method parameter and enter the following information to add a method parameter:

    Field Description
    Name Name of the parameter.
    Reference If you want to reuse a global parameter defined on the Components page, select the parameter from the drop-down list.
    Description Brief description of the parameter.
    Type Specifies the parameter type.
    Available values: Header.
    Data type Specifies the data type.
    Available values: String, Date, Date time, Integer, Double, Boolean, File.
    Required Specifies the parameter is required if selected.
    Repeat Select if the input parameter is of type array.
    Value Specifies the possible values for the parameter.

    Click + in the Value text box to add a value to the list, and click Add to add the header.

    To add a link, click + Add links and enter the following information to add a link:

    • Name: Name of the link.
    • Description: Description for the link.
    • Link: You can add a new link or select an existing global link that is defined on the Components page.
      • To add a new link, select New link and enter the following information:
      • Type: Select OperationId for local operations only. OperationRef can be used for both local and external operations.
      • Value: If Type is OperationRef, provide a reference to the target operation using the JSON Reference syntax (using by the $ref keyword); and if the Type is OperationId provide the OperationId of the target operation.
      • Parameters: Specify the parameters of the target operation that are required to follow the link. Enter a Name and Value, and click Add.
      • Request body: Enter a request body only if the target operation has a body. Define the contents of the body of the target operation.
    To include an existing global link, select Global link and then select an existing global link from the Reference drop-down list.

    e. Callbacks: You can add the callbacks that are supported by the method.
    You can add new callbacks and select existing global callbacks.

    Note: For more information about using callbacks to develop asynchronous APIs, see Asynchronous APIs. For more information on defining and using callbacks in API Gateway, see Overview of Creating a REST API from Scratch.

    To specify a new callback, click + Add callbacks and define the callback:

    • Name: A name for the callback resource.
    • Click + Add resources and provide details of the API that serves as the callback API.

    Note: The user interface and procedure for defining a callback is similar to defining a resource and methods within the resource.

    To include a global callback defined on the Components page, provide the following information:

    • Name: Name of the callback resource.
    • Reference: If you want to reuse a global callback defined on the Components page, select the callback from the drop-down list and click Add.

  13. Click Continue to provide Mocking information for this API>.

    Note: Click Save to save the API at this stage and close the Create REST API wizard.

    The API mocking page appears. API mocking is not enabled for a new API: You must edit the API and enable API mocking after creating the API.

  14. Click Continue to define API components for this API>.
    Alternatively, you can click Components.

    Note: Click Save to save the API at this stage and close the Create REST API wizard.

  15. Define the reusable elements that you want to reuse in other pages of the Create REST API wizard.
    An API may have several elements that are common across resources and methods, such as schemas for response bodies. You can place such common elements in the Components section and reference them using the $ref alias.
    a. In the Schemas section, click + Add schema and provide the following information:

    Field Description
    Name Name of the schema.
    Schema type Specifies the schema type. Available types: Inline schema and Upload schema.
    Value Specifies the value for the schema type selected. For an inline schema, type the request and response values.
    For an external schema, click Browse to upload a schema

    Click + Add to add the schema component.

    b. In the Parameters section, click + Add parameter and provide the following information:

    Field Description
    Name Name of the parameter.
    Description Description of the parameter.
    Type Specifies the parameter type.
    Available values: Path, Query-string, Header, and Cookie.
    Data type Specifies the data type.
    Available values: String, Date, Date time, Integer, Double, Boolean, and File.
    Required Specifies the parameter is required if selected.
    Repeat Select if the input parameter is of type array.
    Value Specifies the possible values for the parameter.

    Click + Add to add the parameter component.

    c. In the Headers section, click + Add header and provide the following information:

    Field Description
    Name Name of the header.
    Description Description of the header.
    Type Specifies the header type. This is fixed as Header for headers.
    Data type Specifies the data type.
    Available values: String, Date, Date time, Integer, Double, Boolean, and File.
    Required Specifies the header is required if selected.
    Repeat Select if the input parameter is of type array.
    Value Specifies the possible values for the header.

    Click + Add to add the header component.

    d. In the Examples section, click + Add examples and provide the following information:

    Field Description
    Name Name of the example.
    Summary Description of the example.
    Value The content of the example.

    Click + Add to add the example component.

    e. In the Links section, click + Add links and provide the following information:

    Field Description
    Name Name of the link.
    Description Description of the link.
    Type Specifies the link type: OperationId or OperationRef.
    Value Path to the target operation or a reference to the target operation.
    Parameter name Name of the parameter that needs to be passed as a parameter to the target operation.
    Parameter value Value for the parameter. Click + Add to add the parameter. You can additional parameters if required.
    Request body Payload of the request sent to the target operation.

    Click Add to add the link component.

    f. In the Callbacks section, click + Add callback and provide the following information:

    1. Type a name for the callback.
    2. Click + Add resources.
    3. Type the Callback path.
    4. Select the supported methods.
    5. Click Add.
    6. For each method that you have just added, complete the next two steps.
    7. Click + Add Resource Parameter and add the required resource parameters.
      The procedure for adding resource parameters is given in Step 11d.
    8. Define the selected methods. The procedure for defining methods is given in Step 12.

    g. In the Request Bodies section, click + Add request and provide the following information:

    Field Description
    Name Name of the request.
    Content type Select a content type from the list.
    Schema You can also select an existing schema.
    Sample Type a sample of the schema.

    Click Add to add the request component.

    h. In the Responses section, click + Add Response and provide the following information:

    Field Description
    Name Name of the response.
    Content type Click Add.
    Schema You can also select an existing schema.
    Sample Type a sample of the schema.
    Header Parameter Click + Add Header Parameter and provide the required information. Then, click + Add to add the header parameter.
    Links Click + Add Links and provide the required information. Then, click Add to add the link.

    Click Add to add the response component.

  16. Click Continue to provide API documents for this API>.

    Note: Click Save to save the API at this stage and close the Create REST API wizard.

    The Documentation page appears.

  17. Type a display name and click Browse to select a file.

  18. Click + Add to upload the file and add a new row.

  19. Click Save to save your changes and create the API.

API Mashups

Servers that provide an API may expose a vast set of functionality. However, each individual service in the API usually provides a very specific functionality. While this is usually effective, sometimes it is useful or required to consolidate a few services and expose them as a single service. In other situations, you might want to extend a service with the functionality provided by an external API. API mashups address these requirements for grouping services and exposing them as a single service.

Note: Currently, API Gateway supports API mashups for REST APIs only. You can define a mashup only in a REST API and only REST APIs can be included in the mashup.

The APIs that are included in an API mashup (participating APIs) can be connected to each other in the following ways:

Usage scenario: API chaining

Assume an API that provides information about courses offered by different universities in a given location. This API provides a service that returns the list of universities for a given course name and postal code. This service could be:


GET /universities?course=medicine&postalcode=600012

The provider of the API wants to extend this API for use in mobile applications that have access to users’ location. As mobile applications can access a user’s location in terms of longitude and latitude, this involves first retrieving the postal code for the users’ current location and then passing that information to the existing API.

Suppose there is a publically available API that returns the postal code based on longitude and latitude values. This service could be:


GET /postalcode?lat=331&long=22324321

If this public API meets other requirements, such as security, performance, and usage limits, it can be utilized to deliver the required functionality.

Using an API mashup, you can create and expose a single service that calls both services: the external service that returns the postal code and the existing service that provides the list of universities. The resulting service could be:


GET /universities?course=medicine&lat=331&long=22324321

Usage scenario: API aggregation

Assume an IT services provider that provides hosting and cloud services to its customers. Users can create accounts for the different types of services that they need to use: bare metal servers, Virtual Private Servers, platforms as a service, and so on. A customer has multiple types of accounts. The statement for each type of account is returned by a different API. The API provider wants to provide a single API that consolidates the statements of a given customer and returns a single response with all the information.

Key Features of a REST API Mashup

Considerations for Creating an API Mashup

Structure of an API Mashup

An API mashup consists of one or more mashup steps, and each step invokes an API. A mashup step defines the request for the API that it invokes. A step can use the data objects provided by API Gateway to access data in the initial request sent to the operation that has the mashup and any of the previous steps.

The following table summarizes the data objects and variables that are available in API Gateway:

Object/Variable Type Possible values
paramStage
  • request
  • response
paramType
  • payload or body
  • headers
  • query
  • path
  • httpMethod
  • statusCode
  • statusMessage
queryType
  • xpath
  • jsonPath
  • regex

The following data objects are available to a mashup step:

Note: Data objects from any of the steps of the mashup can also be accessed by response processing policies and error processing policies of the API that contains the mashup.

Creating an API Mashup

To create a mashup you require:

To create a mashup in a REST API

  1. Click APIs in the title navigation bar. A list of all registered APIs appears.

  2. Click the required API.
    The API details page appears.

  3. Click Edit.

  4. Click Mashups.
    The Mashups tab appears. It displays the resources in the API and their methods on the left and an empty (Default routing) routing diagram.

    Note: If the API does not have any mashup, the Mashup tab displays the list of resources only in the Edit mode; the tab is empty in the view mode.

  5. In the List of resources, click the resource in which you want to include the mashup.
    The resource tab expands and the methods included in the resource are displayed.

  6. Click the toggle button to enable the method in which you want to create the mashup.

    Note: If you use the toggle button and disable a method that has a mashup, the mashup definition for that method is immediately cleared.

  7. Click Add invoke to add a mashup step.

    a. Connect the step to Start. The Start and Stop terminators and all steps have connection points that you can connect to the other steps and terminators.

    Tip: To select a connection point and connect it to another connection point: i) Hover the mouse over the top or bottom of the step or terminator till the connection point is highlighted; ii) Click the connection point and drag to the other step or terminator.

    b. Configure the step properties as desired.
    The Mashup Routing panel that appears on the right side of the mashup canvas displays the properties for the selected step. You can configure the following properties using the Mashup Routing panel:

    Section Field Description
    Mashup step name Provide a name for the mashup step that is unique within the mashup.
    API Endpoint The API endpoint that you want to invoke in the mashup step. The API must be published on the current API Gateway instance.
    API Gateway API The endpoint of the API that you want to use. You can type a few letters and select from the autocomplete list.
    Resource The resource in the API that you want to use. You can type a few letters and select a resource from the autocomplete list.
    Method The specific method of the resource that you want to invoke.
    Execute outbound authentication policy Select if you want the outbound security policies of the participating API to be enforced in the context of an API mashup.
    Headers
    Use incoming Headers Select to use the headers in the incoming request.
    Custom Headers Custom headers that you can add in addition or instead of the incoming headers. Each custom header must have the following fields:

    • Header Name

    • Header Value
    Query Parameters Provide the following values:

    • Query Parameter Name

    • Query Parameter Value
    Path Parameters Provide the following values:

    • Path Parameter Name

    • Path Parameter Value
    Payload Type the Payload.
    XSLT Document Click Add xslt document and select the XSLT file for transforming the payload. Provide the following values:

    • XSLT File

    • Feature Name

    • Feature value

      • For information about transforming the payload using XSLT, see Request Transformation.
    XSLT Transformation alias Click Add xslt transformation alias and select an existing XSLT transformation alias.
    Advanced Transformation
    webMethods IS service Click Add webMethods IS service and provide the following values:

    • webMethods IS Service

    • Run As User

    • Select Comply to IS Spec

      • For information about these fields and using the webMethods IS Service, see Invoke webMethods IS.
    webMethods IS Service Alias For information about the webMethods IS Service Alias, see Invoke webMethods IS.
    Transformation Metadata
    Namespace Provide the following values:

    Custom Pipeline Variables You can use custom pipeline variables to hold values that need to be used in another step of the API mashup. Provide the following values:

    • Name

    • Value

      • For more information, see Structure of an API Mashup above.

    Note: In several fields, such as Header Value within custom headers, Query Parameter Value, and Path Parameter Value, you can use values from previous steps and other data using the variable and alias framework provided by API Gateway. For more information, For more information, see Structure of an API Mashup above.

  8. Click Add aggregator to add an aggregator step.

    Note: You can also add an aggregator step by connecting two invocation steps to the same previous step. An aggregator step is automatically added after the steps when you connect the second step to the same previous step.

  9. If you have added the aggregator by clicking Add aggregator, add the following connections:

    a. Connect the steps that need to be aggregated to the aggregator step.

    b. Connect the aggregator step to the next step.

  10. To add additional steps to the aggregated block, complete the following steps:

    a. To add a new step to the aggregated block, click Add invoke and connect the new step to the same previous step.
    You can configure the properties of the new step immediately or later. For details on configuring the step properties, see step 7.

    b. To add an existing step to the aggregated block, delete the connections of the step, if any and then connect the step to the previous step for the aggregated block and the aggregator step.

  11. Click the mashup step and configure the properties of the mashup step as desired.
    You can configure the mashup step properties using the Mashup Aggregator action panel that appears on the right side of the mashup canvas when you click the aggregator step. You can configure the following properties using the Mashup Aggregator action panel:

    Section Field Description
    Headers
    Use incoming Headers Select to use the headers in the incoming request.
    Custom Headers Custom headers that you can add in addition or instead of the incoming headers. Each custom header must have the following fields:

    • Header Name

    • Header Value
    Query Parameters Provide the following values:

    • Query Parameter Name

    • Query Parameter Value
    Path Parameters Provide the following values:

    • Path Parameter Name

    • Path Parameter Value
    Payload Type the Payload.
    XSLT Document Click Add xslt document and select the XSLT file for transforming the payload. Provide the following values:

    • XSLT File

    • Feature Name

    • Feature value
    XSLT Transformation alias Click Add xslt transformation alias and select an existing XSLT transformation alias.
    Advanced Transformation
    webMethods IS Service Click Add webMethods IS service and provide the following values:

    • webMethods IS Service

    • Select a Run As User

    • Select Comply to IS Spec

      • For information about these fields and using the webMethods IS Service, see Invoke webMethods IS.
    webMethods IS Service Alias Select an existing webMethods IS service alias.
    Transformation Metadata
    Namespace Provide the following values:
    • Namespace Prefix
    • Namespace URI
    Custom Pipeline Variables You can use custom pipeline variables to hold values that need to be used in another step of the API mashup. Provide the following values:
    • Name
    • Value

      • For more information, see Structure of an API Mashup above.
    Mashup Response Transformation
    • Select Aggregate response
    • Payload

    Note: In several fields, such as Header Value within custom headers, Query Parameter Value, and Path Parameter Value, you can use values from previous steps and other data using the variable and alias framework provided by API Gateway. For more information, see Structure of an API Mashup above.

  12. Add, configure, and connect additional API invocation steps and API aggregator steps as desired.

  13. Click Save.
    The mashup is created for the selected method.

Note: You must activate the API to make the mashup available to client applications. For more information about activating an API, see Activating an API.

Viewing API List and API Details

You can view the list of registered APIs, activate, delete, or view analytics of a specific API in the Manage APIs page. In addition, you can view API details, modify API details, activate and deactivate an API in the API details page.

Note: If you encounter any problem viewing the API details with a message that says API loading has failed, this would be because the property watt.server.http.jsonFormat has been set to a value is set to a value that is not parsed (the default value), which API Gateway does not support.

To view API list and API details

  1. Click APIs in the title navigation bar.
    A list of all registered APIs appears. The APIs are sorted based on their names. When there is more than one API with same name, they are sorted based on their system versions. The Date field next to the Version field displays the API creation date.
    You can also perform the following operations in the Manage API page:

    • Filter APIs by Type, Activation status, or Team. Select the required API type, status, or team to view the APIs based on the provided filters.
      Note: The Team filter is applicable only if you have enabled the Teams feature.

    • Activate an API by clicking icon that denotes an inactive state.
      Once an API is activated, the Gateway endpoint is available which can be used by the consumers of this API.

    • Deactivate an API by clicking the status icon that denotes an active state.

    • Delete an API by clicking the Delete icon.

    • View API analytics by clicking the Analytics icon.

    • Publish or Unpublish an API by clicking Publish and the Unpublish icons respectively.

  2. Click any API to view API details.
    The API details page displays the basic information, technical information, resources and methods, and specification for the selected API. This page allows you to edit some of the API details. Also, this page provides options to activate/deactivate an API. Click icon to Export, Enable/Disable mocking, Update, and Create new version operations.

Note:The link provided in the Documentation section of the API details tab can be accessed using API gateway internal users credentials and cannot be accessed using SSO user credentials.

REST API Details

The 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 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 API details view for a REST API displays the details of the API such as Basic and Technical information, Resources and methods, API mocking details, and specifications. You can also view the scopes associated, policies enforced, registered applications and the API-specific analytics.

The table lists the API details displayed for the API:

Field Description
Basic information Displays the information about the API, such as Name, Version, Owner of the API, the teams that the API is assigned to, status of the API whether its is Active or Inactive, the maturity state of the API, the date on which the API was created and a brief description of the API.
Technical information Displays the native endpoints of the API.
Resources and methods Displays a list of resources or methods available in the API sorted by resource/pathname. The list of resources are displayed in sorted order of the path names. Click each resource to view the corresponding HTTP methods, along with a summary. Below each of these methods, details such as parameters and response codes are displayed.
API mocking Details are visible only when API mocking is enabled. Displays a list of mocked responses for the operations in the API, custom IS service list and conditions along with its mocked response.
Components Displays the schemas defined at the API level.
Documentation Displays the definition of the API in different formats.

Various tabs displayed in the API details page display the following details:

You can perform the following operations from the API details page:

SOAP API Details

The API details view for a SOAP API displays the details of the API such as Basic and Technical information, Operations available, REST transformation details, API mocking details, and specifications. You can also view the scopes associated, policies enforced, registered applications and the API-specific analytics.

The table lists the API details displayed for the API:

Field Description
Basic information Displays the information about the API, such as Name, Version, Owner of the API, the teams that the API is assigned to, status of the API whether its is Active or Inactive, the maturity state of the API, the date on which the API was created and a brief description of the API.
Technical information Displays the native endpoints of the API.
Operations Displays a list of operations available in the API and they are sorted alphabetically. Operations are displayed along with their type of binding (SOAP 11 , SOAP 12, and other HTTP methods). Click each method to view details such as input, output, and fault messages.
REST transformation Displays a list of operations exposed as REST resources and they are sorted alphabetically. Operations are displayed along with their type of binding. Click each method to view details such as input, output, and fault messages.
API mocking Details are visible only when API mocking is enabled. Displays a list of mocked responses for the operations in the API, custom IS service list and conditions along with its mocked response that contains the status code and mock payload details.
Documentation Displays the definition of the API in different formats.

Various tabs displayed in the API details page display the following details:

You can perform the following operations from the API details page:

OData API Details

Open Data Protocol (OData) enables the creation of REST-based APIs, which allow resources to be exposed as endpoints and identified using the Uniform Resource Identifiers (URIs). In general, OData is represented by an abstract data model called Entity Data Model (EDM). This Entity Data Model allows Web clients to publish and edit REST services and their resources using simple HTTP messages. OData leverages the principles of HTTP, REST and ATOM, and combines the simplicity of REST and SOAP metadata definitions to describe service interfaces, data models, and semantics.

API Gateway supports OData V4 and V2 services.

The API details view for a OData API displays the details of the API such as Basic and Technical information, OData entity sets, singletons, function imports, actions imports and specifications. You can also view the policies enforced, registered applications and the API-specific analytics.

The API Gateway UI exposes only OData navigation properties to visualize the resource path structure of OData APIs. Any other OData property is not displayed.

Note: API Gateway does not support the querying of Derived Entity Types. This includes the following operations:

  • Requesting a Derived Entity
  • Requesting a Derived Entity Collection
  • Filter on Derived Type

    • Operations on Derived Types are rejected by API Gateway.

The table lists the API details displayed for the API:

Field Description
Basic information Displays the information about the API, such as Name, Version, the teams that the API is assigned to, status of the API whether its is Active or Inactive, the date on which the API was created, and a brief description of the API.
Technical information Displays base URL of the API and the OData version supported.
OData entity sets Displays a list of OData entity sets. An entity set element represents a single entity or a collection of entities of a specific entity type in the data model.

The list of entity sets is sorted alphabetically. Click each entity set to view the resource path, entity type, resource parameter details, and the corresponding HTTP methods.

The entity types are structured records consisting of named and typed properties and key properties whose values uniquely identify one instance from another.
OData singletons Displays a list of OData singletons. Singletons are single entities which are accessed as children of the entity container.

The list of singletons is sorted alphabetically. Click each singleton to view the resource path, entity type, the corresponding HTTP methods, and the navigation properties that allow navigation from an entity to related entities.

The OData navigation property has an impact on the resource structure. This property is represented as an OData Resource and denoted as OData Navigation properties inside the OData Resources profile. There is no restriction to the number of levels you can drill down
OData function imports Displays a list of OData function imports. The Function Import element represents a Function in an entity model.

The list of OData function imports is sorted alphabetically. Click each function import to view the resource path, entity type, and the corresponding HTTP methods.
OData action imports Displays a list of OData action imports. The Action Import element represents an Action in an entity model.

The list of OData action imports is sorted alphabetically. Click each action import to view the resource path, entity type, and the corresponding HTTP methods.
Documentation Displays the definition of the API in different formats.
The metadata document. The metadata document describes the Entity Data Model that is, the structure and organization of the OData service resources exposed as HTTP endpoints by that particular service. This document describes the entity types, entity sets, functions and actions.

Various tabs displayed in the API details page display the following details:

You can perform the following operations from the API details page:

GraphQL API Details

API Gateway supports proxying an existing GraphQL endpoint and provides API management capabilities to clients like authentication, analytics, and so on. The GraphQL APIs can be accessed using the HTTP GET and POST methods. You can create and deploy a GraphQL API using the API Gateway UI or REST endpoints.

The following table lists the features that API Gateway supports for GraphQL.

GraphQL Features Supported
Basic GraphQL concepts:
  • Schema
  • Operations
  • Types
 Yes
Root operations for resources:
  • Query
  • Mutation
 Yes
Root operations for resources: Subscription No
Input and output data types:
  • Scalar type
  • Object type
  • Interface type
  • Union type
  • Enum type
 Yes

The following table lists the API Gateway-specific features that are not supported for GraphQL API.

API Gateway Features for GraphQL Supported
API tagging No
API mocking No
Policy scopes No
Packages and plan No
Adding or updating GraphQL schema types No
Publishing GraphQL API to API Portal No

The API details view for a GraphQL API displays the details of the API such as basic and technical information, operations available, and specifications. You can also view the policies enforced, registered applications, and the API-specific analytics.

The table lists the API details displayed for the API:

Field Description
Basic information Displays the information about the API, such as Name, Version, Owner of the API, the teams that the API is assigned to, Active or Inactive status of the API , the maturity state of the API, the date on which the API was created, and a brief description of the API.
Technical information Displays the following endpoints of the API:
  • Native endpoint(s).
  • Gateway endpoint(s). Displays these endpoints when the API is deployed to a gateway.
  • Service Registry display name. Displays the name of the service registry where the API is deployed.
Operations Displays a list of operations available in the API sorted alphabetically.
Operations are displayed along with their type (Query and Mutation).
Documentation Displays a list of specifications for the API.

Various tabs displayed in the API details page display the following details:

You can perform the following operations from the API details page:

Filtering APIs

You can filter APIs based on the API type or the activation status of the API.

To filter APIs

  1. Click APIs in the title navigation bar.
    A list of all registered APIs appears.

  2. In the Add Filter pane, select REST, SOAP, OData, GraphQL or all to filter APIs by type.

  3. In the Add Filter pane, select Active and/or Inactive to filter APIs by their activation status.

  4. Click Apply filter.
    The filtered list of APIs is displayed. You can click Reset to reset the values to the original values.

Activating an API

You can activate an API in the Manage APIs page. Alternatively you can also activate the API from the API Details page.

You must have the Activate/Deactivate APIs functional privilege assigned to perform this task.

To activate an API

  1. Click APIs in the title navigation bar.
    A list of available APIs appears.

  2. Do one of the following:

    • Click the toggle button, in the corresponding column of the API to be activated, to change the status to icon to activate the API.
    • Select the API to open the API details page. Click Activate.

  3. Click Yes in the confirmation dialog box.

    The API is now activated. The Gateway endpoint is now available, which can be used by the consumers of this API. You can now publish the API to the required destination and expose the API for consumption by the consumers.

    You can modify API details or update the API, except the name and version of the API, when the API is in the active state. Active APIs are replaced during deployment with zero downtime and do not break ongoing requests. The updated APIs do not become effective for ongoing requests.

    Note:

    • If there is an error while saving after updating an active API, the API becomes inactive but the changes are saved.
    • Once the API is activated, you can define the custom gateway endpoints. For more information about gateway endpoints, see Gateway Endpoints.
    • Once the API is activated, you can enable the tracer. For more information about how to enable the tracer and view the tracing details, see Trace API.

Deactivating an API

You can deactivate an API in the Manage APIs page. Alternatively you can also deactivate the API from the API Details page.

You must have the Activate/Deactivate APIs functional privilege assigned to perform this task.

To deactivate an API

  1. Click APIs in the title navigation bar.
    A list of available APIs appears.

  2. Click the toggle button, in the corresponding column of the API to be deactivated, to change the status to icon to deactivate the API.

  3. Click Yes in the confirmation dialog box.
    The API is now deactivated. The API is no more available to be consumed by consumers.

Publishing APIs

You can publish an API to two types of destinations: API Portal and Service Registries.

Publishing APIs to API Portal

Publishing an API to API Portal sends the SOAP and REST APIs to API Portal on which they are exposed for testing and user consumption.

Note: API Gateway does not support publishing GraphQL API to API Portal.

The process of publishing an API to API Portal is initiated from API Gateway and is carried out on the API Portal server.

Doing this involves the following high-level steps:

When publishing an API to the API Portal destination, keep the following points in mind:

Publishing a Single API to API Portal

Pre-requisites:

You must have the Publish to API Portal functional privilege assigned to perform this task.

To publish an API to API Portal

  1. Click APIs in the title navigation bar.
    A list of all APIs appears.

  2. Click the Publish icon for the API that you want to publish.

  3. Select the API endpoints that need to be visible to the consumers.
    At least one endpoint should be selected before publishing the API.

  4. Select the API type if you want to publish a REST-enabled SOAP API.
    When the REST transformation is enabled for a SOAP API in API Gateway, you can publish the REST-enabled SOAP API to API Portal in one of the following ways:

    • Publish as REST: Default. The API is published as a REST API to API Portal. The REST resources and methods which correspond to the transformed SOAP operations are also published to API Portal.

    • Publish as SOAP: The API is published as a SOAP API with the SOAP operations to API Portal.

    • Publish as REST and SOAP: When both the options are selected, the API is published as a REST API as well as a SOAP API in API Portal and marked as a HYBRID API.

    Note: The Publish as option is available only if the REST transformation is enabled for the SOAP API.

  5. Select the communities to which the API needs to be published.
    By default, an API is published to the Public Community of API Portal.

    Note: If an API is already a part of the package published to a community then you cannot remove it from that community.

  6. Click Publish.
    The API along with the selected endpoints is published to API Portal and available for the consumers to consume it.

    A REST-enabled SOAP API is published to API Portal based on the selected API type:

    • REST API. The API Details view displays the published API as a REST API with the defined REST resources and methods.

    • SOAP API. The API Details view displays the published API as a SOAP API with the defined SOAP operations.

    • HYBRID API. The API Details view, by default, displays the published API as a REST API with the REST resources and methods. There is an option SOAP that can be selected to display the published API as a SOAP API with the SOAP operations.

    Once an API is published, the Publish icon changes to Republish icon.

    You can unpublish an API once it is published by clicking the Unpublish icon.

Publishing Multiple APIs to API Portal in a Single Operation

Pre-requisites:

You must have the Publish to API Portal functional privilege assigned to perform this task.

You can bulk publish APIs to API Portal.

To publish multiple APIs to API Portal in a single operation

  1. Click APIs in the title navigation bar.
    A list of all APIs appears.

  2. Select the APIs that you want to publish.
    By default, all the respective API endpoints are internally selected to be visible to the consumers.

  3. In the Menu icon icon, click Publish.

  4. Select the communities to which the APIs have to be published.
    By default, the APIs are published to the Public Community of API Portal.

  5. Click Publish.
    The APIs along with their associated endpoints are published to API Portal and available for the consumers to consume.
    If you have selected several APIs where one or more of them are REST-enabled SOAP APIs in API Gateway, then these SOAP APIs are published as REST APIs along with their specific REST endpoints in API Portal.

  6. Examine the Publish APIs report window and check for any errors that occurred during the publishing process.
    The Publish APIs report window displays the following information:

    Parameter Description
    Name The name of the published API.
    Version The version of the published API.
    Status The status of the publishing process.

    The available values are:

    • Success

    • Failure
    Description A descriptive information if the API publishing process fails or if a warning occurs.

    API Gateway writes these results to the Audit logs dashboard, so you can view them later.

  7. Click Download the detailed report here to download the detailed report as an HTML file.

Publishing APIs to Service Registries

Publishing an API to a service registry enables applications to dynamically locate an API Gateway instance that can process that API.

When publishing an API to a service registry, keep the following points in mind:

Publishing a Single API to Service Registries

Pre-requisites:

You must have the Publish API to service registry functional privilege assigned to perform this task.

To publish an API to service registries

  1. Click APIs in the title navigation bar.
    The list of APIs defined in API Gateway appears.

  2. Click the Publish icon for the API that you want to publish.

  3. Select Service Registries.
    The list of service registries that have been added to API Gateway is displayed.

  4. Select the service registry to which you want to publish the API.
    The list of endpoints in the selected API are displayed.

  5. Select the endpoints that you want to publish to the selected service registry.

  6. Repeat the previous two steps to publish the API to additional service registries.

  7. Click Publish.
    Once an API is published, the Publish icon changes to Republish icon.

You can unpublish a published API by clicking the Unpublish icon.

Publishing Multiple APIs to Service Registries in a Single Operation

Pre-requisites:

You must have the Publish API to service registry functional privilege assigned to perform this task.

Note: When you publish multiple APIs to one or more service registries in a single operation, all endpoints in the APIs are published. To selectively publish endpoints within an API, you must publish the API separately as a single API.

To publish multiple APIs to service registries in a single operation

  1. Click APIs in the title navigation bar.
    The list of APIs defined in API Gateway appears.

  2. Select the APIs that you want to publish.

  3. On the icon menu, click Publish.

  4. Select Service Registries.
    The list of service registries that have been added to API Gateway is displayed.

  5. Select the service registry to which you want to publish the API and click Publish.
    Once an API is published, the Publish icon changes to Republish icon.

You can unpublish a published API by clicking the Unpublish icon.

Unpublishing APIs

You can manually unpublish APIs that you had previously published to an API Portal or to one or more service registries.

Unpublishing APIs from API Portal

After you publish an API to API Portal, the API remains published and available on API Portal for consumption until you manually unpublish the API.

You can unpublish a SOAP or REST API from API Portal to suspend its interaction, testing, and user consumption in API Portal.

Unpublishing a Single API from API Portal

Pre-requisites:

You must have the Publish to API Portal functional privilege assigned to perform this task.

To unpublish an API from API Portal

  1. Click APIs in the title navigation bar.
    A list of all APIs appears.

  2. Click the Unpublish icon for the API that you want to unpublish.
    The Unpublish API dialog box is displayed.

  3. Select API Portal in Destination.

  4. Click Unpublish.
    Select Force unpublish to force the unpublish operation without a confirmation dialog popping up.

  5. Click Yes in the confirmation dialog.
    The API is unpublished from the API Portal destination. The API is no longer available on API Portal for testing and user consumption.

Once an API is unpublished, the Republish icon changes to Publish icon.

You can publish an API once it is unpublished by clicking the Publish icon.

Unpublishing Multiple APIs from API Portal in a Single Operation

Pre-requisites:

You must have the Publish to API Portal functional privilege assigned to perform this task.

You can bulk unpublish APIs from API Portal.

To unpublish multiple APIs from API Portal in a single operation

  1. Click APIs in the title navigation bar.
    A list of all APIs appears.

  2. Select the APIs that you want to unpublish.

  3. In the Menu icon icon, click Unpublish.

  4. Click Unpublish.
    Select Force unpublish to force the unpublish operation without a confirmation dialog popping up.

  5. Click Yes in the confirmation dialog.
    The selected APIs are unpublished from API Portal.

  6. Examine the Unpublish APIs report window and check for any errors that occurred during the unpublishing process.
    The Unpublish APIs report window displays the following information:

    Parameter Description
    Name The name of the unpublished API.
    Status The status of the unpublishing process. The available values are:

    • Success

    • Failure
    Description A descriptive information if the API unpublishing process fails or if a warning occurs.

    API Gateway writes these results to the Audit logs dashboard, so you can view them later.

  7. Click Download the detailed report here to download the detailed report as an HTML file.

Unpublishing APIs from a Service Registry

You can manually unpublish APIs that you had previously published on service registries.

You must consider the following points before unpublishing an API from a service registry:

APIs may also get unpublished automatically from service registries, as described below.

Automatic Unpublishing of APIs

API Gateway automatically, but temporarily unpublishes an API in the following situations:

Unpublishing a Single API from Service Registries

Pre-requisites:

You must have the Publish API to service registry functional privilege assigned to perform this task.

To unpublish an API from Service Registries

  1. Click APIs in the title navigation bar.
    A list of all APIs appears.

  2. Click the Unpublish icon for the API that you want to unpublish.
    The Unpublish API dialog box is displayed.

  3. Select Service registries in Destination.
    The list of service registries to which the API was published is displayed.

  4. Select the service registries from which you want to unpublish the API.

  5. Select Force unpublish to mark the API as unpublished in API Gateway even if the unpublish fails on the selected service registries.
    The API is unpublished from the selected service registries. The API is no longer available on selected service registries for testing and user consumption.

Once an API is unpublished, the Republish icon changes to Publish icon.

Unpublishing Multiple APIs from Service Registries in a Single Operation

Pre-requisites:

You must have the Publish API to service registry functional privilege assigned to perform this task.

You can bulk unpublish APIs from one or more service registries.

To unpublish multiple APIs from service registries in a single operation

  1. Click APIs in the title navigation bar.
    A list of all APIs appears.

  2. Select the APIs that you want to unpublish.

  3. In the Menu icon icon, click Unpublish.

  4. Select Service registries in Destination.
    The list of service registries to which the APIs were published is displayed.

  5. Select the service registries from which you want to unpublish the selected APIs.

  6. Select Force unpublish to mark the APIs as unpublished in API Gateway even if the unpublish fails on the destination service registries.

  7. Examine the Unpublish APIs report window and check for any errors that occurred during the unpublishing process.
    The Unpublish APIs report window displays the following information:

    Parameter Description
    Name The name of the unpublished API.
    Status The status of the unpublishing process. The available values are:

    • Success

    • Failure
    Description A descriptive information if the API unpublishing process fails or if a warning occurs.

    API Gateway writes these results to the Audit logs dashboard, so you can view them later.

  8. Click Download the detailed report here to download the detailed report as an HTML file.

The APIs are unpublished from the selected service registries for the current API Gateway instance. Once an API is unpublished, the Republish icon changes to Publish icon.

Modifying API Details

You must have the API Gateway’s manage APIs or activate/deactivate APIs functional privilege assigned to perform this task.

You can modify API details, as required, from the API details page.

To modify API details

  1. Click APIs in the title navigation bar.
    A list of all registered APIs appears.

  2. Click the required API.
    The API details page appears.

  3. Click Edit.

    Note: If the API is in the active state, you cannot modify the name and version of the API. The API mocking section is unavailable for any changes.

  4. Modify the information as required.

  5. Click Save.
    If the API is in the active state when you modify API details, the active API is replaced with the modified API.
    The modified APIs do not become effective for ongoing requests.

Updating APIs

You can update the definition of an existing API by uploading WSDL, Swagger, or RAML file or URL. The uploaded file can also be in a ZIP format. When an API is updated, it retains the Expose to consumers settings, the existing scope definitions, the configured policies, and the REST-enabled path configurations for SOAP API. You can also edit an API using the Edit option for minor edits, whereas the update feature helps you to overwrite the complete API definition using a file or a URL at the same time.

You can update an active API. You cannot modify the name and version of an API while updating an active API.

Note: The active APIs are replaced with the updated API. The updated APIs do not become effective for ongoing requests. Updates to an activated API are propagated across a cluster and trigger a hot deploy on each cluster node separately.

You can update an existing API in the following ways:

Updating an API by Importing an API from a File

You must have the API Gateway’s manage APIs or Activate/deactivate APIs functional privilege assigned to perform this task. You can not update an API by importing an API from a file if the API is in the active state.

To modify API details

  1. Click APIs in the title navigation bar.

  2. Select the required API from the list of APIs. The API details page for the selected API appears.

  3. Click icon and select Update. The Update API window appears.

  4. Select Update API by importing from file.

  5. Provide the following information:

    Field Description
    Select file Click Browse to browse to the location of file to be imported and select the required file or ZIP format file. The REST API can be updated using only the Swagger or RAML file type. The SOAP API can be updated using only the WSDL file type.
    Root File Name If you have selected a file in ZIP format, type the relative path of the main file within the ZIP file.
    Name Name for the API. Edit or delete the name of the existing API displayed.

    • If you provide an API name, this overwrites the API name mentioned in the uploaded file and the API is updated with the name provided.

    • If you do not provide an API name, the API name mentioned in the uploaded file is picked up and the API is updated with that name.
    Type Select the required type. The available types are RAML, Swagger, WSDL, and GraphQL SDL.

    • For a REST API, the available options are RAML and Swagger.

    • For a SOAP API, the available option is WSDL.

    • For a GraphQL API, the available option is GraphQL SDL.
    Version Version number of the API. The existing version number of the API is automatically displayed. You can edit or delete the version number. If the version number is deleted and the imported file does not have a version number, then the system automatically assigns a version number during the update.

    This overwrites the version of the API.
    Description Description of the API. The existing description of the API is automatically displayed. You can edit or delete the description. If you delete the description then the description from the imported file is used.

  6. Click Update.
    The API definition is updated with the latest changes from the file and is displayed in the API details page.

Updating an API by Importing an API from a URL

You must have the API Gateway’s manage APIs or activate/deactivate APIs functional privilege assigned to perform this task.

To modify API details

  1. Click APIs in the title navigation bar.

  2. Select the required API from the list of APIs. The API details page for the selected API appears.

  3. Click icon and select Update. The Update API window appears.

  4. Select Update API by importing from URL.

  5. Provide the following information:

    Field Description
    URL Type the URL from which the API is being imported.

    Note: The REST API can be updated using only the Swagger or RAML type information that the URL is pointing to. The SOAP API can be updated using only the WSDL file type information that the URL is pointing to. The entity sets, singletons, function imports, and action imports of an OData API can only be updated by a re-import of the OData API definition through the URL.
    Protected Select this option if you want to import an API from a URL that is password protected. The user name and password fields are displayed using which you can access the provided URL.
    Username Type the user name required to access the password protected URL. If you have selected the Protected option, this field is displayed.
    Password Type the password associated with the username. If you have selected the Protected option, this field is displayed.
    Name Name for the API. The existing name of the API is automatically displayed.

    • If you provide an API name, this overwrites the API name mentioned in the file referred by URL and the API is updated with the name provided.

    • If you do not provide an API name, the API name mentioned in the file referred to by URL is picked up and the API is updated with that name.
    Type Select the required type. The available types are RAML, Swagger, WSDL, OData, and Graph QL SDL.

    • For a REST API, the available options are RAML and Swagger.

    • For a SOAP API, the available option is WSDL.

    • For a OData API, the available option is OData.

    • For a GraphQL API, the available option is GraphQL SDL.
    Version Version number of the API. The existing version number of the API is automatically displayed. You can edit or delete the version number. If the version number is deleted and the file referred to by URL does not have a version number, then the system automatically assigns a version number during the update.

    This overwrites the version of the API.
    Description Description of the API. The existing description of the API is automatically displayed. You can edit or delete the description. If you delete the description then the description from the file referred to by URL is used.

  6. Click Update.
    The API definition is updated with the latest changes from the URL and is displayed in the API details page.

API Mocking

Using API Gateway, you can mock an API by simulating the native API. For example, if you have an API without a native implementation, you can mock that API. The mocked response is returned to the consumer when the API is invoked.

In API Gateway, when you enable mocking for an API, a default mock response is configured for each combination of resource, operation, status code, and content-type based on the example and schema specified in that API. You can add a condition to the operation in the resource.

Note: You cannot enable or disable mocking for an active API.

As an API Provider, you can create or modify the default mock response. You can specify conditions and associate an IS service with the mocked API. When an IS service is associated with a mocked API, the associated IS service must adhere to the apigateway.specifications:mockService specification.

At runtime, when the mocked API is invoked, instead of calling the native API, API Gateway returns the mocked response to the consumer based on the following priorities:

  1. If any of the conditions for the invoked operation satisfies, API Gateway returns the associated mocked response.

  2. If any of the conditions for the invoked operation is not satisfied, and if an IS service is configured for the API, then API Gateway invokes the IS service and returns the IS service response.

  3. If any of the conditions for the invoked operation is not satisfied, and if an IS service is not configured for the API, then API Gateway returns the default mocked response.

API mocking is supported only for SOAP and REST APIs.

Note: You must have the API Gateway’s manage APIs or activate/deactivate APIs functional privilege assigned to perform API mocking.

Enabling API Mocking

You can enable or disable API mocking through the API details page.

Note: You cannot enable or disable API mocking for active APIs.

To enable API mocking

  1. Click APIs in the title navigation bar.

  2. Select the required API from the list of available APIs.
    The API details page for the selected API appears.

  3. Click icon and select Enable mocking.
    This generates the default mock responses.

Modifying API Mocking Details

You must select Enable mocking from the API details page.

You can modify API mocking details, as required, from the API details page.

To modify API mocking details

  1. Click APIs in the title navigation bar.
    A list of all registered APIs appears.

  2. Click the required API. The API details page appears.

  3. Click Edit.

  4. Click API mocking.

  5. Specify the following information in the IS service section:

    Field Description
    Invoke service Specifies the webMethods Integration Server service to be invoked.
    Run as user Type the user name you want API Gateway to use to invoke the IS service.

  6. Select the operation that you want to modify from the Mocked responses section.

  7. Click Add Response if you want to add a response and select the status code from the drop-down.

  8. Click icon.
    This adds the status code created to the existing status code list.

  9. Select the status code you want to modify.

  10. Click + Add Response Header and provide the following information to add the required response headers:

    Field Description
    Header key Specify the HTTP header key that would be contained in the header of HTTP response.
    Header value Specify the HTTP header value that would be contained in the header of HTTP response.

    You can add more response headers by clicking icon.

  11. Click + Add Content-type to add a content-type to the status code selected and provide the following information:

    Field Description
    Content type Select the content-type to be added to the selected status code from the drop-down list.
    Mock payloads Specify a mock response payload for the content-type selected.

    You can add more content-types by clicking Add.

  12. Click + Add Conditions to add a condition to the operation in the resource:

    Field Description
    Condition name Specify the name for the condition.
    Condition parameter Select the type to which the condition is to be applied. The available options are:

    • Body

    • Header

    • Query parameter (Applicable only for REST APIs)
    Key The key can be a string for the header and query parameter and for body it can be a JSON path or an XML path.
    Value The value of the condition. Additionally, you can type an * (asterisk) to ignore the value specified in this parameter and the condition is satisfied based on the value specified in the Key parameter.
    Status code Select the status code from the drop-down list.

    Note:

    • You must enable the property Send native provider fault in the Administration > General > API fault section in order to have correct mock response for status code 506.

    • While invoking an API remember to use the query parameter expectedStatusCode in order to have correct mock responses for status codes 100 and 202.
    + Add Response Header Add a response header to the resource selected by providing the following information:

    • Header key. Specify the HTTP header key that would be contained in the header of HTTP response

    • Header value. Specify the HTTP header value that would be contained in the header of HTTP response.
    + Add Content-type Add a content-type to the status code selected by providing the following information:

    • Content type. Select the content-type to be added to the selected status code from the drop-down list.

    • Mock payload. Specify a mock response payload for the content-type selected.

    You can add more conditions by clicking Add.

  13. Click Save.

Custom Replacer

API Gateway allows you to send a dynamic custom response instead of a static mocked response to the consumer when the mocked API is invoked. In the mocked response, you can specify multiple custom replacers. Custom replacer is used to replace the custom variables with the values defined in the request headers, query parameters, and request body. The custom replacer is available in the ${request.<ConditionParameter>.<Key|JsonPath|XPath>} format. The custom replacers are:

Attaching Documents to an API

Pre-requisites:

You must have the Manage APIs functional privilege assigned to perform this task.

You can associate an input document that includes the RAML, Swagger, or WSDL specification, and additional documents such as programming guides, sample code, script files, and project plan with an API. For example, SOAP APIs can contain external documents such as Functional Requirements, Error Messages, Release Notes, and so on.

When attaching a document to an API, keep the following points in mind:

To attach document

  1. Click APIs in the title navigation bar.
    A list of all registered APIs appears.

  2. Select the required API.
    The API details page appears.

  3. Click Edit.

  4. Click Documentation.

  5. Click Browse to select a file and upload it.

  6. Rename the document in the Display Name field as required.
    This is the display name of the document in the API details page.

  7. Click Add.
    The attached document is listed in a table. You can edit and delete the document by clicking the icon and icon icons.

  8. Repeat steps 5 to 7 for each document that you want to attach to the API.

  9. Click Save.

SOAP to REST Transformation

OAP APIs are commonly used to expose data within enterprises. With the rapid adoption of the REST APIs, API providers must be able to provide RESTful interfaces to their existing SOAP APIs instead of creating new REST APIs. Using the API Gateway SOAP to REST transformation feature, the API provider can either expose the parts of the SOAP API or expose the complete SOAP API with RESTful interface. API Gateway allows you to customize the way the SOAP operations are exposed as REST resources. Additionally, the Swagger or RAML definitions can be generated for these REST interfaces.

Note: You must have the API Gateway’s manage APIs or activate/deactivate APIs functional privilege assigned to perform this task.

Activating SOAP to Rest Transformation

You must have the API Gateway’s manage APIs functional privilege assigned to perform this task.

To activate SOAP to REST transformation for a SOAP operation

  1. Click APIs in the title navigation bar.

  2. Select the required API from the list of available APIs.

    The API details page for the selected API appears.

  3. Click Edit.

  4. Click REST transformation.

    A list of SOAP operations already exposed to the consumers as well as to be transformed from SOAP to REST appears. By default, all the SOAP operations are in inactive state.

  5. Click icon to activate the SOAP to REST transformation for the SOAP operations.
    Alternatively, you can activate the SOAP to REST transformation for multiple SOAP operations simultaneously by clicking the Transform all operations activation toggle button.

  6. Select the operation to edit the SOAP operations.

  7. In the Transformation Configuration section, configure the following settings:

    • Use Schema for XML to JSON transformation If you select this checkbox, the XML schema (present in the WSDL) defines the data type of the entity. The data type can either be String, Int, Double, Float, or Boolean. In the response from the native server, if an entity is of a different data type other than the ones defined in the XML schema, API Gateway returns it is as a String data type and not an error.
      If you do not select this checkbox, API Gateway does not honor the XML schema during transformation. Instead, API Gateway derives the data type of entities based on the native service response.
      By default, this checkbox is not selected for any SOAP API. If you have migrated your APIs from another instance of API Gateway , the value of this checkbox will depend on the value of the Extended property pg.soapToRest.typeConvertorEnabled in the source API Gateway of the migrated APIs. The pg.soapToRest.typeConvertorEnabled property specifies whether the key values in a SOAP request must be converted to their primitive type when a SOAP API is transformed to REST API.
      Note: Date and Enumeration data types are also considered to be strings. When API Gateway cannot determine the data type of any value, it considers the data type to be a string.

    • Use default values from schema If you select this checkbox, API Gateway considers the default values provided in the XML schema, if there are no values present in a request or response. If the request or response has some value, this value overrides the default value from XML schema.
      If you do not select this checkbox, API Gateway does not consider the default values present in the XML schema even if there are no values present in the request or response.

    • Remove operation name in response
      If you select this checkbox, the root node is not passed as a part of SOAP to REST response and only the JSON is passed. Root node is generally the SOAP operation name or SOAP operation response name, present in the XML schema. This check box is applicable only to JSON responses.
      If you do not select this checkbox, JSON response is accompanied by the root node. By default, this check box is not selected for any SOAP API.

  8. Click Save.

    The API details page for the selected API appears.

  9. Click REST transformation.

    A list of REST resources for the SOAP operations appears. Click on each resource to view the details that are already available as REST definitions.

Modifying the REST Definitions for SOAP Operations

You must have the API Gateway’s manage APIs functional privilege assigned to perform this task.

To modify the REST definitions for SOAP operation

  1. Click APIs in the title navigation bar.

  2. Select the required API from the list of available APIs.
    The API details page for the selected API appears.

  3. Click Edit.

  4. Click REST transformation.
    A list of SOAP operations already exposed to the consumers as well as to be transformed from SOAP to REST appears.

  5. Click icon to provide the Resource name and Resource path.
    Alternatively, you can activate the SOAP to REST transformation for multiple SOAP operations simultaneously by clicking the Transform all operations activation toggle button.

  6. Select the operation to edit the SOAP operations.

  7. Provide the following information:

    Field Description
    Resource name Name of the resource. The existing name of the SOAP operation automatically appears, you can modify this name.
    Resource path Path of the resource. The existing path of the SOAP operation automatically appears, you can modify this path.

  8. Click + Add Parameter and provide the following information to add the required resource level parameters:

    Field Description
    Name Name of the parameter.
    Description Description of the parameter.
    Type Specifies the parameter type. Available values - Path, Query-string.
    Data type Specifies the data type. Available values - String, Date, Date time, Integer, Double, Boolean.
    Required Specifies the parameter is required if selected.
    Repeat Applicable to parameters of type query. The query parameter value can take comma separated array values.
    Value Specifies the possible value.
    XPath XPath. Specifies how the request parameter must be mapped to the SOAP payload that is sent to the native SOAP service. For example,
    /soapenv:Envelope/soapenv:Body/axis:sayHello/axis:name, or //axis:name (If the SOAP request has only one element such as name).
    Namespace prefix Specifies the namespace prefix of the element that appears in the XPath.
    Namespace URI Specifies the namespace URI for the XPath element. You can add more namespace prefixes and namespace URIs by clicking .

    You can add more parameters by clicking icon.

  9. Select one of the available methods: GET, POST, PUT, or DELETE.
    By default, POST is selected. By default, API Gateway generates the sample JSON request and response based on the XML schema definitions of the SOAP API. Additionally, you can provide a schema and modify the generated sample.

  10. Click Add Request and provide the schema and a sample for the content-type.

  11. Click Add Response and select the status code from the drop-down and provide a description for the status code selected.
    Additionally, to add a content-type to the status code selected, click the status code to which you want to add a content-type and select the Content type. Provide a schema and a sample for the content-type selected. By default, status code 200 is automatically generated by the system.

  12. Click REST transformation.
    A list of SOAP operations already exposed to the consumers as well as to be transformed from SOAP to REST appears. By default, all the SOAP operations are in inactive state.

  13. Click icon to activate the SOAP to REST transformation for the SOAP operations.
    Alternatively, you can activate the SOAP to REST transformation for multiple SOAP operations simultaneously by clicking the Transform all operations activation toggle button.

  14. Select the operation to edit the SOAP operations.

  15. Click Save.
    The API details page for the selected API appears.

  16. Click REST transformation.
    A list of REST resources for the SOAP operations appears. Click on each resource to view the details that are already available as REST definitions.

  17. Click Save.

Supported Content-types and Accept Headers

The following table specifies the content-type available for the HTTP methods:

HTTP Method Content-types Accept Headers
GET application/x-www-form-urlencoded application/json
application/xml or text/xm
multipart/form-data or multipart/mixed
POST application/json
application/xml or text/xm
multipart/form-data or multipart/mixed
application/x-www-form-urlencoded		 application/json
application/xml or text/xm
multipart/form-data or multipart/mixed
PUT application/json
application/xml or text/xm
multipart/form-data or multipart/mixed
application/x-www-form-urlencoded		 application/json
application/xml or text/xm
multipart/form-data or multipart/mixed
DELETE application/x-www-form-urlencoded application/json
application/xml or text/xm
multipart/form-data or multipart/mixed

Note: If a content-type is not specified, then the request verifies the value of the Set Media Type parameter. If the value of the Set Media Type parameter is not defined, then by default, for POST and PUT HTTP methods, the application/json content-type is used. Whereas for GET and DELETE HTTP methods, the application/x-www-form-urlencoded content-type is used.

REST API Endpoints

After providing the information required for the SOAP to REST transformation and activating the API, the API can be invoked as either SOAP or REST API.

The REST transformation of the SOAP API does not change the API name. The only change to the SOAP invocation is that the <resource-path-for-the-operation> is appended:

/ws/<API-NAME>/<version-number>/<resource-path-for-the-resource>

Note: The REST-enabled SOAP API cannot be invoked using the /rest directive.

Samples for REST Request

application/json

The following table provides the samples of the REST request for the application/json content-type application and the equivalent SOAP request after transformation from REST to SOAP:

  Request Equivalent SOAP Request
Consists of only one element (qualified namespaces) 
{
 "name":"user1"
}
 
<soapenv:Envelope xmlns:soapenv=
"http://schemas.xmlsoap.org/soap/envelope/"
 xmlns:axis="http://ws.apache.org/axis2">
 <soapenv:Body>
 <axis:sayHello>
 <axis:name>user1/axis:name>
 </axis:sayHello>
 </soapenv:Body>
</soapenv:Envelope>
Consists of only one element (non-qualified namespaces) 
{
 "name":"user1"
}
 
<soapenv:Envelope xmlns:soapenv=
"http://schemas.xmlsoap.org/soap/envelope/"
 xmlns:axis="http://ws.apache.org/axis2">
 <soapenv:Body>
 <axis:sayHello>
 <name>user1</name>
 </axis:sayHello>
 </soapenv:Body>
</soapenv:Envelope>
Consists of multiple elements 
{
 "a":"1",
 "b" : 2
}
 
<soapenv:Envelope xmlns:soapenv=
"http://schemas.xmlsoap.org/soap/envelope/">
 <soapenv:Body>
 <addInts>
 <a>1</a><b>2</b>
 </addInts>
 </soapenv:Body>
</soapenv:Envelope>

application/xml and text/xml

The following table provides the samples of the REST request for the application/xml and text/xml content-type application and the equivalent SOAP request after transformation from REST to SOAP:

  Request Equivalent SOAP Request
Consists of only one element and namespace added by the client 
<axis:name xmlns:
axis=
"http://ws.apache.org/axis2"
>user1</axis:name>
 
<soapenv:Envelope xmlns:soapenv=
"http://schemas.xmlsoap.org/soap/envelope/"
 xmlns:axis="http://ws.apache.org/axis2">
 <soapenv:Body>
 <axis:sayHello>
 <axis:name>user1</axis:name>
 </axis:sayHello>
 </soapenv:Body>
</soapenv:Envelope>
Consists of only one element and client does not send the Namespace 
<someOtherNamespace
:name xmlns:toMed=
"http:
//someOtherNamespace"
>user1
</someOtherNamespace
:name>
 
<soapenv:Envelope xmlns:soapenv=
"http://schemas.xmlsoap.org/soap/envelope/"
 xmlns:axis="http://ws.apache.org/axis2">
 <soapenv:Body>
 <axis:sayHello>
 <axis:name>user1</axis:name>
 </axis:sayHello>
 </soapenv:Body>
</soapenv:Envelope>
Consists of only one element and the client sends a different namespace to API Gateway 
<toMed:name xmlns:
toMed="http://tOMed"
>user1</toMed:name>
 
<soapenv:Envelope xmlns:soapenv=
"http://schemas.xmlsoap.org/soap/envelope/"
 xmlns:axis="http://ws.apache.org/axis2">
 <soapenv:Body>
 <axis:sayHello>
 <axis:name>user1</axis:name>
 </axis:sayHello>
 </soapenv:Body>
</soapenv:Envelope>
Multiple XML elements 
<addInts>
<a>2</a>
<b>3</b>
</addInts>

<soapenv:Envelope xmlns:soapenv=
"http://schemas.xmlsoap.org/soap/envelope/">
 <soapenv:Body>
 <addInts>
<a>2</a><b>3</b>
</addInts>
 </soapenv:Body>
</soapenv:Envelope>

Path and Query Parameters

The following table provides the samples of the REST request having path and query parameters and the equivalent SOAP request after transformation from REST to SOAP:

<
  Request Equivalent SOAP Request
Simple query or path parameter 
/ws/CalcService/
add/{num1}

or

/ws/CalcService/
add?num1=10
 
<ws:addInts
xmlns:ws="http:test">
<num1>10</num1></ws:addInts>s
Multiple query or path parameters 
/ws/CalcService/
add/{num1}/{num2}

or

/ws/CalcService/
add?num1=10&num2=3

or

/ws/CalcService/
add/{num1}&num2=3
 
<ws:addInts
xmlns:ws="http:test">
<num1></num1><num2></num2>
</ws:addInts>
Hierarchical elements 
/ws/CalcService/add/{num1}/anotherNumber/{num2}

/ws/CalcService/
add/{num1}/
anotherNumber/{num2}


<ws:addInts
xmlns:ws="http:test">
<num1></num1> <num2></
num2></ws:addInts>

multipart/form-data

If you send the multipart/form-data content-type as the REST request, then you need to optimize the method to be used. This optimization is based on the value specified in the SOAP Optimization Method parameter available in Routing policy. The default optimization type is Message Transmission Optimization Mechanism (MTOM). For example, API Gateway converts REST requests with multipart/form-data and multipart/mixed types as follows:

  1. The Multipurpose Internet Mail Extensions (MIME) parts that have a content ID or name that match the elements of type base64Binary or hexBinary in the schema are added as attachments to the outbound request.

  2. Parts other than the content ID or name types are converted into XML depending on the content-type of the MIME part. The application/xml and application/json content-types are converted. If API Gateway is unable to process the MIME part, it wraps the MIME part inside an XML element with the name of the content ID.

Limitations

The following limitations apply when you perform a SOAP to REST transformation:

CentraSite Provided APIs

When you want to perform governed API development with CentraSite and API Gateway, you can create an API in CentraSite defining the design-time aspects. The API can be deployed to the API Gateway. In such cases, you can also see that particular CentraSite destination is being configured in API Gateway. The API details for the CentraSite provided APIs are set as read-only. However, you can edit the run-time aspects such as scope and policies.

Note: When you remove the CentraSite destination from API Gateway, this implies that the API is provided by API Gateway and therefore the details of API are not read-only. You can edit them as required.

When you deploy

For more information about Modifying API, see Modifying API Details.

Versioning APIs

API Gateway supports the creation of new API versions from the existing versions. The new API has the same metadata but with an updated version. The version can either be a number or a string.

The API details page has a drop-down list that displays all the existing API versions. You can create a new version of an API and retain applications that are associated with older versions of the API. When an API is updated, it retains the Expose to consumers settings, the existing scope definitions, the configured policies, and the REST-enabled path configurations for SOAP API.

When you create a new version, the newer version is assigned to the teams of the older version by default. You can later change the teams, if required.

Creating New API Version

You must have the API Gateway’s manage APIs functional privilege assigned to perform this task.

You can create a new version of an API from the latest version available for the API. For example, if the existing version is 1.1 for an API, you can create a version 1.2. If you want to create a version 1.3, you can only create it from the latest version 1.2 and not from 1.1. However, you can delete the intermediate versions. Additionally, even though the owner of the older API version is a different provider, when you create a new version of the API, you are the owner of the newly created version of the API. The new API version is in inactive state, irrespective of the state of the API from which it was versioned.

To create a new version

  1. Click APIs in the title navigation bar.

  2. Select the required API from the list of APIs.

  3. Click icon and select Create new version.

  4. In the Version field, type the new version for the API.

  5. Clear the Retain applications checkbox if you do not want to retain applications that are associated with older versions of the API.

  6. Click Create.

The Version drop-down lists the newly created API version in latest to older order in the API details page. The corresponding API details page is displayed when you select any particular version.

Note: The version is appended to the Gateway endpoint(s) URL once the API is activated and this can be seen in the Technical information section of the API details page. When a client application invokes the API without the version in the endpoint, API Gateway invokes the latest version.

API Scopes

API definitions can be complex and span across multiple REST resources and methods, or SOAP operations for an API. To reduce the complexity of an API definition, you can define scopes and impose a set of policies on each scope to suit your requirements.

A scope represents a logical grouping of REST resources, methods, or both, and SOAP operations in an API. You can then enforce a specific set of policies on each individual scope in the API.

An API can have a set of declared scopes. The available scopes for an API are listed in the Scopes tab of the API details page.

Creating an API Scope

Scopes enable you to group a set of REST resources, methods, or both, and SOAP operations for an API.

A scope consists of a name, description, and zero or more resources, methods, or operations. An API can have zero or more scopes.

You can define a set of policies and configure its properties for each individual scope. These policies apply to each of the resources, methods, or operations that are associated to the scope.

Instructions throughout the remainder of this guide use the term scope-level policy when referring to a set of policies configured for an individual scope of the API.

Note: Ensure that you have a unique set of resources, methods, or operations in every scope in the API.

To create a scope

  1. Click APIs in the title navigation bar.
    A list of APIs available in API Gateway appears.

  2. Click the name of the required API.
    This opens the API details page.

  3. Click Edit.
    If the API is active, API Gateway prompts you to deactivate it.

  4. Click the Scopes tab.
    This displays a list of scopes available in the API.

  5. In the List of scopes section, click Add scope.

  6. In the Basic information section, provide the required information for each data fields that appears:

    Field Description
    Name Name of the scope. A scope name must be unique within an API.

    Note: API Gateway automatically adds the name New Scope to the Name field. You can change the name of the scope to suit your needs. But you cannot leave this field empty.
    Description Description of the scope.

  7. Applicable only for REST APIs. In the Resources and methods section, select the resources, methods, or both, you want to associate to this scope.
    When selecting a resource or method for the scope definition, you can select whether you want some or all of the methods within that resource to be selected as well.

  8. Applicable only for SOAP APIs. In the Operations section, select the operations you want to associate to this scope.

  9. Click Save.
    The scope is created and listed in the List of scopes section.

Post-requisites:

Viewing List of API Scopes and Scope Details

The Scopes tab in the API details page displays a list of all available scopes in the API.

In addition to viewing the list of scopes, you can also examine and modify the details of a scope, and delete a scope in the Scopes tab.

To view the scope list and properties of a scope

  1. Click APIs in the title navigation bar.
    A list of APIs available in API Gateway appears.

  2. Click the name of the required API.
    This opens the API details page.

  3. Click the Scopes tab.
    This displays a list of scopes available in the API.

  4. In the List of scopes section, click the name of the scope you want to examine.

    This opens the details of the scope. The scope details appear in the following sections:

    • Basic information: This section contains a summary of basic information such as name and description of the scope.

    • Resources and methods: Applicable only for REST APIs. This section contains a collection of REST resources, methods, or both, that are associated to the scope.

    • Operations: Applicable only for SOAP APIs. This section contains a collection of SOAP operations that are associated to the scope.

Modifying API Scope Details

You use the Scopes tab in the API details page to examine and modify the details of a scope.

To modify the properties of a scope

  1. Click APIs in the title navigation bar.
    A list of APIs available in API Gateway appears.

  2. Click the name of the required API.
    This opens the API details page.

  3. Click Edit.
    If the API is active, API Gateway displays a warning message to let you know that the API is active.

  4. Click the Scopes tab.
    This displays a list of scopes available in the API.

  5. In the List of scopes section, click the name of the scope you want to modify.

    This opens the details of the scope. The scope details appears in the following sections:

    • Basic information: This section contains a summary of basic information such as name and description of the scope.

    • Resources and methods: Applicable only for REST APIs. This section contains a collection of REST resources, methods, or both, that are associated to the scope.

    • Operations: Applicable only for SOAP APIs. This section contains a collection of SOAP operations that are associated to the scope.

  6. Modify the basic properties, applicable resources, methods, or operations of the scope.

  7. Click Save.
    Activate the API, if it is not active, to put it into effect.

Deleting an API Scope

You delete a scope to remove it from the API permanently.

When a scope is deleted from the API definition, API Gateway deletes the existing associations between the scope and the collection of resources, methods, or operations in the API. But, the collection of resources, methods, or operations continue to exist in the API.

To delete a scope

  1. Click APIs in the title navigation bar.
    A list of all registered APIs appears.

  2. Click the name of the required API.
    This opens the API details page.

  3. Click Edit.
    If the API is active, API Gateway displays a warning message to let you know that the API is active.

  4. Click the Scopes tab.
    This tab displays a list of scopes available with the API.

  5. In the List of scopes section, locate the name of the scope you want to delete.

  6. Click the Delete (icon) icon next to the scope name.

  7. Click Yes in the confirmation dialog.
    The scope is removed from the List of scopes section.

  8. Click Save to save the updated API.
    Activate the API, if it is not active, to put it into effect.

Example - Usage Scenarios of API Scopes

API Provider can restrict the enforcement of policies at the resource-level or method-level for a REST API, and at the operations-level for a SOAP API. This policy enforcement on the resources, methods, or operations of the API will apply in addition to the default enforcement of policies at the global-level and the user-defined enforcement of policies at the API-level.

Consider you have a REST API, for example, PhoneStore API, with a collection of resources and methods.

Resource Name Resource Path Supported Methods
Resource A /phones/orders GET
POST
Resource B /phones/orders/{order-id} GET
PUT
DELETE
Resource C /phones/orders/{order-id}/paymentdetails GET
POST

In the following section, we demonstrate the application of scopes and the policy enforcement using Resource C: /phones/orders/{order-id}/paymentdetails of the PhoneStore API.

You can create scopes in the PhoneStore API, and define the individual scopes with a specific set of resources, methods, or both.

Scope Name Applied Resource Applied Method
PAYMENT Scope Resource C: /phones/orders/{order-id}/paymentdetails  
WRITE Scope Resource C: /phones/orders/{order-id}/paymentdetails POST

Assume you have an API-level policy which enforces an Identify and Authorize Application policy with HTTP Basic Authentication for the PhoneStore API. Now, you might need to have different authentication mechanisms for different methods and resources (collectively, scopes) of the PhoneStore API, depending on the level of access you need.

For example, you might want to enforce an Inbound Authentication - Transport policy with Require HTTP Basic Authentication for the Resource C in PAYMENT Scope to enforce secured access to the data. You might also want to apply an Identify and Authorize Application policy with API Key authentication and Traffic Optimization policy (with 5 API invocations per minute), in particular, for the POST method of the Resource C in WRITE Scope to enforce a higher-level of secured access and manipulation of the REST data.

API-level/Scope-level Policy Applied Policies
API-level Policy Identify and Authorize policy with HTTP Basic Authentication
Scope-level Policy for PAYMENT Scope Inbound Authentication - Transport
Scope-level Policy for WRITE Scope Identify and Authorize policy with API Key

Traffic Optimization

The API Scopes definition looks like this:

API-level / Scope-level Policy Applied Policies
API-level Policy Identify and Authorize policy with HTTP Basic Authentication
Policy for PAYMENT Scope Resource C: /phones/orders/{order-id}/paymentdetails   Identify and Authorize
Policy for WRITE Scope Resource C: /phones/orders/{order-id}/paymentdetails POST Identify and Authorize policy with API Key

Traffic Optimization

The precedence of the policy enforcement effective for an API at run-time is as follows:

  1. Global Policy Enforcement

  2. Method-level Policy Enforcement (REST APIs) -OR- Operation-level Policy Enforcement (SOAP APIs)

  3. Resource-level Policy Enforcement (REST APIs)

  4. API-level Policy Enforcement

The specific aspect of processing during the handling of an API invocation at run-time in API Gateway can be best understood with the following scenarios:

Scenario A: Invoke GET method on the Resource C: /phones/orders/{order-id}/paymentdetails

As per the precedence of policy enforcement, the Inbound Authentication - Transport at the resource-level and the Identify and Authorize Application policy with HTTP Basic Authentication at the API-level are enforced at run-time.

The effective policy set enforced on the API for the GET method at run-time includes:

Scenario B: Invoke POST method on the Resource C: /phones/orders/{order-id}/paymentdetails in WRITE Scope

As per the precedence of policy enforcement, the Identify and Authorize Application policy with API Key at the method-level takes precedence over the Identify and Authorize Application policy with HTTP Basic Authentication at the API-level, and is enforced at run-time.

The effective policy set enforced on the API for the POST method at run-time includes:

Now, consider that you apply an active Global Policy that has the Identify and Authorize policy with Hostname Address for all REST APIs (including our PhoneStore API).

Scenario C: Invoke POST method on the Resource C: /phones/orders/{order-id}/paymentdetails in WRITE Scope

As per the precedence of policy enforcement, the Identify and Authorize policy with Hostname Address applied through the global policy takes precedence over every other Identify and Authorize Application policy that is applied at the method-level and the API-level, and is enforced at run-time.

The effective policy set enforced on the API for the POST method at run-time includes: - Inbound Authentication - Transport

Resolving Scope Conflicts

When you save an API, API Gateway combines the scopes specified with the set of policies defined at the API-level, and on saving the API, API Gateway applies the policies to the API at various enforcement levels. API Gateway validates the scope list to ensure that it contains no conflicting or incompatible policies. If the list contains conflicts or inconsistencies, API Gateway prompts you with an error message.

Consider that you modify the existing UPDATE scope to include a POST method for Resource C. The API Scopes definition now looks like this:

API-level / Scope-level Policy Applied Policies
API-level Policy Identify and Authorize policy with HTTP Basic Authentication
Policy for PAYMENT Scope Resource C: /phones/orders/{order-id}/paymentdetails
Identify and Authorize policy
Policy for WRITE Scope Resource C: /phones/orders/{order-id}/paymentdetails
Method:POST
Identify and Authorize Application policy with API Key
Traffic Optimization
Policy for UPDATE Scope Resource C: /phones/orders/{order-id}/paymentdetails
Method:POST
Identify and Authorize policy with IP Address Range

Scenario D: Save the updated PhoneStore API.

As per the precedence of policy enforcement, the Identify and Authorize Application policy at the method-level in WRITE and UPDATE Scopes take precedence over the Identify and Authorize Application policy at the API-level. But the Identify and Authorize Application policy with the API Key and IP Address Range authentications that are applied at the method-level results in a policy conflict.

To resolve the conflicts, you can choose one of the following workaround:

Exposing a REST API to Applications

The API Provider can restrict the exposure of specific resources and methods of a REST API to other applications.

Consider you have a native REST API created in API Gateway with resources - Resource A, Resource B, and Resource C. You might want to expose Resource A and Resource C, and restrict the visibility of Resource B to other applications. You can use the Expose to consumers button to switch on the visibility of Resource A and Resource C and switch off the visibility of Resource B as required. Similarly, you can restrict the visibility of one or more methods within each individual resource.

If an application attempts to invoke the Resource C in the above REST API, API Gateway returns a HTTP response code 404.

By default, the Expose to consumers button is switched on for all resources and methods of the REST API. Once the API is activated, all of its resources and methods are exposed to registered applications. If you do not want a particular set of resources and methods, or a set of methods in a particular resource to be hidden for registered applications, switch off the Expose to consumers button in the REST API definition.

Note: Be aware that API Gateway does not allow you to activate a REST API if none of the methods in the API are selected for exposing to other applications. You must select at least one method of the REST API to enforce runtime invocations.

To expose a set of resources and methods of the REST API

  1. Click APIs in the title navigation bar.
    A list of APIs available in API Gateway appears.

  2. Click the name of the required API.
    This opens the API details page.

  3. Click Edit.
    If the API is active, API Gateway displays a warning message to let you know that the API is active.

  4. Click Resources and methods.
    This displays a list of resources and methods available in the API.

    a. To select a resource, switch on the Expose to consumers button next to the resource URI. You can select one or more resources to expose to other applications.

    b. To select a method within the resource, click on the resource path. In the expanded list of methods, switch on the Expose to consumers button next to the method name. You can select one or more methods to expose to other applications.

  5. Click Save to save the updated API.
    Activate the API, if it is not active, to put it into effect.

Exposing a SOAP API to Applications

The API Provider can restrict the exposure of specific operations of a SOAP API and GraphQL API to other applications.

Consider you have a native SOAP API or GraphQL API created in API Gateway with operations - Operation A, Operation B, and Operation C. You might want to expose the Operation A and Operation C, and restrict the visibility of Operation B to other applications. You can use the Expose to consumers button to switch on the visibility of Operation A and Operation C and switch off the visibility of Operation B, as required.

If an application attempts to invoke the Operation B in the SOAP API or GraphQL API, API Gateway returns a HTTP response code 404 for SOAP API and response code 400 for GraphQL API.

By default, the Expose to consumers action is switched on for all operations of the SOAP API and GraphQL API. Once the API is activated, exposed operations are available for use in the registered applications. If you do not want a particular set of operations to be hidden for registered applications, switch off Expose to consumers in the SOAP API or GraphQL API definition.

Note: Be aware that API Gateway will not allow you to activate a SOAP API or GraphQL API if none of the operations in the API are selected for exposing to other applications. You must select at least one operation of the SOAP API or GraphQL API to enforce runtime invocations.

To expose a set of operations of the SOAP API or GraphQL API

  1. Click APIs in the title navigation bar.

    This displays a list of APIs available in API Gateway.

  2. Click the name of the required API.

    This opens the API details page.

  3. Click Edit.

    If the API is active, API Gateway displays a warning message to let you know that the API is active.

  4. Click Operations.

    This displays a list of operations available in the API.

    a. To select an operation, switch on the Expose to consumers button next to the operation URI.

    You can select one or more operations to expose to other applications.

  5. Click Save to save the updated API.

    Activate the API, if it is not active, to put it into effect.

API Grouping

You can group APIs based on various categories. Categories help consumers locate APIs easily. For example, if you are offering APIs to help your consumers manage their sales and ordering better, classifying the APIs under Sales and Ordering helps them locate these APIs easily.

The default groups available under which you can group the APIs are Finance Banking and Insurance, Sales and Ordering, Search, and Transportation and Warehousing. If you want to include more groups you can update the property apiGroupingPossibleValues under Administration > Extended settings that enables API grouping. You can modify the existing list of groups by deleting or adding new group names as comma separated values in this field. Ensure that the group name does not contain a comma as part of the name.

API grouping can be applied in one of these ways:

You can select one or more groups in the API grouping field. When an API is published to API Portal, the published APIs in API Portal are grouped as per the group assigned.

API Tagging

Tags are words or phrases that act as keywords for categorizing, identifying, and organizing APIs.

In API Gateway, you can assign tags to APIs, and their resources, methods, or operations. Tags help to logically catagorize APIs in different ways, for example, by usage, owner, consuming application, or other criteria. Tags are especially useful when there are multiple APIs of the same type - it enables to quickly identify a specific API based on the tag assigned to it. For example, you can assign the tag GET-Methods to specific GET methods in different REST APIs, and use it to search for the list of REST APIs with the GET-Methods tag in API Gateway.

You can use tagging, for example, to do the following:

You can assign one or more tags, remove a tag, and view the tags on the API details page. When a tagged API is published to API Portal, the published API in API Portal is tagged with the same tag defined in API Gateway.

Adding Tags to an API

Pre-requisites:

You must have the Manage APIs functional privilege assigned to perform this task.

Tags are not automatically assigned to APIs, resources, methods, or operations. You can add one or more tags, and you can remove tags from an API, resource, method, or operation at any time.

You can define a set of consistent tags that meets your needs for each API, resource, method, or operation. Using a consistent set of tags makes it easier to manage the APIs, resources, methods, or operations. You can search the APIs, resources, methods, or operations based on the tags you add.

When tagging an API, keep the following points in mind:

To tag an API

  1. Click APIs in the title navigation bar.
    A list of all registered APIs appears.

  2. Select the required API. The API details page appears.

  3. Click Edit.

  4. To add tags to an API, in the Basic information section, do one of the following:

    • To add an existing tag, select an existing tag from the drop-down list and click icon
      Alternatively, you can search an existing tag by typing characters in the Tags field that displays a list of existing tags that contain the character, select the required tag, and click icon.

    • To add a new tag, type the new tag and click icon.

    The tag is listed below the Tags. To delete a tag, click the x icon.
    .

  5. To add tags to resources or methods of a REST API, in the Resources and methods section, locate the required resource or method and do one of the following:

    • To add an existing tag, select an existing tag from the drop-down list and click icon
      Alternatively, you can search an existing tag by typing characters in the Tags field that displays a list of existing tags that contain the character, select the required tag, and click icon.

    • To add a new tag, type the new tag and click icon.

    The tag is listed below the Tags. To delete a tag, click the x icon.

  6. To add tags to resources or methods of a SOAP API, in the Operations section, locate the required resource or method and do one of the following:

    • To add an existing tag, select an existing tag from the drop-down list and click icon
      Alternatively, you can search an existing tag by typing characters in the Tags field that displays a list of existing tags that contain the character, select the required tag, and click icon.

    • To add a new tag, type the new tag and click icon.

    The tag is listed below the Tags. To delete a tag, click the x icon.

  7. Click Save.

Exporting APIs

You must have the API Gateway’s export assets privilege assigned to perform this task.

Note: API Gateway supports backward compatibility for all the exported APIs from API Gateway 10.1 version or higher. For more information about exporting and importing APIs, see Overview.

To export an API

  1. Click APIs in the title navigation bar.

  2. You can export a single or multiple APIs as follows:

    • To export a single API, click icon next to the required API.

    • To export multiple APIs simultaneously, click the check-boxes adjacent to the names of the API, click icon and select Export from the drop-down list.

    • Select the API to open the API details page. Click icon and select Export. The Export archive window appears.

  3. Select Include applications if you want to export the applications associated with the APIs.

  4. Select Include application registrations if you want to add the RegisterdApplication object lists to be added to the exported APIs.
    This is not selected by default. But if you select Include applications, this option also gets selected. When both the options Include applications and Include application registrations are selected, the export archive contains APIs with RegisteredApplication objects and applications referenced by APIs with RegisteredApplication objects.
    These exported RegisteredApplication objects are merged with the RegisteredApplication objects in the API Gateway instance where it is imported. The import of these RegisteredApplication objects is based on the value of the import option Overwrite Registered Application. The option Overwrite Registered Application is not selected by default. But, if you select the option Overwrite Application during an import, then Overwrite Registered Application is also selected to support backward compatibility.

  5. Select Include groups if you want to export the groups associated to the team that the APIs belong to.

  6. Select Include users if you want to export the users associated to the team that the APIs belong to.

    Note: The Include groups and Include users check boxes appear, only if you have set the enableTeamWork extended setting to true.

  7. Click Export.
    The browser prompts you to either open or save the export archive.

  8. Select the appropriate option and click OK.

Exporting Specifications

For a REST API, you can export specifications in Swagger and RAML formats to your local system. Similarly, for a SOAP API, you can export a specification in WSDL format to your local system. The exported WSDL is in a ZIP format consisting of the WSDL file whereas for Swagger and RAML the respective files are directly exported. API Gateway supports the following versions:

You can export APIs that have been created from scratch or by importing their respective definitions. The Swagger or RAML definition provides the consumer view on a REST API deployed to the API Gateway. Similarly, the WSDL definition provides the consumer view on a SOAP API. Consumer view indicates that the Swagger, RAML, or WSDL definitions contain the API Gateway endpoint and information about those resources and operations, which are exposed to customers.

Note: In the downloaded Swagger document, the valid JSON schemas attached to a response or a request does not always appear. Only the valid JSON schemas appear correctly. For any other schema information just the generic JSON schema such as {"type":"object"} appears.

To export the specification

  1. Click APIs in the title navigation bar.

  2. Select the required API from the list of available APIs.
    The API details page for the selected API appears.

  3. Click Documentation.

  4. Based on the type of specification that you have selected to export, select any of the following:

    • Swagger data link to export the Swagger specification.

    • RAML data link to export the RAML specification.

    • OpenAPI data link to export the OpenAPI specification.

    • Artifacts link to export the WSDL specification.

    • OData meta document link to a zip containing the OData API and metadata document. If the OData API is active, a link to the service document and a link to the metadata document are also displayed.

    • Schema link to download the GraphQL Schema.

    When downloading a zip file the browser prompts you to either open or save the zip file.

  5. Select the appropriate option and click OK.

Deleting APIs

Deleting an API permanently removes the API from API Gateway.

When deleting an API, keep the following points in mind:

Deleting a Single API

Pre-requisites:

You must have the Manage APIs functional privilege assigned to perform this task.

You delete an API to remove it from API Gateway permanently.

To delete an API

  1. Click APIs in the title navigation bar.
    A list of all APIs appears.

  2. Click the Delete icon for the API that you want to delete.

  3. Select the Force delete option to delete an API forcefully.
    API Gateway ignores any failures even if the API is used by other applications, and clears all data from the API Gateway database.

  4. Click Yes in the confirmation dialog.
    The API is deleted forcefully.

Deleting Multiple APIs in a Single Operation

Pre-requisites:

You must have the Manage APIs functional privilege assigned to perform this task.

You can bulk delete APIs in API Gateway.

To delete multiple APIs in a single operation

  1. Click APIs in the title navigation bar.
    A list of all APIs appears.

  2. Select the APIs that you want to delete.

  3. In the Menu icon icon, click Delete.

  4. Select the Force delete option to delete APIs forcefully.
    API Gateway ignores any failures even if the selected APIs are used by other applications, and clears all data from the API Gateway database.

  5. Click Yes in the confirmation dialog.
    The APIs are deleted forcefully from API Gateway.

  6. Examine the Delete APIs report window and check for any errors that occurred during the deletion process.
    The Delete APIs report window displays the following information:

    Parameter Description
    Name The name of the deleted API.
    Status The status of the deletion process. The available values are:

    • Success

    • Failure
    Description A descriptive information if the deletion fails or if a warning occurs.

    API Gateway writes these results to the Audit logs dashboard, so you can view them later.

  7. Click Download the detailed report here to download the detailed report as an HTML file.

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 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:

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:

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:

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:

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


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>