Defining resources, models, and operations in a REST API by using the REST API Editor

Use the REST API Editor to graphically define resources, models, and operations in a REST API.

1. In the IBM App Connect Enterprise Toolkit, navigate to your REST API project.
2. Open the REST API Description by double-clicking the REST API project or by right-clicking and selecting Open.
   The REST API editor for Swagger documents opens and provides a view of the API details, it Resources and Operations, Error handling, Security, and Message Validation Settings.

To define resources, models, and operations in a REST API, complete the following steps:

3. Use the Header section of the REST API Editor to display and modify general information about the REST API.

   The REST API base URL field displays the current base path for the REST API. All resources in a REST API are defined relative to its base path. You can edit this field to modify the base path of the REST API. The value of this field must be a valid URL path segment, and must not contain any variable elements.

   The Title field displays the current title of the REST API. The Title is distinct from the REST API project name, and is defined as a property in the Swagger document. The Title is used when you push a REST API into IBM API Management.

   The Version field displays the current version of the REST API. It is defined as a property in the Swagger document. The Version is used when you push a REST API into IBM API Management.

   The header section also includes an example REST API base URL. The hostname and port number portions of this URL must be replaced with the hostname and port number of the integration server that the REST API is deployed to. To start an operation that is defined in this REST API by using an HTTP client, you must combine the REST API base URL, the path of the operations resource, and the HTTP method for the operation that you are starting. Depending on the operation that is being started, you might also need to pass extra parameters, or a request body.

4. Use the Resources section to manipulate the resources for your REST API:
   • Use this button to create a new resource in your REST API. When you click this button, a dialog is displayed in which you can specify the resource path and select the operations that you want to add to the resource: GET, POST, PUT, DELETE, OPTIONS, HEAD, and PATCH. When you click OK, the new resource and the operations for that resource are added to the REST API.
   • You can also add and remove operations from a resource after it is created. Use the button on the right side of the resource to add more operations to an existing resource. Use the button on the right side of the operation to remove that operation from its resource.
   • Use this button to modify your resource path. When you click this button, a dialog is displayed in which you can modify the resource path.
   • Use this button to expand all operations under each resource.
   • Use this button to collapse all operations under each resource.
5. When you add an operation under a resource, you can manipulate it.
   An operation can have several different kinds of parameters, and 0 or more responses, which are shown in the following sections:

   • Path, Query, and Header parameter

     Use the Add button and the Delete button to add or delete Header and Query parameters, and then set their Name, Type, and Data Type, and optionally, the Format, Required, and Description values.

     The Name and Type fields of a Path parameter cannot be changed, and the name must match the path template in the resource. Path parameters can be added or removed only by editing the path template in the Resource.

     The Data Type of a Path, Query, or Header parameter can be set only to a primitive data type, such as string, number, integer, or Boolean. These primitive data types correspond with those in the Swagger specification, and map to the possible primitive types in a JSON document. You cannot set the Data Type of a Path, Query, or Header parameter to that of a Model defined in the REST API. The Data Type of a Path, Query, or Header parameter is not currently used by the IBM App Connect Enterprise run time, and the parameters are provided to the nodes in the subflow as character data. The Graphical Data Map models them as strings. However, it is advisable to set the parameter correctly for use with Swagger tooling.

     The Format field is an optional free-form description of the format of the data that is expected for values of this parameter. For example, you can use formats that are mentioned in the Swagger specification such as int32, double, or date-time. Alternatively, you can include your own format names, such as customer-id. The Format of a Path, Query, or Header parameter is not currently used by the IBM App Connect Enterprise run time; however, it is advisable to set it correctly for use with Swagger tooling.

     The Required field states whether the parameter must be specified by HTTP clients that start this operation. Path parameters must always be specified in the request URL by an HTTP client. This field cannot be changed for Path parameters. Query and Header parameters can be marked as optional by deselecting this checkbox. The presence of a Query or Header parameter is not currently validated by the IBM App Connect Enterprise run time. However, it is advisable to set it correctly for use with Swagger tooling.

     The Swagger Form parameter type is not supported in IBM App Connect Enterprise.

   • Request Body

     Use the Add request button and the Delete button to add or delete a request body, if a request body is allowed for the HTTP method of the selected operation. For example, GET, HEAD, DELETE, and OPTIONS requests do not permit request bodies.

     A request body is usually a JSON document, and the structure of that JSON document can be defined in a Model. The structure of a request body is not currently validated by the IBM App Connect Enterprise run time. However, the Model definition can be used with a Mapping node to graphically implement the REST API operation. It is advisable to define Models for all of the possible JSON request bodies in the API, for use with Swagger tooling.

     The Schema type for Request includes all primitive data types, such as string, number, integer, or boolean, plus all models defined in the API.

   • Response Body

     Use the Add response button and the Delete button to add or delete a response, if a response body is permitted for the HTTP method of the selected operation. For example, HEAD requests do not return a response body.

     Set the HTTP status code number for this response as the value of the Response Status field. The HTTP status code must be a valid HTTP status code as described by RFC 7231 or the IANA Status Code Registry. You can define multiple responses for a single operation, but the HTTP status code of a response must be unique within that operation.

     A response body is usually a JSON document, and the structure of that JSON document can be defined in a Model. The structure of a response body is not currently validated by the IBM App Connect Enterprise run time. However, the Model definition can be used with a Mapping node to graphically implement the REST API operation. It is advisable to define Models for all of the possible JSON request bodies in the API for use with Swagger tooling.

     The Schema type for Response includes all primitive data types, such as string, number, integer, or boolean, plus all models defined in the API. Additionally, you can specify if this operation returns an array of values, where the type of each item in that array is defined by the Schema type field. If you specify that the response is an array, and the Schema type refers to a Model that is itself an array, the Response is defined as returning an array of arrays.

6. Use the Model Definitions section of the editor to define the JSON data that you can use for the Request and Response Schema type in your operations.
   To create a new Model data type, click the Add button next to the Model Definitions field, and enter a name for your new JSON data type:

   

   You can define models of type object, string, integer, number, boolean, and null.

   Note: The file data type is not supported by IBM App Connect Enterprise; you cannot set a parameter or model type as file.

   To create an object Model when you have entered its name, use the Add a child for selection button , located in the Model Definitions section, to add the first child. You can then add more children to build up the required structure:

   

   You can specify if the data type must be an array, whether it is required, whether it allows null, and you can specify a format. Format is a free form text field, which you can use to describe the format of the data. For example, you can have a string with a format of date. For more information, see http://swagger.io/specification/#dataTypeFormat.

   The following example shows the definition of a Pet schema type:

   

   This Pet Model schema type ^could be used in a GET operation to produce a JSON data message with the following format:

   {
   	"id": 1001,
   	"category": {
   		"id": 10,
   		"name": "Cat"
   	},
   	"name": "Moggy",
   	"photoUrls": ["http:\/\/something.com\/images?q=tbn:XmoggyJjB2XhAqq97VzJP"],
   	"tags": [{
   		"id": 11,
   		"name": "Moggy"
   	}],
   	"status": "pending"
   }

   You can also define a GET for returning multiple Pets by setting the operation Schema type to Pet and checking the Array option:

   

   While the Open API editor is active in a separate window to allow editing the resources, models, and operations theIBM App Connect Enterprise Toolkit REST API editor for Swagger documents is in a read-only mode. You must close the REST API API editor to re-enable the ACE Toolkit REST API editor for Swagger documents.