API Namespaces

The API building format used is closely related to the OpenAPI specification for REST APIs.

The user can define various endpoints (paths) for a REST API, operations (GET, POST, PUT, DELETE) for each of these endpoints, as well as the operation parameters, request bodies, responses, and contained schemas of various types. In general, it holds all necessary information to describe an API using OpenAPI for external consumers.

The API Version is used to manage the changes of the API. The older implementation of IBM Industry Solutions Workbench (versions 2.9 and prior) had the default API Version as 1.0.0 which is now configurable by the user. This will help the consumers of the REST APIs be aware of the changes. There is no change in the url of the REST APIs. For any kind of breaking changes in the contract, not only the API Version should have a major change (e.g., 1.2.0 to 2.0.0) but a new API Namespace representing a different API should also be created so the consumers of the APIs have the flexibility of upgrading to the latest APIs only if they are ready.

Note:

IBM Industry Solutions Workbench lets you create one or more separate REST APIs within a single service project. Each REST API is represented by its own API Namespace in Solution Designer and has its own API specification.

Create an API Namespace

To create an API Namespace, use the Create capability in the left navigation bar.

This process is separated into the following 3 steps where you have to provide different information:

  1. General Information: Internal information on the API Namespace
  2. API Information: Public information on the API
  3. Build Information: API integration settings

General Information

An API Namespace is defined by the following master data which will only be used internally:

  • Prefix: The prefix of the API Namespace (must be unique within a project). Please note that only the characters a-z (without special characters) and digits can be used within a prefix. Furthermore, prefixes may not begin with a digit and the first character must be lowercase. A prefix can not consist more than 6 characters. This field is mandatory.
  • Label: This is a meaningful title of the API Namespace. This field is mandatory.
  • Description: This is the description of the API Namespace and its life cycle. This field is optional.
Warning:

At this point, you have to choose, whether you want to create an API from scratch or create an API Namespace based on an existing API specification.

Create an API from scratch

After selecting and confirming the from scratch option you have to provide the following information about the API:

API information

The API information is the public information for this API and will be visible in the API specification file.

  • API Title: Title of the API (mandatory)
  • API Description: Description of the API (optional)
  • API Version: Version of the API. The API Version is used to transparently manage the changes in the API. It helps to communicate the changes with the consumers. It will be reflected in the swagger of the API. It follows Semantic Versioning 2.0.0. (mandatory)
  • Host: Base URL for API calls. The host of the server is only a placeholder and will be substituted depending on the deployment. The base path is pre-filled with the prefix of the API Namespace (mandatory)
  • Contact E-mail: Contact E-mail of the API. A valid E-mail must be provided (optional)
  • Contact Name: Contact name of the API (optional)
  • Contact URL: Contact URL of the API (optional)
  • License Name: License name of the API (optional)
  • License URL: License URL of the API. A valid URL must be provided (optional)
  • Terms of Service URL: Terms of service URL of the API. A valid URL must be provided (optional)

Build information

By proceeding with Next you can select the format for the API specification (OpenApi 3.0 or Swagger 2.0) that will be generated. Based on the selected format you have some options for integrations with this API.

IBM Business Automation Workflow

If selected, it will add additional integration artifacts that are automatically produced during the build process of the project. This means, you will be able to download a toolkit file via Solution Envoy which you can then import into IBM Business Automation Workflow.

Note:

IBM Business Automation Workflow can only be enabled when Swagger 2.0 is selected.

The toolkit will contain the following functionality:

  • For each API operation of the API namespace, a service flow item is existing using the operationId as a name
  • The service flow provides functionality to invoke the Rest call against the API Operation
  • Parameters and Request body of the API operations are provided as input variables
  • Responses of the API operations are provided as output variable

Additionally, the following input variables are available for the service flow:

  • requestTimeout (Integer): The time in milliseconds to wait until the request will timeout. If not set, the default timeout from the server will be applied.
  • responseTimeout (Integer): The time in milliseconds to wait until the response will timeout. If not set, the default timeout from the server will be applied.

After importing the toolkit, you can make use of the provided service flows in other toolkits or process applications.

To do this, it is necessary to provide some configuration for the connection to the Rest API, defined by the following environment variables:

  • projectAcronym_apiNamespace_ENDPOINT_ADDRESS (e.g. ORDERS_ORDERAPI_ENDPOINT_ADDRESS): Provide the full URL of the deployed API in the service against which the Rest calls should be invoked (e.g. https://my-url/orders/api/orderapi)
  • projectAcronym_apiNamespace_SSL_CONFIGURATION (e.g. ORDERS_ORDERAPI_SSL_CONFIGURATION) optional: The name of the SSL configuration to use.If not set, the default configuration from the server will be applied.
Note:

You can also modify the toolkit after importing it. Please consider that in this case, your changes will be overwritten by an import of any new version of the toolkit.

IBM API Connect

IBM API Connect can be enabled for both OpenApi 3.0 and Swagger 2.0. Once you enable this feature, some metadata about the API has to be provided.

  • IBM Name: The display name within IBM API Connect (x-ibm-name) (mandatory)
  • Phase: The phase of development the API is in. It can only take one of the following values (mandatory):
    • identified
    • specified
    • realized
  • Type: Type of the API. Currently, only rest (optional) is supported
  • testable: Used to specify whether the API can be tested using the test tool in the Developer Portal. By default, it is disabled. (mandatory)
  • enforced: Used to specify if the API Connect gateway is used to enforce the API. By default, it is disabled. (mandatory)
  • cors: Used to specify whether CORS access control is used for the API. By default, it is disabled. (mandatory)
  • Additional configuration: The mandatory API Connect configurations are reflected as YAML here. All non-mandatory API Connect configurations can be added here. For more information on the configurations, please refer to the IBM API Connect documentation (optional)

Clicking on Create after that will persist the new API Namespace. You can also use the Open after creation checkbox to open the API Namespace for further editing after creating.

Create an API Namespace based on an existing API specification

When selecting the based on uploaded Open API / Swagger file option you have to provide an API specification (.yaml or .json) file and upload it. After confirming with Create the uploaded file is first checked to be a valid specification. If it's content is invalid a message is shown within the dialog.

Currently, any compliant OpenAPI 3 specification can be used for the creation of a new API Namespace. However, the Solution Designer doesn't support the modelling of all OpenAPI 3 features through the UI. If you have special use cases in your API specification, warnings will be shown after creating the API Namespace. You can view and access them through the Expert view in the API Namespace.

Note:

Even though not all features are supported in the UI, the API of the deployed service will try to apply the valid OpenAPI 3 features correctly. Please find the list of API validations here.

Warning:

If the uploaded API specification does not meet the above-mentioned expectations completely a list of notifications is shown in order to indicate what should be changed within the specification file to meet the expectations.

Warning:

OpenAPI 3 specs allow parameters to be directly attached to a path so that they are shared to all of the path's operations, however while importing path pararmeters they're transferred into all of the operations and no longer saved within the path itself.

During the import IBM Industry Solutions Workbench auto-resolves the following issues if occurring to fit to the supported structure of the design environment:

  • Component Identifier of every component is required to be capitalized and will be auto resolved to be capitalized
  • Property Name is required to start with a lowercase letter and will be auto resolved
  • content type application/json; charset=utf-8 is auto-solved to application/json
  • Path URL is required to start with a "/" which is automatically added during import
  • Path URL must not end with a "/" which is automatically removed during import
Note:

The information API Title, API Description, Host, Contact E-mail, Contact Name, Contact URL, License Name, License URL and Terms of Service URL will be taken from the uploaded API specification and can be changed afterwards. After successful creation of the API Namespace, a confirmation is shown and the created elements of the API namespaces are stated.

You can also use the Open after creation checkbox to open the API Namespace for further editing after creating.

Edit an API Namespace

Visit the API Namespace's overview page and then open General tab.

Edit the master data

By navigating to the API Namespace Details section on the right and using the Edit namespace details button, you can adjust Prefix, Label and Description. You can confirm your entry by using the Save capability.

Edit API information

On the second section on the right with the heading API Information, click the Edit API Information button.

You can only edit the following fields:

  • API Title: Title of the API (mandatory)
  • API Description: Description of the API (optional)
  • API Version: Version of the API. The API Version is used to transparently manage the changes in the API. It helps to communicate the changes with the consumers. It will be reflected in the swagger of the API. It follows Semantic Versioning 2.0.0. (mandatory)
  • Contact E-mail: Contact E-mail of the API. A valid E-mail must be provided (optional)
  • Contact Name: Contact name of the API (optional)
  • Contact URL: Contact URL of the API (optional)
  • License URL: License URL of the API. A valid URL must be provided (optional)
  • Terms of Service URL: Terms of service URL of the API. A valid URL must be provided (optional)
Warning:

You are not allowed to change the Host.

Edit build information

On the second section on the right with the heading Build Information, click the Edit build information button, you can adjust the Supported API Specification and the additional API Integrations. The edit options for IBM API Connect will be the same as enabling IBM API Connect while creating an API Namespace (see also). You can confirm your entry by using the Save capability.

Delete an API Namespace

To delete an API Namespace, use the Delete namespace button in the upper right corner of an API Namespace's overview page.

Warning:

You will be asked to confirm the action before the selected command is permanently deleted. You can only delete a namespace if artifacts that belong to the namespace are not in use.

Excursion: When to release a new API?

A version number tag indicates a certain level of backwards-compatibility that can be expected by the client, and as such, extra care should be taken to maintain this trust. The following lists show which types of changes necessitate a new version, and which don't (1):

(1) See https://developer.atlassian.com/server/framework/atlassian-sdk/atlassian-rest-api-design-guidelines-version-1/

Changes that don't require a new version:

  • New resources (under a new resource path)
  • New HTTP methods on existing resources (new commands)
  • New data formats
  • New attributes or elements on existing data types

Changes that require a new version:

  • Removed or renamed URIs
  • Different data returned for same URI
  • Removal of support for HTTP methods on existing URIs