Modelling APIs

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 FSW (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 Financial Services 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), digits and the special character "_" are permitted for 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. The prefix cannot be changed after creation. 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.

Attention: At this point, you have to choose, whether you want to create an API from scratch or create an API 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 Process Designer.

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

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.

Create an API 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, the following content is supported to be imported to the new API namespace:

  • General validations:

    • no duplicated items (is valid in OpenApi 3.0/Swagger 2.0 with lower- and upper-cased)

    • valid Contact E-mail

    • valid Contact URL

    • valid License URL

    • valid Terms of Service URL

  • Paths:

    • must meet the general validation rules for paths

  • Operations:

    • must meet the general validation rules for operations

    • only POST, GET, PUT and DELETE operations are supported

    • operations GET and DELETE are not supported to have a request body

    • inline and referenced parameters are supported

    • inline and referenced request bodies are supported

    • inline and referenced responses are supported

    • only one request body is supported per operation

    • no duplicated status codes are allowed in responses

  • Parameters:

    • must meet the general validation rules for parameters

    • for referenced parameters, schemas of type string, boolean, integer and number are allowed. For inline parameters primitive inline schemas are supported as well

    • parameter location can be either Path, Query or Header; Note: header parameters named Accept, Content-Type and Authorization are not allowed.

  • Request Bodies:

    • must meet the general validation rules for request bodies

    • only referenced Object, OneOf and Array schemas are supported

  • Responses:

    • must meet the general validation rules for responses

    • only referenced Object, OneOf and Array schemas are supported

    • application/json and application/json; charset=utf-8 are the only allowed content types

  • Schemas:

    • must meet the general validation rules for schemas

    • only referenced schemas are allowed as array items

    • only referenced object schemas are allowed as AllOf schemas

    • inline object schemas type are not allowed as schema properties

    • only referenced object schemas are allowed as OneOf schemas and discriminator is required here

Attention: 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.

During the import IBM Financial Services 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.

Edit an API namespace

You have two options to edit an API namespace. The first is to visit the API namespace's overview page and then open General tab then click on the Edit details button in top right corner in the first card with header API Namespace Details on the right to open the Edit master data view of the API Namespace. The second option is to expand the API Namespaces section on the project's Overview page and click on the three-dotted menu icon on the right side of each namespace card. This will also open the Details view of the namespace.

Edit the master data

By navigating to the Master data section of the Details view and using the Edit master data capability of the sub-menu, you can adjust Label and Description. You can confirm your entry by using the Save capability.

Edit API information

To edit the master data of an API namespace on the API Namespaces card on the project's Overview page in the namespaces tab. Clicking on the info menu will open the API Namespace Details dialog. Alternatively, you can use the Edit API Information button on the top right corner of the second card on the right section on the API Overview page.

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)

Attention: You are not allowed to change the Host.

Edit build information

In the Api Overview page click on the Build Information Button in the third card with header Build Information on the right and by using the Edit Build Information capability, 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 Info capability on the namespace's card in the API Namespaces section on the project's Overview page or use the Delete namespace button in top right corner on an API namespace's instance.

Attention: You will need 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