Use the REST API Editor to graphically define resources, models, and operations in a REST API.
Use the sections in the REST API Editor to define your REST API.
To define resources, models, and operations in a REST API, complete the following steps:
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.
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.
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.
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
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.
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: