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

OMCe tracks a custom API as it's created, saved, published, implemented, deactivated, and reactivated. Custom APIs can be published independently or when a related backend is published.

Scope and Version Format

Both custom APIs and API implementations have versions that use the format Major.minor.

Active Versions

Though there can be multiple active versions of an API implementation, a single implementation is mapped to a specific API version.

Draft and Published States

Both custom APIs and API implementation can have a Draft state or a Published state.

• A custom API can be published independently or published when a related backend is published.

• An API implementation can be published independently.

Actions Tracked by OMCe

The following operations are tracked for custom APIs: Create, Update, Publish, and Move to Trash.

The following operations are tracked for API implementations: Create and Save.

Backend References

A backend can reference multiple APIs, but a backend can only reference one version of a specific API. For example, a backend can reference both myAPI1.1 and yourAPI2.0, but it can’t reference both myAPI1.1 and myAPI2.0.

API implementations aren’t referenced directly by a backend. The implementation is referenced by the API, which is in turn referenced by the backend.

Dependencies

A custom API is dependent on its active API implementation (as determined by the policy). In other words, an API implementation is a dependency of any APIs that list it as the active or default implementation.

An API implementation is dependent on the API that it implements and any other APIs called by the custom code (as listed in the file manifest).

Backends are also dependencies of associated custom APIs.

Policy Attributes

A custom API is affected by the API version to implementation policy mapping and the default API version setting.

An API implementation is affected by the number of node instances per virtual machine and standard runtime policies such as read-only, log-levels, etc.

For detailed descriptions of policies and their values, see Oracle Mobile Cloud Enterprise Policies.

Publishing 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.

Note:

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.

Note:

Custom APIs can be published independently of implementations. When you publish an API, the implementation isn’t published automatically. To understand the relationship between custom APIs and their implementations, see Custom APIs and API Implementations.

Updating 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 Mobile Apps > 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.

Creating 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 Mobile Apps > 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.

   OMCe 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.

Moving 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 Mobile Apps > 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.

To find out how dependencies can affect moving an artifact to the trash, see Moving an API Implementation to the Trash.

Restoring a Custom API

1. Click and select Mobile Apps > 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. To restore an artifact when a duplicate artifact exists, see Restoring an Artifact.

Managing 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 Mobile Apps > 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.