Assign versions to APIs

Consider whether you need to assign a version to your APIs. Assigning versions is necessary only if there are any breaking changes.

zosConnect-2.0 Applies to zosConnect-2.0.

For minor changes that do not break existing users, you can update the operations in place and use the version field in the API editor to track these minor version increments. For example, an operation can be added to an API or an optional field can be added to a schema without breaking the existing usage of an API.

Each API name, service name, and base path name must be unique within a server.

If you decide that you do need to assign versions to your APIs, there are several methods available. The following examples show two methods that use the path.

Base path versions

You can assign versions at the API level by using the base path. This method requires a separate API project for each version but has the advantage of producing separate Swagger documents, one for each version. This method creates a simpler view when there are several versions and the changes to different versions are isolated from each other. This method also reduces the risk of regressions and the degree of testing that is required for any one change. For example,

My API Project V1 (basepath= /v1/myapi):
/v1/myapi/customers
/v1/myapi/accounts

My API Project V2 (basepath= /v2/myapi):
/v2/myapi/customers
/v2/myapi/accounts

Path versions

You can assign a version at the resource level by using the path. With this method, you have multiple versions of a resource and all versions of each resource are kept in the same API project. This method is more appropriate if changes between versions are small or infrequent, meaning that there is little justification for maintaining separate API projects and Swagger documents. For example,

My API Project (basepath= /myapi):
GET /myapi/customers this might call service getCustomers
GET /myapi/customers/v2 this might call service getCustomersV2
GET /myapi/customers/v3 this might call service getCustomersV3
PUT /myapi/accounts this might call service updateAccounts

You do not need to assign a version number to your first version. If you need to add versions, you can start with V1 or, as in the above example, V2. Use the Version field to record minor non-breaking changes to the existing versions of APIs or services.

Note: You cannot deploy more than one API or service that differs only by the value of the Version field in the API toolkit. This field is only a description field and does not enable API or service versioning.