Defining resources, models, and operations in a REST API

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

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

1. 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 pushing 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 pushing 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. In order to invoke an operation defined in this REST API 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 invoking. Depending on the operation being invoked, you might also need to pass additional parameters, or a request body.

2. 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 has been created. Use the button on the right side of the resource to add additional 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.
3. When you have added an operation under a resource, you can manipulate it.
   An operation can have several different kinds of parameters, and 0 or more responses, shown in these 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 Integration Bus 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 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 Integration Bus run time; however, it is advisable to set it correctly for use with Swagger tooling.

     The Required field states whether or not the parameter must be specified by HTTP clients invoking 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 Integration Bus 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 Integration Bus.

   • Request Body

     Use the Add request button and the Delete button to add or delete a request body, if a request body is permitted 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 Integration Bus 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 should be a valid HTTP status code as described by RFC 7231 or the IANA Status Code Registry. You can have multiple responses defined 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 Integration Bus 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 will be defined as returning an array of arrays

4. 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 Integration Bus; 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 top right of the Model Definitions section, to add the first child. You can then add additional children to build up the required structure:

   

   You can specify if the data type should be an array, whether it is required, whether it will allow 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 could 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 could also define a GET for returning multiple Pets by setting the operation Schema type to Pet and checking the Array option: