Contact Free trial Login

Publish an API Specification

When you want to share your API specification with other developers, you can publish it to Anypoint Exchange. Exchange creates a page that presents the project for anyone in your business group to view and download the project from.

The page that Exchange creates for a published project includes a left pane for viewing the specification’s documentation, a middle pane for viewing a description of the specification, and a right pane for viewing metadata about the specification.

An example page for a specification published in Exchange

1 The left pane, which you can navigate to view the documentation. The navigation is generated from the documentation in the specification.
2 The middle pane, which describes the specification. You write the description in Exchange after publishing the specification.
3 The right pane, which displays metadata about the specification.

Before You Begin

It is a good practice to remove unreferenced files before publishing a project to Anypoint Exchange. An unreferenced file is a file that is not referenced either directly or indirectly from the project’s root file.

For example, suppose that the file example.raml is among the files in a project. If the root file of the project does not reference the file with any !include tag, then the root file doesn’t reference the file directly. Also, if no file, in a chain of references from the root file, itself references example.raml, then example.raml is not referenced indirectly from the root file. Therefore, example.raml is unreferenced and should probably not be among the files in your project.

Procedure

  1. Open the API-specification project that you want to publish, if it is not already open.

  2. In the top-right corner of API Designer, click Publish and then click Publish to Exchange.

    Result: This dialog is opened.

    apid publish dialog api specs

    1 Asset version: The version number to be displayed in the Version section of the page that Anypoint Exchange creates for the project.
    2 API version: The version number of the API specification. For a description of this field, see the "Filling in the API version Field" section.
    3 Business group ID: The ID of the business unit in Anypoint Platform to which the project belongs. You should keep the value as it is, except in unusual cases.
    4 Asset name: The name that Anypoint Exchange uses to identify the published project. You should keep the value as is, except in unusual cases.
    5 Asset ID: The ID that Anypoint Exchange uses to identify the published project. You should keep the value as is, except in unusual cases.
    6 Add to API Manager: Specifies that you want to publish the API specification to an API portal. When you click Publish to Exchange, API Designer also publishes the specification to API Manager, where the specification is listed in the API Administration section.
  3. After completing the required fields, click Publish to Exchange.

    If your project includes files that are not referenced by the root file either directly or indirectly, a dialog asks you to confirm that you do want to publish the project together with those unreferenced files. By default, API Designer excludes them from the published project in Anypoint Exchange.

Filling in the API version Field

The appearance of the API version field depends upon several factors:

  • Anypoint Exchange requires that each API specification published to it have a version number.

  • API Manager requires that API specifications provide a version number.

  • In specifications written in OAS, the version field is required.

  • In specifications written in RAML, the version node is optional.

The following flowchart shows how API Designer decides whether to disable or enable the API version field and whether to populate it with a number:

The appearance of the API version field depends on the outcome of the checks that API Designer makes when you want to publish an API specification.

Flowchart for the checks that API Designer makes

1 API Designer checks whether the version number for the API specification is provided within the specification. If the version number is provided, then the API version field is populated with the number and disabled, so that you cannot change the number. If the specification does not provide the version number, then API Designer moves to the next check.
2 API Designer checks whether the checkbox Add to API Manager is selected. If the checkbox is selected, then API Designer prevents you from proceeding because API Manager requires that the specification provide the version number. If the checkbox is not selected, then API Designer moves to the last check.
3 API Designer checks whether the specification is being published to Anypoint Exchange for the first time. If the specification is being published for the first time, then API Designer enables the API version field and suggests a version number because a number is not provided in the specification. If the specification is not being published for the first time, then API Designer enables the API version field and populates the field with the number used when the specification was last published. You can change the number.

Was this article helpful?

💙 Thanks for your feedback!

Edit on GitHub