Define and Manage APIs

Important
Do not provide values starting with a dot (.), in any of the fields in API Gateway UI as Elasticsearch does not support saving those values.

Defining and Managing APIs

APIs are designed to expose application functionality and data for use by consumers and developers, as necessary. A basic API definition influences how efficiently consumers or developers are able to consume and use an API. Core API design considerations are fueled by business drivers, developer and consumer audiences, as well as the available resources. Therefore, a careful consideration of all influencing factors affects the planning and architectural decisions you make while designing and defining your API.

The following figure depicts the various factors that drive the designing and defining of an API.

API Gateway enables organizations to define and manage their APIs. Developer and partner users can use API Gateway’s design and customization capabilities to build, develop, and then publish APIs to a portal for consumption by internal and external API consumers.

The following sections describe the types of APIs that API Gateway supports, the different ways in which you can create APIs, update APIs, create and maintain different versions of an API, and group and tag APIs.

API administrators and users with the appropriate functional privileges can use API Gateway’s capabilities to create and manage APIs, and publish the APIs to Developer Portal or service registries from where they can be consumed.

API Gateway supports the following API types:

Asynchronous APIs

API Gateway provides an asynchronous form of API support for REST APIs. The synchronous and asynchronous nature of an API depends on the way how a request sent by an application is processed, and the mode and the time frame in which the data is returned to the client.

The following are the differences between the synchronous and asynchronous APIs.

Synchronous API Asynchronous API
Synchronous API is used where data or service availability, resources and connectivity are high and requires low latency. Asynchronous API is used where data or service availability, resources and connectivity are low or over-saturated with demand.
The client application requests data and waits until it receives a response to proceed with other processes. The expectation is an immediate response The client application requests data and continues with other processes without waiting for a response. There is no expectation of an immediate response.

Consider this example of synchronous and asynchronous APIs performing a log purge operation. In this scenario, because there is a wait period for the return of data, synchronous API invocations might time out when the API processes take a significant period of time to complete. The following figure depicts the differences between how a synchronous and an asynchronous API perform the log purge operation.

While creating a REST API, API Gateway provides the capability of defining the callback component with the supported method parameters. For details about creating an API with the callback defiition, see Creating a REST API.

Creating APIs

You can create and manage APIs from the Manage APIs page in API Gateway UI. The page lists all the APIs, their description, and version number. On this page you can create an API, delete an API, view API details, activate or deactivate an API, publish or unpublish an API, view API analytics, group APIs, and add tags to an API.

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

The following sections explain in detail about different ways of creating APIs.

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.

    Note
    Importing an API fails for an invalid WSDL 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
  • Importing an API fails for an invalid WSDL file.
  • 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. 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.

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 or disable mocking, update, and create new version operations.

    The list of registered applications is sorted by name in ascending order and you can view the total count of registered applications. If the list of registered applications is long, then the applications are distributed in more than one page. You can navigate between the pages by selecting the page numbers provided below the grid.

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:

Exposing a SOAP API to Applications

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

Searching Data

The search feature in API Gateway is a typeahead search—a simple and easy to use search facility where you can type the text of interest to search. You can search for all items that contain one or more specified keywords (that is, text strings) in the item’s properties. Some of the properties are name, description, version, key, value, and so on in the API.

You can search for the following types of data as shown in the image.

To search for an item, simply type a string in the search box in the title navigation bar. A list of search result is displayed directly below the Search box. The number of matches found are displayed in five sections depending on the type they fit in: APIs, Application, Alias, Packages, and Plans. A minimum of five search results are displayed in each category. If there are no results as per the search string typed, a message displays saying so.

If you find what you are searching for in the search result box, click on it to view the details. You are navigated to the specific page that displays more information. For example, if you are searching for an API and click the displayed result, you are navigated to the specified API details page. If you are searching for an application and click the displayed result, you are navigated to the specified Application details page.

If you want to see all the search results click Show all results in the search result box. The Advanced search page is displayed. This is a dedicated page that displays extensive search results. In the Advanced search page, you can search or filter the results in the following ways: by type or keyword.

Note
Search by keyword will not show any search results, if the field names have any special characters. The following special characters are not supported - ! ? & # $ * % : ; = ‘ “ ( ) / \ < >
The fields that does not support special characters are as follows:
- Maturity state
- Scope name
- Scope description
- API Operations info name
- API Resource path
- API Tags
- Application identifiers named values
- User Login ID
- User First name
- User Last name
- OAuth scope name
- OAuth Scope description
For example, if an API has a tag name Test-001, and you search APIs with the tag name Test-001, you will not get any search results.

You cannot search for REST resources and methods in a REST API. The search function only works for the name and description of the REST API. For example, you can search for a REST API named LibraryAPI. But you cannot search for a REST resource named book or a REST method POST within the REST API. However, the search function works for name, description, and operations of SOAP APIs.You cannot search for resources and methods of an OData API.

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. You can filter APIs based on the following filter options.
    You can use a combination of these options to filter the APIs.

    • Type. Select REST, SOAP, OData, GraphQL or all to filter APIs by type.

    • Activation status. Select Active or Inactive to filter APIs by their activation status.

    • Team. This filter is applicable only if you have enabled the Teams feature. Select the teams listed to filter APIs by their association with the teams selected.

    • Active endpoints. Select API Gateway, or Microgateway to filter APIs by their active endpoints available.

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

Configuring the Number of APIs listed on a Page

You can configure the number of APIs that get listed per page in the Manage APIs or the Manage applications page. In each of these pages, you can use the pagination bar at the bottom of the page to navigate from one page to another, the first page, or the last page when there are more than 20 APIs in the list. To change the number of APIs listed in a page, select the required number in the Show # results per page field in the pagination bar at the bottom of the page. The API list now displays only those many APIs in one page as specified. For example, if you select Show 10 results per page, only 10 APIs are listed in one page.

This configuration that you change through the drop down is maintained as long as you are logged in to API Gateway.

The value is set in the drop down is applicable for both APIs and applications listing. For example, if you change the show results to 10 in the Manage APIs drop down, then the number is retained for Manage applications page as well.

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.

    Note
    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.

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.

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.

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 Developer Portal, the published APIs in Developer 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 Developer Portal, the published API in Developer 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.

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.

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>

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.