Creating a REST API

To create a REST API in IBM® App Connect Enterprise, you can define the models, resources, and operations in the REST API Editor, or the OpenAPI editor. Alternatively, you can use the IBM App Connect Enterprise Toolkit to import a Swagger document or an OpenAPI 3.0 document that describes the resources and operations that you want in the REST API.

About this task

Both methods of creating a REST API have advantages, and the most appropriate method depends on your circumstances.

Creating a REST API from scratch by using Swagger specifications

You can use the REST API editor that is integrated into the IBM App Connect Enterprise Toolkit to create a REST API from scratch. The REST API editor enables you to graphically create a REST API by defining the resources, operations, and parameters for that REST API. You can also use the REST API editor to define models that represent the structure of JSON request and response bodies for the operations in the REST API. The models that you define with the REST API editor can then be used by the Graphical Data Mapping editor to implement the operations in the REST API.

The REST API editor creates and modifies a Swagger document that is compliant with version 2.0 of the Swagger specification. The Swagger document can be used with the Graphical Data Mapping editor to implement operations in the REST API as well as a wide range of external tools. For example, Swagger UI, Swagger Codegen, and IBM API Management. However, the REST API editor does not support the full Swagger specification, and cannot be used to set some properties, such as validation attributes, on objects in the Swagger document.

Use the REST API editor to create a REST API from scratch in the following circumstances:

You have limited or no knowledge of the Swagger specification.
You prefer to use the graphical tools that are integrated into the IBM Integration Toolkit, rather than using an external editor to create a Swagger document.

Creating a REST API from scratch by using OpenAPI 3.0 specifications

You can use the OpenAPI editor that is integrated into the IBM App Connect Enterprise Toolkit to create a REST API from scratch. By using the OpenAPI editor, you can graphically create a REST API by defining the resources, operations, and parameters for that REST API. You can also use the OpenAPI editor to define models that represent the structure of JSON request and response bodies for the operations in the REST API. The models that you define with the OpenAPI editor can then be used by the Graphical Data Mapping editor to implement the operations in the REST API.

The OpenAPI editor creates and modifies an OpenAPI 3.0 document. The OpenAPI 3.0 document can be used with the Graphical Data Mapping editor to implement operations in the REST API.

Use the OpenAPI editor to create a REST API from scratch by using OpenAPI 3.0 specifications in the following circumstances:

You have limited or no knowledge of the OpenAPI 3.0 specification.
You prefer to use the graphical tools that are integrated into the IBM Integration Toolkit, rather than using an external editor to create an OpenAPI 3.0 document.

Creating a REST API by importing a Swagger document

You can use an external editor, such as Swagger Editor, to create a Swagger document that defines the REST API that you want to implement. You can then create a REST API by importing this Swagger document by using the IBM App Connect Enterprise Toolkit. All the resources, operations, and parameters are loaded from the Swagger document and are viewable from the REST API editor in the IBM App Connect Enterprise Toolkit. The models are also loaded from the Swagger document, and those models can then be used with the Graphical Data Mapping editor to implement operations in the REST API.

The REST API editor in the IBM Integration Toolkit also allows you to modify the REST API, such as adding new resources, and it modifies the imported Swagger document automatically. However, the REST API editor does not support the full Swagger specification, and might be unable to display or modify the full contents of an imported Swagger document.

Create a REST API by importing a Swagger document in the following circumstances:

You have good knowledge of the Swagger specification, and you create a Swagger document for the REST API that you plan to implement in IBM App Connect Enterprise.
A separate member of your team, such as an API Designer, is creating a Swagger document for the REST API that you plan to implement in IBM App Connect Enterprise.
You require the use of all properties in the Swagger specification; for example, the validation attributes such as maxLength, uniqueItems, and allOf, which are available when you define models.

Creating a REST API by importing an OpenAPI 3.0 document

You can use an external editor to create an OpenAPI 3.0 document that defines the REST API that you want to implement. You can then create a REST API by importing this OpenAPI 3.0 document by using the IBM App Connect Enterprise Toolkit. All the resources, operations, and parameters are loaded from the OpenAPI 3.0 document and are viewable from the OpenAPI editor in the IBM App Connect Enterprise Toolkit. The models are also loaded from the OpenAPI 3.0 document, and those models can then be used with the Graphical Data Mapping editor to implement operations in the REST API.

The OpenAPI editor in the IBM Integration Toolkit also allows you to modify the REST API, such as adding new resources, and it modifies the imported OpenAPI 3.0 document automatically.

Create a REST API by importing an OpenAPI document in the following circumstances:

You have good knowledge of the OpenAPI 3.0 specification, and you create an OpenAPI 3.0 document for the REST API that you plan to implement in IBM App Connect Enterprise.
A separate member of your team, such as an API Designer, is creating an OpenAPI 3.0 document for the REST API that you plan to implement in IBM App Connect Enterprise.
You require the use of all properties in the OpenAPI 3.0 specification.

Procedure

Complete the steps in one of the following tasks to create a REST API in IBM App Connect Enterprise:

Creating a REST API from scratch with Swagger specifications by using the IBM App Connect Enterprise Toolkit
Creating a REST API from scratch with OpenAPI 3.0 specifications by using the IBM App Connect Enterprise Toolkit
Creating a REST API from an imported Swagger document.
Creating a REST API from an imported OpenAPI 3.0 document.

If you are importing a Swagger document, ensure that you are aware of the restrictions on the format of Swagger documents that are used to create REST APIs, as described in Restrictions on Swagger documents.

What to do next

If you created the REST API from scratch by defining resources, models, and operations in the IBM App Connect Enterprise Toolkit, you must now define the operations in the REST API Editor or the OpenAPI editor before you implement them. For information, see Defining resources, models, and operations in a REST API by using the REST API Editor, and Defining resources, models, and operations in a REST API by using the OpenAPI editor.
If you create the REST API from an imported Swagger document, you must then implement the operations, as described in Implementing an operation in a REST API by using the REST API Editor for Swagger 2 documents.