7 API Lifecycle

The lifecycle stages of custom APIs and API implementations are similar. Both artifacts go through a design-time phase where each is created, tested, edited, and then published.

When you create a new custom API, its version is automatically set to 1.0 and it’s considered to be in a Draft state. You can test and edit your draft API as often as needed. As you develop your API, you can change the version's major and minor values as you see fit, that is, creating a new version of your API or updating an existing version.

After you've implemented and tested your API, and you’re satisfied with your API configuration, you can publish it with the understanding that a published API can’t be changed. To make a change to a published API, create a new version of the API. APIs are implemented with custom code. For custom APIs, you'll also need to create a new implementation for the new version.

You can export a draft or published API for use in other instances. Eventually, the API may become obsolete, and you can move it to the trash.

If you want a general introduction to how artifacts interrelate in the overall lifecycle before exploring the lifecycle of APIs, see Understanding Lifecycles.

Custom APIs and API Implementations

Publish a Custom API

As soon as an API is published, it can’t be changed. You can create a new version of it, but you cannot edit it.

You must have an implementation associated with the API to publish it. A mock implementation is provided by default. To associate an implementation other than the mock implementation, open the API, and click Implementations in the left navigation bar. Select the implementation you want and click Set as Default.

1. Click and select Applications > APIs from the side menu.
2. Select the draft API that you want to publish.
3. Click Publish.

   You can enter a justification for publishing in the Comment field.

When the API is published, you’re returned to the APIs page where you can see the updated status of your API.

Custom APIs can be published independently of implementations. When you publish an API, the implementation isn’t published automatically.

Update the Version Number of an API

If you created a new version of an API using the New Version dialog, you can update the version number of the API if it’s still in a Draft state. This is particularly useful if you need to designate a different version number for it before you publish the API.

1. Click and select Development > APIs from the side menu.
2. Select the API you want.
3. Select More > Update Version Number.
4. Enter a version number of the format Major.minor.

   The previous version of the API is displayed next to the field. You'll get a message letting you know if you enter an existing version number.

5. (Optional) Add a brief description that states what distinguishes this version from the previous one.
6. Click Update.

   A confirmation message is displayed. A draft of the new version is added to the list of APIs.

Create a New Version of an API

You can make a new version of a custom API regardless of whether it’s in a Draft or Published state. When you create a new version of a custom API, you are basically cloning the API configuration and making changes to it alone. You can specify the implementation to associate with the new version of the API. You can upgrade your custom API easily by creating a new version of it:

1. Click and select Development > APIs from the side menu.
2. Select the API.
   You can create a new version of a custom API whether it’s in a Draft or Published state.
3. In the right section, select More > New Version.

   Mobile Hub checks for any dependencies on other APIs and for an associated implementation.

4. Enter a version number in the format Major.minor.

   If you enter a version number that already exists, you'll get a message letting you know that number is already in use.

5. (Optional) Add a brief description that states what distinguishes this version from the previous one.
6. Click Create.

   A confirmation message is displayed. A draft of the new version is created and is visible in the API Catalog.

Move a Custom API to the Trash

Remove a custom API by moving it to the trash. If the API is needed later, you can restore it from the trash.

1. Click and select Development > APIs from the side menu.
2. Select the custom API you want to remove.
3. In the right section, select More > Move to Trash.
4. Click Trash in the confirmation dialog if there are no dependency issues.

   If you think you or someone else might restore it later on, enter a brief comment about why you're putting this item in the trash.

Restore a Custom API

1. Click and select Development > APIs from the side menu.
2. Click Trash ().
3. Make sure APIs is selected in the trash drawer.
4. In the list of items in the trash, click by the API you want and select Restore from Trash.
5. Click Restore in the confirmation dialog if there are no conflicts.

When you restore an API, its implementations are not restored with it. You’ll have to manually restore the implementations you want and designate an implementation as the default. Open the restored API, click Implementations from the navbar, and set an implementation as the default.

Restoring an artifact can cause conflicts if a duplicate artifact already exists.

Manage an API

After you create a custom API, you’ll want to edit it, publish it, see what implementations are associated with it, in short, you want to be able to manage the API and examine details of the APIs created by other service developers. The APIs page gives you access to all these features.

When at least one custom API exists, you’ll be taken to the APIs page every time you click and select Development > APIs from the side menu. On the left side of the page, you’ll see a list of all the custom APIs except for those in the trash. You can see which APIs are in the Draft state and which are in the Published state. Every API is listed by its name and version number.

The right side of the page is where you can open, test, publish, and examine data about your custom API.

On the upper right side of the APIs page, you can perform the following actions:

• Click Open to view details and settings for the selected custom API.

• Click More to create a new version, update an existing version, or move an API to the trash.

• Expand Implementations to see what implementations are available, along with their version numbers and whether they are in a Draft or Published state. Click Manage to go directly to the Implementations page.

On the lower right side of the page, you view data about the selected API:

Description of the illustration api_manage_history.png

• Expand Used By to see the list of the backends that call on the API.

  Click All Usages to see the complete list.

• Expand the History section to quickly see the latest activity for the selected custom API.