Creating a REST API

To create a REST API in IBM® Integration Bus, you can define the models, resources, and operations in the REST API Editor, or you can use the IBM Integration Toolkit to import a Swagger 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:

You can use the REST API editor that is integrated into the IBM Integration 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, such as 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 tooling that is integrated into the IBM Integration Toolkit, rather than using an external editor to create a Swagger 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 using the IBM Integration Toolkit. All the resources, operations, and parameters are loaded from the Swagger document and are viewable from the REST API editor in the IBM Integration 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 make modifications to 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 have already created a Swagger document for the REST API that you plan to implement in IBM Integration Bus.
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 Integration Bus.
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 defining models.

Procedure

Complete the steps in one of the following tasks to create a REST API in IBM Integration Bus:

Creating a REST API from scratch by using the IBM Integration Toolkit
Creating a REST API from an imported Swagger 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 have created the REST API from scratch by defining resources, models, and operations in the IBM Integration Toolkit, you must now define the operations in the REST API Editor, before implementing them. For information about how to do this, see Defining resources, models, and operations in a REST API and then Implementing an operation in a REST API.
If you have created the REST API from an imported Swagger document, you must now implement the operations, as described in Implementing an operation in a REST API.