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 (Eg. 1.2.0 to 2.0.0) but the Prefix should also be updated as the consumers of the APIs should 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 API namespaces Overview section or in the left navigation bar.

An API namespace is defined by the following master data:

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

Create an API namespace from scratch

After selecting and confirming the from scratch option you have to provide the following meta-data about the API.

  • 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)

By proceeding with Next you can select the format for the API specification (OpenApi 3.0 or Swagger 2.0) you want to generate and add additional integration artifacts that should be automatically produced during the build process of the project. Clicking on Create after that will persist the new API namespace.

Create a new API namespace based on an 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 click on the Info icon in the top right to open the Details 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, use the Info capability on the namespace's card in the API Namespaces section on the project's Overview page. Alternatively, you can use the Info capability on an API namespace's instance page to open the Details view, navigate to the Master Data section and use the Edit Master Data capability there.

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

By navigating to the Build Information section and by using the Edit Build Information capability, you can adjust the Supported API Specification and the additional API Integrations. 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 Info capability on an API namespace's instance page to open the Details view, navigate to the Master Data section and use the Delete capability there.

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