Working with REST API Descriptors
REST (Representational State Transfer) is an architectural style that requires web applications to support HTTP methods such as GET, POST, PUT, PATCH, DELETE, and HEAD, and to use a consistent, application-independent interface.
Note:
When a REST V2 resource does not define the HTTP HEAD method explicitly but supports the HTTP GET method, and if a client invokes the HEAD method, Integration Server sends the response using the GET method. However, the response does not contain the response body.
Integration Server can act as a REST server or a REST client. When Integration Server acts as a REST client, Integration Server sends specifically formatted requests to the REST server.
For Integration Server to act as a REST server, it must host services that perform the above HTTP methods. These services perform functions that are specific to your application.
The focus of REST is on resources rather than services. A resource is a representation of an object or information. A resource can represent:
A single entity, like a coffee pot you want to purchase from an online shopping site.
A collection of entities, like records from a database.
Dynamic information, like real-time status updates from a monitoring site.
That is, resources are the entities or collections of entities in a distributed system that you want to post or retrieve or take action on. In a REST style system, each resource is identified by a universal resource identifier (URI).
Development of REST systems is defined by a series of constraints:
Clients and servers are separate.
Communication between clients and servers is stateless.
Clients can cache responses returned from servers.
There may be intermediate layers between the client and server.
Servers can supply code for the clients to execute.
Clients and servers remain loosely coupled by communicating through a uniform interface.
The uniform interface is the key constraint that differentiates REST from other architectural approaches. The characteristics of this interface are:
Requests identify resources.
Responses contain representations of those resources.
Clients manipulate resources through their representations.
Messages are self-descriptive.
The interface employs Hypermedia as the engine of application state (HATEOAS), which enables the client to find other resources referenced in the response.
One strength of REST is that it leverages the well understood methods supported by HTTP to describe what actions should be taken on a resource. To be REST-compliant, an application must support the HTTP methods. Many applications use web browsers to interact with resources on the Internet. Web browsers, however, typically support only the HTTP GET and HTTP POST methods. To get around this restriction, you can use Integration Server to build REST-compliant applications that support the HTTP methods.
About REST Request Messages
REST clients send specially formatted requests to your REST application. The format of REST requests is determined by the webMethods Integration Server REST implementation and your specific application, but essentially it conveys the following information, or tokens, to the REST server:
The HTTP method to execute
The directive
The name of the resource
More complex request messages can contain more explicit information about the resource.
When Integration Server processes a REST request, it parses the tokens and identifies the HTTP method to execute, locates the resource to act upon, and passes additional information as input parameters to the services you wrote for your application. The configuration of the REST resources determines how Integration Server handles the requests from REST clients.
Sending Responses to the REST Client
When Integration Server responds to an HTTP request, the response contains a status line, header fields, and a message body.
Status Line
The status line consists of the HTTP version followed by a numeric status code and a reason phrase. The reason phrase is a brief textual description of the status code. Integration Server always sets the HTTP version to match the version of the client that issued the request. You cannot change the HTTP version.
You can use the pub.flow:setResponseCode service to set the status code and reason phrase. You can also set the status code and reason phrase of an HTTP request by adding a variable named $httpResponse that references the pub.flow:httpResponse document type to the flow service pipeline. For more information on this document type, see the section pub.flow:HTTPResponse in the webMethods Integration Server Built-In Services Reference. If you do not explicitly set the status code, Integration Server will set it to 200 for successfully completed requests and an appropriate error code for unsuccessful requests.
HTTP/1.1 defines all the legal status codes in Section
http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10. Examine these codes to determine which are appropriate for your application.
Header Fields
You can communicate information about the request and the response through header fields in the HTTP response. Integration Server will generate some header fields, such as Set-Cookie, WWW-Authenticate, Content-Type, Content-Length, and Connection. You can use the pub.flow:setResponseHeader to set Content-Type and other header fields. You can also set the header fields of an HTTP request by adding a variable named $httpResponse that references the pub.flow:httpResponse document type to the flow service pipeline. For more information on this document type, see the section pub.flow:HTTPResponse in the webMethods Integration Server Built-In Services Reference..
HTTP/1.1 defines the header fields that can appear in a response in three sections of RFC 2616:
4.5,
6.2, and
7.1. Examine these codes to determine which are appropriate for your application.
Message Body
The message body usually contains a representation of the requested resource, one or more URLs that satisfy the request, or both. In some cases, the message body should be empty, as specified in
RFC 2616, Section 4.3You can use the pub.flow:setResponse service to explicitly set the message body. You can also set the message body of an HTTP request by adding a variable named $httpResponse that references the pub.flow:httpResponse document type to the flow service pipeline. For more information on this document type, see the section pub.flow:HTTPResponse in the webMethods Integration Server Built-In Services Reference. If you do not explicitly set the message body, the output pipeline of the top-level service will be returned to the client in the message body.
In URL template-based approach, Integration Server returns the output defined in the output of the service as a response to the client.
For more information about how Integration Server builds HTTP responses, see the section About Content Handlers for HTTP Responses in the webMethods Integration Server Administrator’s Guide.
Setting Responses Using pub.flow:HTTPResponse
The pub.flow:HTTPResponse document type helps you to set the response headers. You can add a reference of pub.flow:HTTPResponse document type with the name $httpResponse to the pipeline and use this pipeline variable instead of invoking the pub.flow:setResponseCode, pub.flow:setResponseHeader, and pub.flow:setResponse services to set the response headers.
For more information, see the section pub.flow:setResponse in the webMethods Integration Server Built-In Services Reference.
A REST API descriptor (RAD) provides a way of describing the operations provided by one or more REST resources or services along with the information about how to access those operations. RAD defines data exchange formats supported by these operations, security mechanisms to access these operations, and the MIME types the resources consume and produce. Integration Server generates the RAD as an asset and you can create the RAD as a provider or as a consumer. Integration Server supports generating the RAD based on the following specifications:
Swagger specification version 2.0
OpenAPI specification version 3.0.x
While generating the RAD based on Swagger specification 2.0, Integration Server creates and maintains a Swagger document for the RAD and while generating it based on OpenAPI specification 3.0.x, Integration Server creates and maintains an OpenAPI document for the RAD.
Using Designer you can create a REST API descriptor using resource first or Swagger first approach.
Note:
The base path of the created REST API descriptor is set as /rad/<namespaceName of the REST API descriptor>. You can change the base path. To avoid exposing the server namespace name to the end user, set the base path to an application specific path.
Swagger first refers to REST API descriptors created by importing a Swagger document. During this process,
Integration Server creates services, doctypes, and REST V2 resources based on the contents of the Swagger document. The application developer then provides the service implementation of the generated services. You can then invoke the REST application through a client. Because the Swagger specification does not include resource definitions,
Integration Server allows you to create the REST V2 resources based on tags or based on the Swagger paths. Tags defined in a Swagger document are used for grouping of operations. If you choose to create a REST V2 resource based on tags, all the operations associated to a tag are grouped together. Otherwise, the resources are created based on the Swagger path. For more information about creating a REST API descriptor using a Swagger document, see
Creating a Provider REST API Descriptor from a Swagger
Document.
Note:
In the Swagger first approach to create a REST API descriptor, Integration Server automatically creates a URL alias for the base path of the created REST API descriptor.
You can use REST API descriptors to access a Swagger document through a URL in JSON and YAML format.
The standard URLs to access the Swagger document are:
JSON Format:
http://host:port/<base_path>?swagger.jsonYAML Format:
http://host:port/<base_Path>?swagger.yamlThe following table lists the standard URLs under appropriate conditions:
If the URL includes.. | URL in JSON format is.. | URL in YAML format is.. |
A default base path. | http://host:port/rad/<namespace_of_rad>?swagger.json. For example, http://host:port/rad/cc:rad?swagger.json. | http://host:port/rad/<namespace_of_rad>>?swagger.yaml. For example, http://host:port/rad/cc:rad?swagger.yaml. |
An application specific base path. | http://host:port/<alias_name>?swagger.json. For example, http://host:port/api?swagger.json. | http://host:port/<alias_name>?swagger.yaml. For example, http://host:port/api?swagger.yaml. |
The server response type for a JSON based application is, application/json and for a YAML based application is, application/x-yaml.
You can also access the Swagger document for REST API descriptor that is created using the legacy REST resources using the above mentioned URLs.
Note:
If the REST API descriptor does not exist in the Integration Server namespace or if the format is not swagger.json or swagger.yaml, Integration Server returns an error message. For example, if the URL is http://host:port/api?swagger.xml, then the Integration Server throws an error.
Services for REST Resources Configured Using the URL Template-Based Approach
The URL template-based approach helps you configure REST resources for an existing
Integration Server service. The HTTP methods that you can configure for a REST resource are restricted only by the methods that you configure as allowed for the underlying service. The methods supported by a REST resource must be a subset of the methods allowed for the service corresponding to the REST resource. For information about configuring the supported methods for a REST resource and its corresponding
Integration Server service, see
Defining a REST V2 Resource
Operation.
If a REST request specifies an HTTP method that is not allowed for its service, the request fails with a “405 Method Not Allowed error.
Example 1
A REST service and its corresponding resource support the GET, PUT, and DELETE services:
If the client sends a... | Integration Server responds by... |
GET request | Executing the GET method |
PUT request | Executing the PUT method |
POST request | Issuing error “405 Method Not Allowed” |
Note:
This example assumes that the request URL is in a format supported by the REST resource.
Configuration
There are a few things you can configure with respect to REST V2 processing:
Name of the REST V2 directive
If you want to allow clients to specify a name other than “rad” for the REST V2 directive, you can do so with the watt.server.RESTDirective.V2 configuration parameter. For example, to allow clients to specify “process” for the REST V2 directive, you would change the property to the following:
watt.server.RESTDirective.V2=process
With this setting, clients can specify “rad” or “process” for the REST directive. In the following example, the two requests are equivalent:
METHOD /process/discussion/topic/9876 HTTP/1.1
METHOD /rad/discussion/topic/9876 HTTP/1.1
For more information about the watt.server.RESTDirective.V2 property, refer to webMethods Integration Server Administrator’s Guide.
Which ports will accept the REST V2 directive
By default, all Integration Server ports except the proxy port allow use of the REST directive. You can limit which ports will allow this directive by specifying them on the watt.server.allowDirective.V2 configuration parameter. For more information about this property, refer to the webMethods Integration Server Administrator’s Guide.
Converting an Existing Application to a REST Application
If you have an existing application that you want to transform into a REST application, consider using the URL template-based approach and configure REST resources for the application. This is the most straightforward approach you can use to transform the application.
Designer provides two ways to create RAD, as a provider or as a consumer. You can create a provider or consumer RAD based on Swagger specification version 2.0 and can create a provider RAD based on OpenAPI specification version 3.0.x.
An OpenAPI based provider RAD describes an external REST API allowing
Integration Server to create the document types, resources, and services based on the imported OpenAPI document. You can modify these flow services and share the updated OpenAPI document with users. You can also modify the server details in the generated RAD. However, other fields present in the RAD are read-only.
A Swagger based provider RAD describes a REST API that is hosted in
Integration Server which can be accessed by the external clients.
Integration Server generates the Swagger document based on the RAD and external clients use this Swagger document to access the REST API. You can create a provider RAD from an
Integration Server REST resource or from a Swagger document. You can edit the details of the RAD generated from a REST resource; however, the RAD generated from a Swagger document is read-only.
A Swagger based consumer RAD describes an external REST API, allowing
Integration Server to create a REST connector service for each operation in the REST API. You can use the REST connector service just like any other
Integration Server flow service; when you invoke a connector service, it calls a specific operation of a REST API.
Integration Server generates the connector service signature based on the Swagger document.