Publish APIs

Why Publish APIs?

After you build your APIs, you have to publish them to make the APIs available for consumption by developers and consumers. Publishing an API enables developers and consumers to consume the functionalities exposed through your API. They can then integrate the functionalities, the APIs provide,into applications easily. Creating and developing an API in API Gateway does not make it accessible to your users. You must first activate the API before publishing it to a portal so that the gateway endpoint is available for the developers and consumers to invoke the API.

API Gateway allows you to publish APIs to Developer Portal from where they are available for consumption by developers and consumers.

Optionally, API Gateway also allows you to publish the APIs to the following destinations:

In addition to publishing, API Gateway provides you with capabilities to customize your APIs before publishing them. You can customize APIs depending on how you want to restrict exposure of specific information the APIs handle as follows:

The following sections describe how you can activate an API, customize the gateway endpoint, and publish APIs to different destinations.

Activating an API

You must first activate the API before publishing it to a portal so that the gateway endpoint is available for developers and consumers to invoke the API.

You must have the Activate/Deactivate APIs functional privilege assigned to perform this task. You can activate an API in the Manage APIs page. Alternatively you can also activate the API from the API Details page.

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.

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 and GraphQL 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.

Gateway Endpoints

Gateway endpoint is the URL that is used to access an API through API Gateway. By default, API Gateway provides a default gateway endpoint for all active APIs. The default gateway endpoint is in the <protocol>://<hostname>/{defaultPrefix}/{apiName}/{apiVersion}/{resourcePath} format.

When there is a need to access the API using a different endpoint, you can define a custom gateway endpoint. In custom gateway endpoints, you can customize the portion of the URL between <host> and <resourcePath>.

Custom gateway endpoints can be specific to an API or a global template can be defined through global gateway endpoint.

How do I Define API-specific Gateway Endpoints?

This use case explains how to define custom gateway endpoints specific to an API. You can define more than one custom gateway endpoint to an API. Custom gateway endpoints can be added for all types of APIs such as REST, SOAP, OData.

The use case starts when you want to define API specific gateway endpoint and ends when you have created the API specific gateway endpoint.

Here are some points that you need to consider, when you define API specific gateway endpoint:

Important
At any given point, API Gateway does not allow you to provide the same gateway endpoint for different APIs nor different versions of same API. Hence, make sure that you provide an unique gateway endpoint, so that it does not match with any of the existing APIs’ default or custom gateway endpoints.

Before you begin

Ensure that you have:

  • Manage APIs functional privilege.

  • Activated the API.

    • To define API-specific gateway endpoints

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

      Note
      You can manage the gateway endpoints of an API, directly from the view mode of the API details screen.

    2. Click the corresponding API for, which you want to customize the gateway endpoint.
      The API details page appears.

    3. Click Technical information.

    4. Click +Add custom gateway endpoint and provide the following information.

      Field Description
      Name Specifies the name for the custom gateway endpoint. A gateway endpoint name must be unique within an API.
      URL Specifies the custom gateway endpoint.
      The gateway endpoint name cannot include a space, nor can it include the following special characters: # % ? ‘ “ < \

    5. Click Save.
      The added custom gateway endpoint appears in the Gateway endpoint(s) field of the API details page. In addition to the default gateway endpoint, you can access the API using this custom gateway endpoint.

      Note
      You can edit or delete the gateway endpoint from API details page either by clicking the or icon corresponding to the gateway endpoint that you want to edit or delete.

    How do I Define Global Gateway Endpoint?

    This use case explains how to define global gateway endpoint. The global gateway endpoint creates gateway endpoint template for all APIs. Each API will inherit this global endpoint in addition to the default and custom endpoints of an API.

    The use case starts when you want to define global gateway endpoint and ends when you have created the global gateway endpoint.

    In order to generate a unique gateway endpoint for each API version, the global gateway endpoint template must use the following variables :

    Publishing APIs to Developer Portal

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

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

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

    Doing this involves the following high-level steps:

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

    Publishing a Single API to Developer Portal

    Pre-requisites:

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

    To publish an API to Developer 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 Developer Portal in one of the following ways:

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

      • Publish as SOAP: The API is published as a SOAP API with the SOAP operations to Developer 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 Developer 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 Developer 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 Developer Portal and available for the consumers to consume it.

      A REST-enabled SOAP API is published to Developer 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 Developer Portal in a Single Operation

    Pre-requisites:

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

    You can bulk publish APIs to Developer Portal.

    To publish multiple APIs to Developer 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 Developer Portal.

    5. Click Publish.
      The APIs along with their associated endpoints are published to Developer 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 Developer 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.

    Unpublishing APIs from Developer Portal

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

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

    Unpublishing a Single API from Developer Portal

    Pre-requisites:

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

    To unpublish an API from Developer 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 Developer 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 Developer Portal destination. The API is no longer available on Developer 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 Developer Portal in a Single Operation

    Pre-requisites:

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

    You can bulk unpublish APIs from Developer Portal.

    To unpublish multiple APIs from Developer 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 Developer 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.

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