Publishing an API

Last modified on April 13, 2021

When you feel your API definition is ready for production use, you can publish it. Publishing is a way to show that the API is in a stable state and its endpoints can be reliably called from other applications.

Publishing makes the API definition read-only, so any changes you make after that point should be saved as a new version of the API. Collaborators will not be able to edit the published version either.

Difference between published and unpublished APIs

The difference is mostly semantic:

  • An unpublished API definition is a draft, a work in progress. Every API in SwaggerHub starts as unpublished. Though unpublished APIs are listed in the SwaggerHub registry, they are not ready for API consumers.

  • A published API definition is a stable version ready for consuming from client applications. It is not supposed to be changed, and any changes will be introduced as a new version of the API.

Technically, the difference is that published API versions cannot be edited (unless you unpublish them). If you want to change something, you should create a new version of the API and make changes in it.

SwaggerHub shows the Published label next to published APIs and domains. People searching SwaggerHub can also filter the list to show only published APIs.

Published APIs

Click the image to enlarge it.

Published/unpublished vs public/private

Published and unpublished are not the same as public and private. Public and private indicate who can see the API in SwaggerHub -- everyone or just the selected collaborators. Published and unpublished indicate production readiness – whether the API is ready for consumption or not.

Publish an API version

The API owner and collaborators with the Editor role can publish API versions.

  1. Go to the API page in SwaggerHub.

  2. If the API has several versions, select the version you want to publish.

    Selecting an API version
  3. Open the version list and click  Publish Version.

  4. (Optional.) Select Set as default version to make this version the default version of your API.

    Publishing an API
  5. Click Publish Version.

Once published, the API version becomes read-only and cannot be edited. If you need to add new endpoints, change parameters, and so on, you should create a new version of your API and make the changes there. However, if you need to make some important changes to a published API, you can unpublish it temporarily.

Note: All collaborators receive an email notification when an API is published or unpublished.

Unpublish an API version

If you change your mind and want to pull the API definition back to make some changes, you can unpublish the API. To do this, you must be the API owner or a collaborator with the Editor role.

  1. Open the API in the SwaggerHub Editor.

  2. If the API has several versions, switch to the version you want to unpublish.

    Selecting an API version
  3. Open the version list and click  Unpublish Version.

  4. In the dialog, click Unpublish Version.

This API version can now be edited again.

Publish and unpublish via CLI

Use SwaggerHub CLI to publish and unpublish your APIs from the command line.

To publish:

swaggerhub api:publish OWNER/API_NAME/VERSION

Alternatively, you can use the --publish option of api:create and api:update:

swaggerhub api:update OWNER/API_NAME/VERSION --file myapi.yaml --publish

To unpublish:

swaggerhub api:unpublish OWNER/API_NAME/VERSION

What’s next

Once you have published your API, you can:

See Also

Creating a New API
Public and Private APIs
Sharing APIs
Versioning
Custom Branding for API Documentation

Watch the video
 
Highlight search results