Integration Server as a Contract-First REST API Provider using OpenAPI

Concepts

What is OpenAPI Specification?

The OpenAPI Specification (OAS) defines a standard, language-independent interface for REST APIs which allows both humans and computers to discover and understand the capabilities of a REST service. The supported interface files adopt this specification for describing and visualizing REST web services.
An OpenAPI document describes the entire API, including:

• Available endpoint (/users) and the operations it supports (GET /users, POST /users).
• Input and output data for each operation.
• Authentication methods
• Contact information, license, terms of use, and other information.

The OpenAPI document can be written in both YAML and JSON formats. Both formats are readable by both humans and machines. You can seamlessly generate services and APIs by importing an OpenAPI document in Integration Server and the APIs are compatible across providers and consumers.
Integration Server supports OpenAPI specification version 3.0.2.

What are REST API Descriptors?

A REST API Descriptor (RAD) is a container that describes the operations supported by one or more REST v2 resources or services along with the information about how to access those operations. Using this information, Integration Server creates and maintains an OpenAPI document for the RAD.
You can create two types of RAD in Integration Server:

• Provider: When you create a provider RAD, Integration Server generates various assets including a provider RAD, flow services, REST V2 resources, and JSON document types.
• Consumer: When you create a consumer RAD, Integration Server generates various assets including a consumer RAD, REST connector services, and document types.

RAD_example_transparent1280×720 67.5 KB

The above figure illustrates that a RAD:

• Is an Integration Server asset that describes the full REST API.
• Includes one or more REST v2 resources.
• Specifies the Integration Server supported authentication mechanisms:
  • HTTP authentications: Basic, Bearer, and Digest.
  • OAuth 2.0 flows: Authorization Code, Implicit, Resource Owner Password Credentials or Password, and Client Credentials.
• Provides the complete information about the API in the form of an OpenAPI document.

Using a RAD, you can:

• Define transport protocols that can be used to access the API in the RAD.
• Configure various content types that define the request or response format for the whole API or individually for an operation.

Use cases

How to create provider REST API descriptors using an OpenAPI document?

Description

Consider this use case when you want to expose REST services that adhere to the OpenAPI specification 3.0.2 to an external client and want to use Integration Server as an endpoint for the REST requests. You need to create a provider REST API descriptor (RAD) using an OpenAPI document that acts as a container for the REST services.
This use case starts when you have an OpenAPI document which is accessible through a URL or file path. It ends when the provider RAD is created and the services are exposed to client applications.

Actors

• An Integration developer who creates the provider RAD.
• An Integration Server which is an endpoint for REST requests.

Basic Flow

1. Start Software AG Designer.

2. In the Service Development perspective of Designer, select File > New > REST API Descriptor.

3. In the Create a New REST API Descriptor wizard page.

   1. Select the folder in which you want to create the RAD.

   2. In the Element name field, type a name for the RAD using any combination of letters, numbers, and the underscore character.

   3. Click Next.

4. In the Specification Version wizard page, click OpenAPI 3.x . Click Next.

   1. In the Select the Source Type wizard page, by default Designer selects RAD as Provider and the source type as OpenAPI Document . Click Next.

5. In the Select the OpenAPI Document Location wizard page, select the following to perform the corresponding action in Designer:

   Task Selection	Purpose	Course of Action
   File/URL	Generate a RAD from an OpenAPI document that resides on the file system or the Internet.	Do one of the following: Click Browse to navigate to and select an OpenAPI document on your local file system. Enter the URL for the OpenAPI document. Provide your username and password to use the OpenAPI document from the website.
   Import OpenAPI document based on tags	Groups the operations under a REST V2 resource based on the tags. If you do not select this option, Designer groups the operations by path	By default, the check box is selected.
   Document name prefix	Designer uses this as prefix name while creating the JSON document types and variables for anonymous schemas. If you do not add a prefix, by default Designer adds _untitled as prefix. The prefix name must not be the same as the schema name or the property name present in the OpenAPI document.	Add a prefix name.

   1. Click Finish.

      Designer creates the provider RAD based on the OpenAPI document and creates the associated services, JSON document types, callback services, and resources, and places them under a folder that has the same name as the RAD appended with an underscore (_).

   If there is any change in the OpenAPI document and you want to refresh the generated assets, you can refresh the provider RAD in Designer.

   Alternative/Exception Flows

   If the OpenAPI document is invalid or any exception arises during the RAD creation, Integration Server does not generate the RAD and displays error message in Designer.

   How to refresh provider REST API descriptors using an OpenAPI document?

   Description

   Consider this use case where the OpenAPI document used to create a REST API Descriptor (RAD) changes and you need to update the RAD and other assets to reflect the changes.
   This use case starts when you have identified the OpenAPI document needed to refresh the provider RAD. It ends when Integration Server refreshes all the assets related to the provider RAD according to the OpenAPI document.

   Actors

   • An Integration developer refreshing the provider RAD.
   • An Integration Server that refreshes the provider RAD.

   Pre-conditions

   Before you refresh a provider REST API Descriptor (RAD) using an OpenAPI document, ensure that the OpenAPI document is valid and based on the OpenAPI Specification version 3.0.2.

   Basic Flow

   1. Start Designer.

   2. In the Package Navigator view, lock the RAD that you want to refresh.

   3. Right-click on the RAD and select Refresh REST API Descriptor.

   4. Review the informational message about potential changes to the existing RAD and click OK to continue with refresh.

   5. Click Yes to refresh the RAD with a new OpenAPI document or if the location of the original OpenAPI document has changed. Click No to use the OpenAPI document from the existing specified location.

   6. When you click Yes , Designer displays the Select the OpenAPI Document Location dialog box.

   7. Select the OpenAPI document for which the location has changed and click Finish.
      After you refresh a provider REST API Descriptor (RAD), Integration Server adds elements, such as services, document types, callback services, or resources to the RAD to reflect new elements in the updated OpenAPI document.

   Alternate/Exception Flows

   • If Integration Server cannot refresh a provider RAD, Integration Server rolls back to the last saved version of the RAD.
   • If refresh is not successful, refer to Integration Server logs to determine the issue.

   How to handle different schemas for different content types?

   Description

   Consider this use case where a client sends REST API requests with different content types and Integration Server needs to process these requests.

   The body of the OpenAPI document lists the content types consumed by the service, for example, application/json, application/xml and specifies the schema for each content type. You can define multiple content types in the request body, such as JSON, XML, form data, plain text, and use different schemas for different content types. A client can include any supported content type while sending a REST API request.

   Integration Server sends the REST response with an HTTP status code and returns the data in the response body and/or headers. Integration Server can respond with various content types.

   The following is a segment of an OpenAPI document that highlights multiple content types in the request body and response.

   requestBody:
   content:
   application/json:
   schema:
   $ref: `#/components/schemas/Pet`
   application/xml:
   schema:
   $ref: `#/components/schemas/Pet`
   application/x-www-form-urlencoded:
   schema:
   $ref: `#/components/schemas/PetForm`
   responses:
   content:
   application/xml:
   schema:
   $ref: `#/components/schemas/Pet`
   application/json:
   schema:
   $ref: `#/components/schemas/PetForm`
   

   This use case starts when you have identified that the OpenAPI document defines different schemas under different content types. It ends when you have identified the content type that the client is using while sending the REST API request.

   Actors

   • An integration developer implementing the business login in the service.
   • An Integration Server that processes the REST API request.

   Basic Flow

   1. Start Designer.

   2. Create a provider REST API Descriptor (RAD) using an OpenAPI document.

   3. Verify if the following assets are generated after you create the RAD:

      • A RAD under the <RADName>_ folder.
      • Document types under the docTypes folder.
      • REST v2 resources under the resources folder.
      • Services under the services folder

   4. In the Package Navigator view, lock the service that you want to update.

   5. Use pub.flow:getTransportInfo service to obtain information about the content type of the REST API request. For more details on the pub.flow:getTransportInfo, refer to the Integration Server Built-In Services Reference guide.

   Because the request body of the OpenAPI document may contain multiple content types, you can use the above service to check the content type of the REST API request and use the respective document type for the service implementation.
   For example, you can import the OpenAPI document, differentContentType.yml(attached below) to create a RAD.

   differentContentType.zip (1.4 KB)

   Integration Server generates the following assets:

   • A RAD, myRad_.
   • Document types under myRad_ > docTypes folder.
   • REST v2 resources under myRad_ > resources folder.
   • Services under myRad_ > services folder.

   The input signature of the service contains two document types:

   • Pet: schema corresponds to application/json and application/xml.
   • PetForm: schema corresponds to application/x-www-form-urlencoded.
   6. Implement the business logic of the service.

   For example, you can install the package, Sample_OAS.zip(attached below) to determine the content type of the REST request.

   Sample_OAS.zip (18.6 KB)

   References

   • OpenAPI Specification - Version 3.0.2
   • REST Capabilities In Integration Server - Knowledge base - Software AG Tech Community & Forums

   –End