Publishing an API

The user interface provides an option that adds an API to a Product and publishes the Product in a Catalog. Publishing a draft Product makes the APIs in that Product visible on the Developer Portal for use by application developers. The syndication feature in IBM® API Connect means that if Spaces are enabled for a Catalog, Products can be published only to a Space within that Catalog.

Before you begin

Ensure that you have a Catalog to stage to in the API Manager or API Designer user interfaces (UI). For more information, see Creating and configuring Catalogs.

Ensure that the Catalog has at least one gateway service configured.

Note: All references in this topic to a Catalog can also be applied to Spaces in a Catalog, unless specified otherwise. For more information about Spaces, see Using syndication in IBM API Connect®.

To complete the Product management tasks that are described in this topic, you must either be the owner of the API provider organization, or be assigned Product > Manage permission for the target Catalog or Space. For information on configuring Product management permissions for a Catalog or Space, see Creating and configuring Catalogs or Managing user access in a Space.

About this task

You can complete this task either by using the API Designer UI application, or by using the browser-based API Manager UI. Publishing is not available when working offline in API Designer.

Validation of the API definition file occurs during the staging or publishing process. The following validation occurs:
  • Validation against the OpenAPI schema by using the API Dev Tools Swagger Parser (https://www.npmjs.com/package/@apidevtools/swagger-parser).
  • Validation against IBM extension properties.
  • Semantic validation, which includes the following types of validation:
    • Ensuring that if an OpenAPI is enforced by an API Connect Gateway, then the scheme must be HTTPS, or the parameter name for an API key security scheme in the header must be either X-IBM-Client-Id or X-IBM-Client-Secret.
    • Ensuring that if the OpenAPI is not enforced by an API Connect Gateway, then a host must be provided.
    • De-referencing of local references in the definition file (that is, values of $ref properties), and ensuring these are valid JSON Pointers within the file.
Note: Products that contain an API with a Swagger property using regex that include lookahead assertions, such as "(?" cannot be validated or published. An error message is returned. For example: 
Product has not been published!
The multipart 'openapi' field contains an OpenAPI definition with validation errors.
    definitions.properties.pattern Does not match format 'regex' (context: (root).definitions.properties.pattern, line: 0, col: 0)
400
Note: If the OpenAPI file that defines your API uses a $ref field to reference a fragment of OpenAPI code that is defined in a separate file, the $ref field is replaced with the contents of the target file before the product that contains the API is staged or published (the $ref field is supported only if you are using the API Connect for IBM Cloud developer toolkit). For more information, see Using $ref to reuse code fragments in your OpenAPI files.

Procedure

  1. In the navigation pane, click Develop icon in the navigation pane Develop, then select the APIs tab.
    The Develop page opens.
  2. Optional: If you have accounts on multiple provider organizations, you can select a new provider organization for staging and publishing from the Organization menu.
  3. You can publish an API either from the Develop listing page, or from within the API definition itself.
    1. To publish an API from the Develop listing page, click the options menu icon options icon alongside the required API, and then select Publish.
    2. To publish an API from withing the API definition, complete the following steps:
      1. Click the title of the API that you want to work with.
      2. Click the options menu icon:
        Screen capture highlighting the options menu icon
      3. Click Publish.
  4. Choose one of the following actions:
    • To publish the API by adding it to a new Product:
      1. Select New Product - Publish using a new product.
      2. When prompted, enter a Title and Version.
      3. The Product Name is automatically entered. The Name is the used to refer to the product in CLI commands. See apic products.
      4. Click Next.
    • To publish the API by adding it to an existing Product:
      1. Select Existing Product - Publish using an existing product
      2. Select the Product you want to use.
      3. Click Next.
  5. Select the Catalog to which you want to publish the Product.
  6. If Spaces have been enabled in the selected Catalog, select the Space that you require.
    Note: The Catalogs that you can select from are those that are defined for the management server and provider organization that you are connected to.

    If you are using the API Manager user interface, the connection details are determined by the API Manager URL that you open, and the user ID with which you log in. If you are using the API Designer user interface, you provide the management server details and user ID in the login window that opens when you first launch API Designer; see Logging into API Connect Designer.

    For details of how to create a Catalog in a provider organization, see Creating and configuring Catalogs.

  7. If you want to publish the Product only to selected gateway services, select Publish to specific gateway services, then select the required gateway services. Only the gateway services whose type matches the gateway type setting for the Product are listed. For information on gateway types, see API Connect gateway types.
  8. Click Publish.

Results

Your Product is published to a Catalog. You can view the state of the Product in the Catalog in API Manager. If you published the product from API Designer, ensure you are logged into API Manager with the same user name and password that you used for API Designer. Click Manage icon in the API Manager UI navigation pane Manage in the API Manager UI, then select the required Catalog. The Product is shown with a state of Published.

For information about the lifecycle of a product, see The Product lifecycle.

If approval is required to publish Products in the Catalog, a publish approval request is sent, and the Product moves to the Pending state; the Product is published in the Catalog when the request is approved. If approval is not required, the Product is published immediately.

Note: If approval is required to stage Products to the Catalog, a stage approval request is sent. When the request is approved, the Product moves to the staged state and must be separately published in the Catalog. For information on publishing a staged Product in a Catalog, see Publishing a Product.

For information on configuring Product lifecycle approvals for a Catalog, see Creating and configuring Catalogs. For information on approving requests, see Approving Product lifecycle and subscription requests.

If the Product contains no Plans, a Plan called Default Plan is added automatically to the Product in the Catalog.

Notes:
  • If an OpenAPI 3 API contains a response wildcard (which is not supported), publishing is disabled for that API. You must correct the problem before you can publish the API.
  • If the Product contains an API that includes a user-defined policy that has not been imported into this Catalog, the publish will fail. The user-defined policy must be available in the required Catalog for the Product to be published successfully. For detailed instructions on how to import a user-defined policy into a Catalog, see Importing a user-defined policy into a Catalog.