Google is committed to advancing racial equity for Black communities. See how.

Publish your APIs

Publish APIs to your portal to make them available for consumption by app developers, as described in the following sections.

Overview of API publishing

The process of publishing APIs to your portal is a two-step process:

  1. Select the API product that you want to publish to your portal.
  2. Render API reference documentation from a snapshot of your OpenAPI Specification to enable app developers to learn about your APIs. (For more information about snapshots, see What is a snapshot of an OpenAPI Specification?

What is published to the portal?

When you publish an API, the following updates are made to your portal automatically:
  • SmartDocs API reference documentation is added to your portal

    The SmartDocs API reference documentation is rendered from a snapshot of your OpenAPI Specification. The SmartDocs UI is based on Angular material, a state-of-the-art UI components library.

    Developers can review your SmartDocs API reference documentation and use the Try this API panel to make an API request and view the output. Try this API works with unsecured endpoints or secured endpoints using Basic, API Key, or OAuth Authentication, based on the security method defined in your OpenAPI Specification. For OAuth, the following flows are supported: authorization code, implicit, password, and client credentials.

    Click to expand the Try this API panel. The expanded panel enables you to view the curl call and code samples in various formats, such as HTTP, Python, Node.js, and more, as shown below.

  • A link to the API Reference page is added to the APIs page

    The APIs page (included with the sample portal) provides a list of all APIs published to your portal with links to the respective API reference documentation for more information. You can customize the image displayed for each API card.

What is a snapshot of an OpenAPI Specification?

Each OpenAPI Specification serves as the source of truth throughout the lifecycle of an API. The same specification is used at each phase in the API lifecycle, from development to publishing to monitoring. When you modify a specification, you need to be cognizant of the impact the changes have on your API through other lifecycle phases, as described in What happens if I modify a specification?

When you publish your API, you take a snapshot of the OpenAPI Specification to render API reference documentation. That snapshot represents a specific version of the specification in the spec store. If you modify the OpenAPI Specification using the spec editor, you may decide to take another snapshot of the specification in order to reflect the latest changes in the API reference documentation.

Apigee Edge supports OpenAPI Specification 3.0 when you create OpenAPI Specifications using the spec editor and generate interactive API reference documentation using SmartDocs on your portal (described below), though a subset of features are not yet supported. For more information, see Known issues with integrated portal.

About callback URLs

If your apps require a callback URL, such as when using the OAuth 2.0 authorization code grant type (often referred to as "three-legged OAuth"), you can require developers to specify a callback URL when they register their apps. The callback URL typically specifies the URL of an app that is designated to receive an authorization code on behalf of the client app. For more information, see Implementing the authorization code grant type.

Note: The callback URL is stored as a custom attribute in the corresponding Edge app entity. If you are using a third-party identity provider, you are responsible for syncing the callback URL metadata.

You can configure whether or not to require a callback URL during app registration when adding an API to your portal. You can modify this setting at any time, as described in Manage the callback URL for an API.

When registering an app, developers must enter a callback URL for all APIs that require it, as described in Register apps.

Configure your API proxy to support "Try this API"

Before publishing your APIs, you'll need to configure your API proxy to support making requests on the Try this API panel in the SmartDocs API reference documentation, as follows:

  • Add CORS support to your API proxies to enforce client-side cross-origin requests

    CORS is a standard mechanism that allows JavaScript XMLHttpRequest (XHR) calls executed in a web page to interact with resources from non-origin domains. CORS is a commonly implemented solution to the "same-origin policy" that is enforced by all browsers.

  • Update your API proxy configuration if you are using basic authentication or OAuth2

The following table summarizes the API proxy configuration requirements to support the Try this API panel in the SmartDocs API reference documentation based on the authentication access.

Auth access Policy configuration requirements
None or API key Add CORS support to your API proxy. For convenience, use the sample CORS solution provided on GitHub or follow the steps described in Adding CORS support to an API proxy.
Basic authentication Perform the following steps:
  1. Add CORS support to your API proxy. For convenience, use the sample CORS solution provided on GitHub or follow the steps described in Adding CORS support to an API proxy.
  2. In the Add CORS AssignMessage policy, ensure the Access-Control-Allow-Headers header includes the authorization attribute. For example:
    <Header name="Access-Control-Allow-Headers">
      origin, x-requested-with, accept, content-type, authorization
    </Header>
OAuth2
  1. Add CORS support to your API proxy. For convenience, use the sample CORS solution provided on GitHub or follow the steps described in Adding CORS support to an API proxy.
  2. In the Add CORS AssignMessage policy, ensure the Access-Control-Allow-Headers header includes the authorization attribute. For example:
    <Header name="Access-Control-Allow-Headers">
      origin, x-requested-with, accept, content-type, authorization
    </Header>
  3. Correct non-RFC-compliant behavior in your OAuth2 policy. For convenience, use the sample OAuth2 solution provided on GitHub or perform the following steps:
    • Ensure that the <GrantType> element in the OAuth2 policy is set to request.formparam.grant_type (form param). For more information, see <GrantType>.
    • Ensure that the token_type in the OAuth2 policy is set to Bearer, and not the default BearerToken.

Explore the APIs page

To view the APIs published to your portal:
1. Select Publish > Portals and select your portal.
2. Click APIs on the portal home page.
Alternatively, you can select APIs in the portal drop-down menu in the top navigation bar.

The list of APIs is displayed.

API reference

As highlighted in the previous figure, the APIs page enables you to:

Add an API to your portal

To add an API to your portal:

  1. Select Publish > Portals and select your portal.
  2. Click APIs on the portal home page.

    Alternatively, you can select APIs in the portal drop-down menu in the top navigation bar.

  3. Click + API.

    The Add API Product to Portal dialog displays.

  4. On the Select Product tab, select the API product that you want to add to your portal.

  5. Click Next.

  6. Configure the API reference documentation content and its visibility on the Documentation tab:

    Field Description
    API documentation source Select the source to use for the snapshot. Select Select an OpenAPI Spec to select or upload a specification. Alternatively, you can select No API documentation and add one later after the API has been added, as described in Manage the snapshot of the specification.
    Visibility

    If you have not enrolled in the Beta release of the developer team and audience management features, select one of the following options:

    • Anonymous users to allow all users to view the API.
    • Registered users to allow only registered users to view the API.

    You can manage the audience later, as described in Manage the audience for an API on your portal.

    If you have enrolled in the Beta release of the developer team and audience management features, select one of the following options:

    • Public (visible to anyone) to allow all users to view the API.
    • Authenticated users to allow only registered users to view the API.
    • Selected audiences to select the specific audiences that you want to be able to view the API.

    You can manage audience visibility later, as described in Manage the visibility of an API in your portal.

    StatusSelect Published to publish the API to your portal. Select Unpublished if you are not ready to publish the API. You can change the setting later, as described in Publish or unpublish an API on your portal.

  7. Configure the following information on the Customize tab:

    Field Description
    TitleUpdate the title of your API. By default, the API product name is used.
    DescriptionUpdate the description of your API. By default, the API product description is used.
    API Product Image To display an image on the API card on the APIs page, click Select an image. In the Select image dialog, select an existing image, upload a new image, or provide the URL of an external image. You can add an image later, as described in Manage the image for an API card on your portal.

    Note: The size of the API card image is defined in the default theme as 344px x 192px. Be sure to select an image with a relative size. Alternatively, you can modify the image size for the API card, as described in Customize the appearance of the API card on the APIs page.

    Callback URLSelect Require app owners to specify a callback URLif you want to require that app developers specify a callback URL. You can add or update the callback URL later, as described in Manage the callback URL for an API.
  8. Click Finish.

Manage the snapshot of the specification

After you publish your API, at any time you can take a new snapshot of the OpenAPI Specification to update the API reference documentation that is published on your portal.

To manage the snapshot of the OpenAPI Specification:

  1. Select Publish > Portals and select your portal.
  2. Click APIs on the portal home page.

    Alternatively, you can select APIs in the portal drop-down menu in the top navigation bar.

  3. Position the cursor over the API for which you want to take a snapshot to display the actions.

  4. Click Snapshot icon.

    Note: A message is displayed if your snapshot is current with the source specification selected.

  5. Select an existing specification from the Update API documentation source drop-down or select Select an OpenAPI Spec to select or upload a new specification to use for generating documentation for the API.

    Alternatively, you can select No API documentation to remove the current specification.

  6. Click Update Snapshot (or Remove Snapshot, if you have selected No API documentation).

API reference documentation is rendered from the specification and added to the API Reference page.

Publish or unpublish an API on your portal

To publish or unpublish an API on your portal:

  1. Select Publish > Portals and select your portal.
  2. Click APIs on the portal home page.

    Alternatively, you can select APIs in the portal drop-down menu in the top navigation bar.

  3. Position the cursor over the API that you want to publish or unpublish.

  4. Click Settings icon.

  5. Select the Enabled checkbox to publish the API on your portal. Deselect Enabled to unpublish the API.

  6. Click Save.

Manage the audience for an API on your portal

Manage the audience for your API on your portal by allowing access to:

  • All users
  • Registered users only

To manage the audience for an API on your portal:

  1. Select Publish > Portals and select your portal.
  2. Click APIs on the portal home page.

    Alternatively, you can select APIs in the portal drop-down menu in the top navigation bar.

  3. Position the cursor over the API for which you want to manage the audience to display the actions.

  4. Click Settings icon.

  5. Under Audience, select one of the following options:

    • Anonymous users to allow all users to view the API product.
    • Registered users to allow only registered users to view the API product.
  6. Click Save.

Manage the visibility of an API in your portal (Beta)

Manage the visibility of an API in your portal by allowing access to:

  • Public (visible to anyone)
  • Authenticated users
  • Selected audiences

You create and manage the audiences for your portal, as described in Manage the audience for your portal.

To manage the visibility of an API in your portal:

  1. Select Publish > Portals and select your portal.
  2. Click APIs on the portal home page.

    Alternatively, you can select APIs in the portal drop-down menu in the top navigation bar.

  3. Position the cursor over the API for which you want to take a manage the visibility to display the actions.

  4. Click

  5. Select one of the following options:

    • Public (visible to anyone) to allow all users to view the API product.
    • Authenticated users to allow only registered users to view the API product.
    • Selected audiences to select the specific audiences that you want to be able to view the API product.
  6. Click Submit.

Manage the callback URL for an API

Manage the callback URL for an API. See About callback URLs.

To manage the callback URL for an API:

  1. Select Publish > Portals and select your portal.
  2. Click APIs on the portal home page.

    Alternatively, you can select APIs in the portal drop-down menu in the top navigation bar.

  3. Position the cursor over the API for which you want to manage the callback URL to display the actions.

  4. Click Settings icon.

  5. Update the callback URL for the authenticated APIs, as required.

  6. Click Save.

Manage the image for an API card

Manage the image that appears with an API card on the APIs page by adding or changing the current image.

To manage the image for an API card:

  1. Select Publish > Portals and select your portal.
  2. Click APIs on the portal home page.

    Alternatively, you can select APIs in the portal drop-down menu in the top navigation bar.

  3. Position the cursor over the API for which you want to manage the image to display the actions.

  4. Click Settings icon.

  5. Under Image:

    • Click Remove to remove the current image.
    • Click Select to select or upload an image.
  6. Click Save.

Edit the API details

To edit the API details:

  1. Select Publish > Portals and select your portal.
  2. Click APIs on the portal home page.

    Alternatively, you can select APIs in the portal drop-down menu in the top navigation bar.

  3. Position the cursor over the API that you want to edit.

  4. Click Settings icon.

  5. Edit the fields, as required.

  6. Click Save.

Remove an API from your portal

To remove an API from your portal:

  1. Select Publish > Portals and select your portal.
  2. Click APIs on the portal home page.

    Alternatively, you can select APIs in the portal drop-down menu in the top navigation bar.

  3. Position your cursor over the API in the list to display the actions menu.

  4. Click Delete.

Troubleshoot issues with your published APIs

The following sections provide information to help you troubleshoot specific errors with our published APIs.

Error: Failed to fetch error returned when using Try this API

When using Try this API, if the TypeError: Failed to fetch error is returned, consider the following possible causes and resolutions:

  • For mixed content errors, the error may be caused by a known swagger-ui issue. One possible workaround is to make sure that you specify HTTPS before HTTP in the schemes definition in your OpenAPI Specification. For example:

    schemes:
       - https
       - http
    
  • For Cross-Origin Resource Sharing (CORS) restriction errors, ensure that CORS is supported for your API proxies. CORS is a standard mechanism that enables client-side cross-origin requests. See Configure your API proxy to support Try this API.

Error: 'Access-Control-Allow-Origin' header contains multiple values '*, *', but only one is allowed

When using Try this API, you may receive the following error message if the Access-Control-Allow-Origin header already exists:

The 'Access-Control-Allow-Origin' header contains multiple values '*, *', but only one is allowed.

To correct this error, modify the AssignMessage policy to use <Set> to set the CORS headers instead of <Add>, as shown in the excerpt below. For more information, see the relevant community article.

<AssignMessage async="false" continueOnError="false" enabled="true" name="add-cors">
    <DisplayName>Add CORS</DisplayName>
    <FaultRules/>
    <Properties/>
    <Set>
        <Headers>
            <Header name="Access-Control-Allow-Origin">{request.header.origin}</Header>
            <Header name="Access-Control-Allow-Headers">origin, x-requested-with, accept, content-type, authorization</Header>
            <Header name="Access-Control-Max-Age">3628800</Header>
            <Header name="Access-Control-Allow-Methods">GET, PUT, POST, DELETE</Header>
        </Headers>
    </Set>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <AssignTo createNew="false" transport="http" type="response"/>
</AssignMessage>

Error: Request header field not allowed

When using Try this API, if you receive a Request header field not allowed error, similar to the example below, you may need to update the headers supported in the CORS policy. For example:

Access to XMLHttpRequest ... has been blocked by CORS policy: Request header field
content-type is not allowed by Access-Control-Allow-Headers in preflight response

In this example, you need to add the content-type header to the Access-Control-Allow-Headers section in your CORS AssignMessage policy, as described in Attaching an Add CORS policy to a new API proxy.

Error: Access denied when calling an API proxy using OAuth2

Apigee’s OAuthV2 policy returns a token response that contains certain non-RFC-compliant properties. For example, the policy will return a token with the value BearerToken, instead of the expected RFC-compliant value Bearer. This invalid token_type response can result in an Access denied error when using Try this API.

To correct this issue, you can create a JavaScript or AssignMessage policy to transform the policy output into a compliant format. For more information, see non-RFC-compliant behavior.