API Namespaces

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

The user can define various endpoints (paths) for an 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.

Create an API Namespace

To create an API namespace, use the Create capability in the API namespaces Overview section or in the navigation.

An API namespace is defined by the following master data:


Property	Description
Prefix	This is the prefix of the API namespace. It is unique within an API solution. 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 API Namespace from Scratch

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


Property	Description
API Title	Title of the API. This field is mandatory.
API Description	Description of the API. This field is optional.
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 This field is mandatory.
Contact E-mail	Contact E-mail of the API. A valid E-mail must be provided. This field is optional.
Contact name	Contact name of the API. This field is optional.
Contact URL	Contact URL of the API. This field is optional.
License Name	License name of the API. This field is optional.
License URL	License URL of the API. A valid URL must be provided This field is optional.
Terms of service URL	Terms of service URL of the API. A valid URL must be provided This field is 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 artefacts that should be automatically produced during the build process of the solution. Create after that will persist the new API namespace.

Create a new API Namespace based on an uploaded API Specification

After selecting “based on uploaded Open API/Swagger file" option you have to provide a 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 capability.

For API specifications currently the following content is supported to be imported to the new API namespace.

General validations
- Must meet the general validation rules that can be found here
- 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 DELTE 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', 'one of' and 'array' schemas are supported
Responses
- Must meet the general validation rules for responses
- Only referenced 'object', 'one of' 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 indicated what should be changed within the spec file to meet the expectations.

During the import 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 importing.
Path URL is required not to end with a ‘/’ which is automatically removed during importing.

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 successfully creation of the API namespace a confirmation is shown and the created elements of the API namespaces are stated.

Edit an API Namespace

To edit an API namespace, navigate to the Details view of the API namespace that is accessible by clicking on the namespace itself from the API namespace overview page.

Edit the Master Data

By navigating to the master data section and by using the Edit master data capability, you can adjust the "Label” and "Description". You can confirm your entry by using the Save capability.

Edit API Information

By navigating to the API information section and by using the Edit API Information capability, you can adjust the following information:


Property	Description
API Title	Title of the API. This field is mandatory.
API Description	Description of the API. This field is optional.
Contact E-mail	Contact E-mail of the API. A valid E-mails must be provided. This field is optional.
Contact name	Contact name of the API. This field is optional.
Contact URL	Contact URL of the API. This field is optional.
License URL	License URL of the API. A valid URL must be provided This field is optional.
Terms of service URL	Terms of service URL of the API. A valid URL must be provided This field is optional.

Attention: You are not allowed to change the Host and Licence Name.

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

You can delete an API namespace by navigating to the details view by clicking on the namespace card and using the Delete capability.

You will need to confirm the action before the selected command is permanently deleted.

Attention: You can only delete a namespace if artefacts that belong to the namespace are not in use.