Publishing your APIs

This page applies to Apigee and Apigee hybrid.

View Apigee Edge documentation.

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 your OpenAPI document or GraphQL schema to enable app developers to learn about your APIs. (For more information, see About API documentation)

What is published to the portal?

When you publish an API, the following updates are made to your portal automatically:

  • API reference documentation. The interface provided depends on whether you publish your API using an OpenAPI document or GraphQL schema. See:
  • 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, listed in alphabetical order, with links to the respective API reference documentation for more information. Optionally, you can customize the following:

    • Image displayed for each API card
    • Categories used for tagging APIs to enable developers to discover related APIs on the APIs page
    APIs page in live portal showing two categories and use of images APIs page in live portal showing two categories and use of images

SmartDocs (OpenAPI)

When you publish an API using an OpenAPI document, the SmartDocs API reference documentation is added to your portal.

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 document. For OAuth, the following flows are supported: authorization code, password, and client credentials.

API reference documentation page with callouts that show how to authorize your API call, undock the Try this API panel, download the relevant spec, and execute the API.

API reference documentation page with callouts that show how to authorize your API call, undock the Try this API panel, download the relevant spec, and execute the API.

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

Expanded Try this API panel

Expanded Try this API panel

GraphQL Explorer

When you publish an API using a GraphQL schema, the GraphQL Explorer is added to your portal. The GraphQL Explorer is an interactive playground for running queries against your API. The explorer is based on GraphiQL, a reference implementation of the GraphQL IDE developed by the GraphQL Foundation.

Developers can use the GraphQL Explorer to explore the schema-based interactive documentation, build and run queries, view query results, and download the schema. To secure access to your API, developers can pass authorization headers in the Request Headers pane. For more information about GraphQL, see graphql.org.

GraphQL Explorer in the portal

GraphQL Explorer in the portal

About API documentation

Each OpenAPI or GraphQL document serves as the source of truth throughout the lifecycle of an API. The same document is used at each phase in the API lifecycle, from development to publishing to monitoring. When you modify a document, 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 document?

When you publish your API to a portal, you save a version of the OpenAPI or GraphQL document to render API reference documentation. If you modify the document, you may decide to update the API reference documentation published to the portal in order to reflect the latest changes.

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.

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

Configure your API proxy to support the Try this API panel

Before publishing your APIs using an OpenAPI document, 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 OAuth 2.0.

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, 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, follow the steps described in Adding CORS support to an API proxy.
  2. In the Add CORS 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>
OAuth 2.0
  1. Add CORS support to your API proxy, follow the steps described in Adding CORS support to an API proxy.
  2. In the Add CORS 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 OAuth 2.0 policy. For convenience, use the sample OAuth 2.0 solution provided on GitHub or perform the following steps:
    • Ensure that the <GrantType> element in the OAuth 2.0 policy is set to request.formparam.grant_type (form param). For more information, see <GrantType>.
    • Ensure that the token_type in the OAuth 2.0 policy is set to Bearer, and not the default BearerToken.

Manage APIs

Manage your APIs as described in the following sections.

Explore APIs

Use the console or curl command to view APIs that are in your portal.

Console

To view the API catalog:

  1. Select Publish > Portals and select your portal.
  2. Click API catalog on the portal home page.
    Alternatively, you can select API catalog in the portal drop-down menu in the top navigation menu.
    The APIs tab in the API catalog displays a list of the APIs that have been added to your portal.

    APIs tab that shows information about the APIs including name, description, visibility, categories, associated spec, and modified

    APIs tab that shows information about the APIs including name, description, visibility, categories, associated spec, and modified

    As highlighted in the previous figure, the APIs tab lets you:

curl

To list APIs using organizations.sites.apidocs/list:

curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"

Replace the following:

  • ORG_NAME with the name of the organization. For example, my-org.
  • SITE_ID with the name of the portal, in the form ORG_NAME-PORTAL_NAME, where ORG_NAME is the name of the organization and PORTAL_NAME is the portal name converted to all lowercase and with spaces and dashes removed. For example, my-org-myportal.

See Pagination notes for instructions on using pagination in the response payload.

Response payload:

{
  "status": "success",
  "message": "one page of apidocs returned",
  "requestId": "1167960478",
  "data": [
    {
      "siteId": "my-org-myportal",
      "title": "Hello New World",
      "description": "Simple hello new world example",
      "specId": "hellowworld",
      "modified": "1695841621000",
      "anonAllowed": true,
      "imageUrl": "/files/camper1.jpg?v=1695841491415",
      "id": "381054",
      "categoryIds": [
        "e0518597-ece2-4d7d-ba7c-d1793df0f8db",
        "61c1014c-89c9-40e6-be3c-69cca3505620"
      ],
      "published": true,
      "apiProductName": "Hello New World"
    },
    {
      "siteId": "my-org-myportal",
      "title": "mock-product",
      "description": "Mock product",
      "specId": "apigee spec",
      "modified": "1698956849000",
      "anonAllowed": true,
      "id": "399638",
      "categoryIds": [
        "e0518597-ece2-4d7d-ba7c-d1793df0f8db"
      ],
      "published": true,
      "apiProductName": "mock-product"
    },
    {
      "siteId": "my-org-myportal",
      "title": "Hello World 2",
      "description": "Simple hello world example",
      "specId": "hello-new-world",
      "modified": "1698950207000",
      "anonAllowed": true,
      "imageUrl": "/files/book-tree.jpg?v=1698165437881",
      "id": "399668",
      "categoryIds": [
        "e0518597-ece2-4d7d-ba7c-d1793df0f8db",
        "61c1014c-89c9-40e6-be3c-69cca3505620"
      ],
      "published": true,
      "apiProductName": "Hello World 2"
    }
  ],
  "nextPageToken": ""
}

Where:

  • modified: Time the catalog item was last modified in milliseconds since epoch. For example, 1698165480000.
  • id: The ID of the catalog item. For example, 399668.

Pagination notes:

  • Page size: Use pageSize to specify the number of list items to return in one page. The default is 25, and the maximum is 100. If there are additional pages, nextPageToken is populated with a token:

    curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs?pageSize=PAGE_SIZE" \
       -H "Authorization: Bearer $(gcloud auth print-access-token)"
    

    Replace:

    • PAGE_SIZE with the number of list items to return in one page. For example, 10.

    Response payload:

    {
      "status": "success",
      "message": "one page of apidocs returned",
      "requestId": "918815495",
      "data": [
        {
          "siteId": "my-org-myportal",
          "title": "Hello New World",
          "description": "Simple hello new world example",
          "specId": "apigee",
          "modified": "1699146887000",
          "anonAllowed": true,
          "imageUrl": "/files/camper1.jpg?v=1695841491415",
          "id": "381054",
          "categoryIds": [
            "e0518597-ece2-4d7d-ba7c-d1793df0f8db",
            "61c1014c-89c9-40e6-be3c-69cca3505620"
          ],
          "published": true,
          "apiProductName": "Hello New World"
        }
      ],
      "nextPageToken": "7zcqrin9l6xhi4nbrb9"
    }
    
  • Page token:

    Use pageToken to retrieve subsequent pages when there are more than one:

    curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs?pageSize=PAGE_SIZE&pageToken=PAGE_TOKEN" \
          -H "Authorization: Bearer $(gcloud auth print-access-token)"
    

    Replace:

    • PAGE_SIZE with the number of list items to return in one page. For example, 10.
    • PAGE_TOKEN with the nextPageToken value. For example, 7zcqrin9l6xhi4nbrb9.

Add an API

To add an API to your portal:

Console

  1. Access the API catalog.
  2. Click the APIs tab, if not already selected.
  3. Click Add.

    The Add an API product to the catalog dialog displays.

  4. Select the API product that you want to add to your portal.

  5. Click Next. The API details page displays.

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

    Field Description
    Published Select Published to publish the API to your portal. Clear the checkbox if you are not ready to publish the API. You can change the setting later, as described in Publish or unpublish an API.
    Display title Update the title of your API that is displayed in the catalog. By default, the API product name is used. You can change the display title later, as described in Edit the display title and description.
    Display description Update the description of your API that is displayed in the catalog. By default, the API product description is used. You can change the display description later, as described in Edit the display title and description.
    Require developers to specify a callback URL Enable if 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.
    API documentation

    To use an OpenAPI document:

    1. Select OpenAPI document.
    2. Click Select Document.
    3. Perform one of the following steps:
      • Click the Upload File tab and upload a file.
      • Click the Import from a URL tab and import a spec by providing a name and URL from which to import.
    4. Click Select.

    To use a GraphQL schema:

    1. Select GraphQL Schema.
    2. Click Select Document.
    3. Navigate to and select the GraphQL schema.
    4. Click Select.

    Alternatively, you can select No documentation and add one later after the API has been added, as described in Manage the API documentation.

    Visibility

    If you have not enrolled in the beta release of the audience management feature, 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.

    If you have enrolled in the beta release of the audience management feature, 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.

    Display image To display an image on the API card on the APIs page, click Select image. In the Select image dialog, select an existing image, upload a new image, or provide the URL of an external image, and click Select. Preview the API thumbnail and click Select. You can add an image later, as described in Manage the image for an API card. When specifying the URL of an external image, the image won't be uploaded to your assets; additionally, loading of the image in the integrated portal will be subject to its availability, which may be blocked or restricted by content security policies.
    Categories

    Add the categories that the API will be tagged with to enable app developers to discover related APIs on the APIs page. To identify a category:

    • Select a category from the drop-down list.
    • Add a new category by typing its name and pressing Enter. The new category is added to the Categories page and made available when adding or editing other APIs.

  7. Click Save.

curl

To add an API to your portal using organizations.sites.apidocs.create:

curl -X POST "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs" \
         -H "Authorization: Bearer $(gcloud auth print-access-token)" \
         -H "Content-Type: application/json" \
         -d '{
            "title": "TITLE",
            "description": "DESCRIPTION",
            "anonAllowed": ANON_TRUE_OR_FALSE,
            "imageUrl": "IMAGE_URL",
            "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE,
            "categoryIds": [
              "CATEGORY_ID1",
              "CATEGORY_ID2"
            ],
            "published": PUBLISHED_TRUE_OR_FALSE,
            "apiProductName": "API_PRODUCT",
         }'

Replace the following:

  • ORG_NAME with the name of the organization. For example, my-org.
  • SITE_ID with the name of the portal, in the form ORG_NAME-PORTAL_NAME, where ORG_NAME is the name of the organization and PORTAL_NAME is the portal name converted to all lowercase and with spaces and dashes removed. For example, my-org-myportal.
  • TITLE with the display title. For example, Hello World 2.
  • DESCRIPTION with the display description. For example, Simple hello world example.
  • ANON_TRUE_OR_FALSE with true or false (default), where true enables anonymous user access. This setting is ignored if you have enrolled in the beta release of the audience management feature.
  • IMAGE_URL with the URL of an external image used for the catalog item, or a file path for image files stored in the portal, for example, /files/book-tree.jpg. When specifying the URL of an external image, the image won't be uploaded to your assets; additionally,loading of the image in the integrated portal will be subject to its availability, which may be blocked or restricted by content security policies.
  • CALLBACK_TRUE_OR_FALSE with true or false (default), where true requires a portal user to input a URL when managing the app.
  • CATEGORY_ID with the ID of the category. For example, bf6505eb-2a0f-47af-a00a-ded40ac72960. Separate multiple category IDs with a comma. Get the category ID with the list API categories command.

  • PUBLISHED_TRUE_OR_FALSE with true or false (default), where true indicates the API is publicly available.

  • API_PRODUCT with the name of the API product. For example, Hello World 2.

Response payload:

{
  "status": "success",
  "message": "API created",
  "requestId": "1662161889",
  "data": {
    "siteId": "my-org-myportal",
    "title": "Hello World 2",
    "description": "Simple hello world example",
    "modified": "1698948807000",
    "anonAllowed": true,
    "imageUrl": "/files/book-tree.jpg",
    "id": "409405",
    "requireCallbackUrl": true,
    "categoryIds": [
      "88fbfd1d-9300-49f7-bfc2-531ade4c63d4",
      "630c4cf9-109a-48b0-98cc-ef4c12ae4474"
    ],
    "published": true,
    "apiProductName": "Hello World 2"
  }
}

Where:

  • modified: Time the catalog item was last modified in milliseconds since epoch. For example, 1698165480000.
  • id: The ID of the catalog item. For example, 399668.

Edit an API

Once you have added an API, use the console or an API call to make edits.

This section provides a detailed example of the steps to take to modify an existing API in your portal.

Refer to subsequent sections for specific modification settings.

Console

  1. Access the API catalog.
  2. Click the APIs tab, if not already selected.
  3. Click in the row of the API that you want to edit.
  4. Click Edit.
  5. Under API details, make any modifications. See descriptions of the options in Add an API.
  6. Click Save.

curl

Once you have added an API, use the organizations.sites.apidocs.update call to make edits.

This example walks you through the steps required to change the published status of your API in your portal from true to false. You can change more than one setting in one API call if necessary.

  1. Get a list of the APIs in your portal using organizations.sites.apidocs/list in order to locate the generated id that uniquely identifies each API:

    curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs" \
        -H "Authorization: Bearer $(gcloud auth print-access-token)"
    

    Replace the following:

    • ORG_NAME with the name of the organization. For example, my-org.
    • SITE_ID with the name of the portal, in the form ORG_NAME-PORTAL_NAME, where ORG_NAME is the name of the organization and PORTAL_NAME is the portal name converted to all lowercase and with spaces and dashes removed. For example, my-org-myportal.

    Response payload:

    {
      "status": "success",
      "message": "one page of apidocs returned",
      "requestId": "1167960478",
      "data": [
        {
          "siteId": "my-org-myportal",
          "title": "Hello New World",
          "description": "Simple hello new world example",
          "specId": "hellowworld",
          "modified": "1695841621000",
          "anonAllowed": true,
          "imageUrl": "/files/camper1.jpg?v=1695841491415",
          "id": "381054",
          "categoryIds": [
            "e0518597-ece2-4d7d-ba7c-d1793df0f8db",
            "61c1014c-89c9-40e6-be3c-69cca3505620"
          ],
          "published": true,
          "apiProductName": "Hello New World"
        },
        {
          "siteId": "my-org-myportal",
          "title": "mock-product",
          "description": "Mock product",
          "specId": "apigee spec",
          "modified": "1698956849000",
          "anonAllowed": true,
          "id": "399638",
          "categoryIds": [
            "e0518597-ece2-4d7d-ba7c-d1793df0f8db"
          ],
          "published": true,
          "apiProductName": "mock-product"
        },
        {
          "siteId": "my-org-myportal",
          "title": "Hello World 2",
          "description": "Simple hello world example",
          "specId": "hello-new-world",
          "modified": "1698950207000",
          "anonAllowed": true,
          "imageUrl": "/files/book-tree.jpg?v=1698165437881",
          "id": "399668",
          "categoryIds": [
            "e0518597-ece2-4d7d-ba7c-d1793df0f8db",
            "61c1014c-89c9-40e6-be3c-69cca3505620"
          ],
          "published": true,
          "apiProductName": "Hello World 2"
        }
      ]
    }

    Where:

    • modified: Time the catalog item was last modified in milliseconds since epoch. For example, 1698165480000.
    • id: The ID of the catalog item. For example, 399668.
  2. Use the organizations.sites.apidocs.get call to return the current values for a specific API:

    curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
        -H "Authorization: Bearer $(gcloud auth print-access-token)"
    

    Replace the following:

    • ORG_NAME with the name of the organization. For example, my-org.
    • SITE_ID with the name of the portal, in the form ORG_NAME-PORTAL_NAME, where ORG_NAME is the name of the organization and PORTAL_NAME is the portal name converted to all lowercase and with spaces and dashes removed. For example, my-org-myportal.
    • API_DOC with the generated id of the document. For example, 399668. Use the list API docs command to find this value.

    Response payload:

    {
      "status": "success",
      "message": "apidoc returned",
      "requestId": "2072952505",
      "data": {
        "siteId": "my-org-myportal",
        "title": "Hello World 2",
        "description": "Simple hello world example",
        "specId": "hello-new-world",
        "modified": "1698950207000",
        "anonAllowed": true,
        "imageUrl": "/files/book-tree.jpg?v=1698165437881",
        "id": "399668",
        "categoryIds": [
          "e0518597-ece2-4d7d-ba7c-d1793df0f8db",
          "61c1014c-89c9-40e6-be3c-69cca3505620"
        ],
        "published": true,
        "apiProductName": "Hello World 2"
      }
    }
  3. Include the mutable values you want to keep in the organizations.sites.apidocs.update call, and modify the values you want to change. If you omit a line, the default setting is used. For this example, change the published setting from true to false:

    curl -X PUT "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
         -H "Authorization: Bearer $(gcloud auth print-access-token)" \
         -H "Content-Type: application/json" \
         -d '{
            "title": "TITLE",
            "description": "DESCRIPTION",
            "anonAllowed": ANON_TRUE_OR_FALSE,
            "imageUrl": "IMAGE_URL",
            "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE,
            "categoryIds": [
              "CATEGORY_ID1",
              "CATEGORY_ID2"
            ],
            "published": false,
            "apiProductName": "API_PRODUCT",
         }'
    

    Replace the following:

    • TITLE with the display title. For example, Hello World 2.
    • DESCRIPTION with the display description. For example, Simple hello world example.
    • ANON_TRUE_OR_FALSE with true or false (default), where true enables anonymous user access. This setting is ignored if you have enrolled in the beta release of the audience management feature.
    • IMAGE_URL with the URL of an external image used for the catalog item, or a file path for image files stored in the portal, for example, /files/book-tree.jpg. When specifying the URL of an external image, the image won't be uploaded to your assets; additionally,loading of the image in the integrated portal will be subject to its availability, which may be blocked or restricted by content security policies.
    • CALLBACK_TRUE_OR_FALSE with true or false (default), where true requires a portal user to input a URL when managing the app.
    • CATEGORY_ID with the ID of the category. For example, bf6505eb-2a0f-47af-a00a-ded40ac72960. Separate multiple category IDs with a comma. Get the category ID with the list API categories command.
    • API_PRODUCT with the name of the API product. For example, Hello World 2.

    Response payload:

    {
      "status": "success",
      "message": "ApiDoc updated",
      "requestId": "197181831",
      "data": {
        "siteId": "my-org-myportal",
        "title": "Hello World 2",
        "description": "Simple hello world example.",
        "modified": "1698884328000",
        "anonAllowed": true,
        "imageUrl": "/files/book-tree.jpg",
        "id": "408567",
        "requireCallbackUrl": true,
        "categoryIds": [
          "88fbfd1d-9300-49f7-bfc2-531ade4c63d4",
          "630c4cf9-109a-48b0-98cc-ef4c12ae4474"
        ],
        "published": PUBLISHED_TRUE_OR_FALSE,
        "apiProductName": "Hello World 2"
      }
    }
    

Publish or unpublish an API

Publishing is the process of making your APIs available to app developers for consumption.

To publish or unpublish an API on your portal:

Console

  1. Access the API catalog.
  2. Click the APIs tab, if not already selected.
  3. Click in the row of the API that you want to edit.