REST Developer’s Guide

  

Version 9.6

April 2014
   

This document applies to webMethods Integration Server Version 9.6 and to all subsequent releases.
Specifications contained herein are subject to change and these changes will be reported in subsequent release notes or new editions.
Copyright © 2010-2014 Software AG, Darmstadt, Germany and/or Software AG USA Inc., Reston, VA, USA, and/or its subsidiaries and/or
its affiliates and/or their licensors.
The name Software AG and all Software AG product names are either trademarks or registered trademarks of Software AG and/or
Software AG USA Inc. and/or its subsidiaries and/or its affiliates and/or their licensors. Other company and product names mentioned
herein may be trademarks of their respective owners.
Detailed information on trademarks and patents owned by Software AG and/or its subsidiaries is located at
hp://documentation.softwareag.com/legal/.
Use of this software is subject to adherence to Software AG's licensing conditions and terms. These terms are part of the product
documentation, located at hp://documentation.softwareag.com/legal/ and/or in the root installation directory of the licensed product(s).
This software may include portions of third-party products. For third-party copyright notices and license terms, please refer to "License
Texts, Copyright Notices and Disclaimers of Third Party Products”. This document is part of the product documentation, located at
hp://documentation.softwareag.com/legal/ and/or in the root installation directory of the licensed product(s).

Document ID: IS-RS-DG-96-20140415

 M  
Table of Contents

Table of Contents

About this Guide..............................................................................................................................5

Document Conventions.............................................................................................................. 5
Documentation Installation......................................................................................................... 6
Online Information...................................................................................................................... 6

About Integration Server REST Processing................................................................................. 9

Overview................................................................................................................................... 10

How REST Processing Works...................................................................................................... 13

About REST Request Messages..............................................................................................14
How webMethods Integration Server Processes REST Requests...........................................14
Sending Responses to the REST Client.................................................................................. 16
Status Line.........................................................................................................................16
Header Fields.................................................................................................................... 17
Message Body...................................................................................................................17

Setting Up Your REST Application.............................................................................................. 19

Setting Up a REST Application on Integration Server............................................................. 20
Services............................................................................................................................. 20
Configuration......................................................................................................................21
Converting an Existing Application...........................................................................................22

Documenting Your Rest Application........................................................................................... 23

Providing Information About Your Application.......................................................................... 24
General Information...........................................................................................................24
Information About Each Request...................................................................................... 24
Information About Responses........................................................................................... 26

Index................................................................................................................................................ 27

REST Developer’s Guide Version 9.6 3

 M  
Even Header

REST Developer’s Guide Version 9.6 4

 M  
Odd Header

About this Guide

This guide is for developers using webMethods Integration Server to create REST
applications. This guide assumes basic knowledge of REST concepts and HTTP request
processing and familiarity with Software AG Designer and webMethods Integration
Server.

Document Conventions

Convention Description

Bold Identifies elements on a screen.

Narrowfont Identifies storage locations for services on webMethods

Integration Server, using the convention folder.subfolder:service .

UPPERCASE Identifies keyboard keys. Keys you must press simultaneously

are joined with a plus sign (+).

Italic Identifies variables for which you must supply values specific to
your own situation or environment. Identifies new terms the first
time they occur in the text.

Monospace Identifies text you must type or messages displayed by the

font system.

{} Indicates a set of choices from which you must choose one. Type
only the information inside the curly braces. Do not type the { }
symbols.

| Separates two mutually exclusive choices in a syntax line. Type

one of these choices. Do not type the | symbol.

[] Indicates one or more options. Type only the information inside

the square brackets. Do not type the [ ] symbols.

... Indicates that you can type multiple options of the same type.
Type only the information. Do not type the ellipsis (...).

REST Developer’s Guide Version 9.6 5

 M  
Even Header

Documentation Installation
You can download the product documentation using the Software AG Installer. The
documentation is downloaded to a central directory named _documentation in the main
installation directory (SoftwareAG by default).

Online Information
You can find additional information about Software AG products at the locations listed
below.

If you want to... Go to...

Access the latest version of product Software AG Documentation website

documentation.
hp://
documentation.softwareag.com

Find information about product releases Empower Product Support website

and tools that you can use to resolve
hps://empower.softwareag.com
problems.
See the Knowledge Center to:
Read technical articles and papers.
Download fixes and service packs (9.0
SP1 and earlier).
Learn about critical alerts.
See the Products area to:
Download products.
Download certified samples.
Get information about product
availability.
Access older versions of product
documentation.
Submit feature/enhancement requests.

Access additional articles, demos, and Software AG Developer Community for

tutorials. webMethods

REST Developer’s Guide Version 9.6 6

 M  
Odd Header

If you want to... Go to...

Obtain technical information, useful hp://

resources, and online discussion forums, communities.softwareag.com/
moderated by Software AG professionals,
to help you do more with Software AG
technology.
Use the online discussion forums to
exchange best practices and chat with
other experts.
Expand your knowledge about product
documentation, code samples, articles,
online seminars, and tutorials.
Link to external websites that discuss
open standards and many web
technology topics.
See how other customers are streamlining
their operations with technology from
Software AG.

REST Developer’s Guide Version 9.6 7

 M  
Even Header

REST Developer’s Guide Version 9.6 8

 M  
Odd Header

1   About Integration Server REST Processing

■ Overview ....................................................................................................................................... 10

REST Developer’s Guide Version 9.6 9

 M  
Even Header

Overview
Representational State Transfer (REST) is an architectural style used to build distributed
hypermedia systems. The World Wide Web is the best known example of such a system.
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 GET, POST, PUT, and DELETE 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 all four methods.

REST Developer’s Guide Version 9.6 10

 M  
Odd Header

Integration Server can be a REST server or a REST client. When Integration Server
acts as a REST server, it hosts an application that you write. The application includes
services that you write that instruct Integration Server to process some or all of the
HTTP GET, POST, PUT, and DELETE methods in request messages against resources.
When Integration Server acts as a REST client, it sends specially formaed requests to
the REST server.

REST Developer’s Guide Version 9.6 11

 M  
Even Header

REST Developer’s Guide Version 9.6 12

 M  
Odd Header

2   How REST Processing Works

■ About REST Request Messages ................................................................................................. 14
■ How webMethods Integration Server Processes REST Requests .............................................. 14
■ Sending Responses to the REST Client ..................................................................................... 16

REST Developer’s Guide Version 9.6 13

 M  
Even Header

About REST Request Messages

REST clients send specially formaed 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
A simple REST request looks like this:
METHOD /directive/resource_type/resource_id HTTP/1.1

Where... Is the...

METHOD HTTP request method.

directive The type of processing to perform.

resource_type/ Resource to act upon.

resource_id

More complex request messages can contain more explicit information about the
resource.

How webMethods Integration Server Processes REST

Requests
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. On
Integration Server the resources of your application are represented as folders within
a package. For each resource, you will write individual services for the HTTP methods
that you want Integration Server to execute against the resource. Those services must be
named _get, _post, _put, and _delete, and they are stored in the folder for the resource.
For more information, see"Services" on page 20.
Consider a Discussion application that maintains a database of discussions about
different topics. The following examples show how Integration Server would parse these
REST requests.
Example 1

REST Developer’s Guide Version 9.6 14

 M  
Odd Header

Here is a request to obtain a list of all topics contained in the database, and how
Integration Server would parse the request:
GET /rest/discussion/topic HTTP/1.1

Where... Is the...

GET Type of HTTP method to perform. Integration Server maps

this value to the corresponding service on Integration Server,
in this case, the _get service.

rest Type of processing to perform, in this case, Integration Server

REST processing.

Note: For more information about directives, see webMethods

Integration Server Administrator’s Guide.

discussion/topic Location of the _get service for this resource on Integration

Server. In this example, the _get service resides in the topic
folder in the discussion folder (discussion.topic).

Example 2
Here is a request to display information about topic number 3419, and how Integration
Server would parse the request:
GET /rest/discussion/topic/3419 HTTP/1.1

Where... Is...

3419 An instance of a resource passed into a service as the

$resourceID variable. In the example, the $resourceID variable
narrows the focus of the GET request to topic 3419.

Note: Integration Server assigns the first token after the folder(s)
to the $resourceID parameter. To determine whether a token
represents a folder or the $resourceID , Integration Server
looks in the current namespace for a folder that has the same
name as the token. If it does not find a folder with this name,
Integration Server assigns the token to the $resourceID variable.
In other words, the first token (after the directive) that does not
correspond to a folder becomes the $resourceID .

Example 3
Here is a request to display information about a particular comment, 17 for example,
and how Integration Server would parse the request:

REST Developer’s Guide Version 9.6 15

 M  
Even Header

GET /rest/discussion/topic/3419/comment/17 HTTP/1.1

Where... Is...

comment/17 Additional information that further narrows the information

about the resource. This information is passed into a service as
the $path variable. In the example, comment/17 further narrows
the focus of the GET request to comment 17.

Example 4
Here is a request to display information contributed by participant Robertson in 2009
about topic 17, and how Integration Server would parse the request:
GET /rest/discussion/topic/3419/comment/17?year=2009&name=Robertson HTTP/1.1

Where... Are...

year and name Input variables that are specific to your application. Tokens
specified after the ? must be entered as name/value pairs. In
this example, year=2009 and name=Robertson narrow the focus
of the GET request to entries that participant Robertson added
to comment 17 in 2009.

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 will always set the HTTP version to match the version of the client
that issued the request. You cannot change the HTTP version.
You can, however, use the pub.flow:setResponseCode service to set the status code and
reason phrase. For more information about this service, refer to 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 hp://www.w3.org/Protocols/
rfc2616/rfc2616-sec10.html#sec10. Examine these codes to determine which are
appropriate for your application.

REST Developer’s Guide Version 9.6 16

 M  
Odd Header

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. For
more information about this service, refer to 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.3
You can use the pub.flow:setResponse service to explicitly set the message body. See the
webMethods Integration Server Built-In Services Reference for details. 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.
For more information about how Integration Server builds HTTP responses, refer to the
section that describes how Integration Server chooses content handlers in webMethods
Integration Server Administrator’s Guide.

REST Developer’s Guide Version 9.6 17

 M  
Even Header

REST Developer’s Guide Version 9.6 18

 M  
Odd Header

3   Setting Up Your REST Application

■ Setting Up a REST Application on Integration Server ................................................................. 20
■ Converting an Existing Application .............................................................................................. 22

REST Developer’s Guide Version 9.6 19

 M  
Even Header

Setting Up a REST Application on Integration Server

Integration Server can act as a REST server or REST client. For Integration Server to act
as a REST server, it must host services that perform the GET, PUT, POST, and DELETE
methods. These services, which you provide, perform processing that is specific to your
application. For example, the service you write to perform the GET method might access
your application database, perform a query, and return a result.

Services
When you build a REST application on your Integration Server, you must include
services that correspond to the HTTP methods you want to provide for each resource.
These services must be named as follows:

Service Description

_get Performs the GET method.

_put Performs the PUT method.

_post Performs the POST method.

_delete Performs the DELETE method.

These services reside in folders on your Integration Server in a directory structure that
is specific to your application. For example, the Discussion application described above
might have the following structure as viewed from Software AG Designer:

In addition to the _get, _put, _post, and _delete services, you can also place a special service
named _default in one or more of the application folders. Integration Server executes
this service if a REST request specifies an HTTP method that is not represented by a
service in the folder. For example, suppose the folder contains the _get, _put, and _post
services, but no _delete service. If the client issues a DELETE request, Integration Server
will execute the _default service, and pass “DELETE” to it in the $hpMethod variable.

REST Developer’s Guide Version 9.6 20

 M  
Odd Header

If a request specifies an HTTP request method that is not represented by a service in the
folder and there is no _defaultservice in the folder, the request fails with error “404 Not
Found” or “405 Method Not Allowed.” Integration Server issues 404 if the first token in
the URI does not exist in the namespace, or 405 if one or more tokens in the URI identify
elements in the namespace but the URI does not correctly identify a folder and a service
to execute.
Example 1
A resource’s folder contains the _get, _post, and _default services:

If the client sends a... Integration Server responds by...

GET request Executing the _get service

POST request Executing the _post service

DELETE request Executing the _default service

Example 2
A resource’s folder contains the _get, _put, and _delete services:

If the client sends a... Integration Server responds by...

GET request Executing the _get service

PUT request Executing the _put service

POST request Issuing error “405 Method Not Allowed”

Additional possible uses for the _default service are:

Direct all REST requests through common code before branching off to individual
GET, PUT, POST, or DELETE methods.
Make PUT and POST processing the same by directing PUT and POST requests to
the same code.

Configuration
There are a few things you can configure with respect to REST processing:
Name of the REST directive
If you want to allow clients to specify a name other than “rest” for the REST
directive, you can do so with the wa.server.RESTDirective configuration parameter.

REST Developer’s Guide Version 9.6 21

 M  
Even Header

For example, to allow clients to specify “process” for the REST directive, you would
change the property to the following:
watt.server.RESTDirective=process

With this seing, clients can specify “rest” or “process” for the REST directive. In the
following example, the two requests are equivalent:
METHOD /process/discussion/topic/9876 HTTP/1.1

METHOD /rest/discussion/topic/9876 HTTP/1.1

For more information about the wa.server.RESTDirective property, refer to

webMethods Integration Server Administrator’s Guide.
Which ports will accept the rest 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 wa.server.allowDirective configuration parameter. For more information about
this property, refer to the webMethods Integration Server Administrator’s Guide.

Converting an Existing Application

If you have an existing application that you want to transform into a REST application,
one approach is to refactor your existing services into _get, _put, _post and _delete services.
There is, however, another approach that might be faster and easier.
The invoke directive, like the rest directive, supports the GET, PUT, POST, and DELETE
methods. For existing applications that use the invoke directive, you can update
a service to call the pub.flow:getTransportInfo service and then perform a branch on /
transport/http/method to execute the appropriate portions of your existing code, as in
the following example:

Note, however, that if you use the invoke directive instead of the rest directive, you
cannot take advantage of these REST-specific features:
$resourceID pipeline variable
$path pipeline variable
_default service

REST Developer’s Guide Version 9.6 22

 M  
Odd Header

4   Documenting Your Rest Application

■ Providing Information About Your Application .............................................................................. 24

REST Developer’s Guide Version 9.6 23

 M  
Even Header

Providing Information About Your Application

It is important to document your REST application so that your customers and partners
will be able to build clients that interact with it correctly. Your documentation should
cover how to:
Send requests to your application
Handle responses from your application
The following sections describe the different areas your documentation should cover.

General Information
Include the following general information about your application:
A list of resource types
In the sample Discussion application described above, resource types would be
discussion and topic.
The HTTP methods your application supports for each resource
In the sample Discussion application, the discussion resource supports GET, but the
topics resource supports DELETE, GET, POST, and PUT.

Information About Each Request

Include the following information about each request:
The format of the request URL
For example, documentation for the Discussion application could provide a list of
possible client requests:
Return general information about the Discussion application:
GET /rest/discussion HTTP/1.1

Return a list of all topics contained in the database:

GET /rest/discussion/topic HTTP/1.1

Display entries made by participant Robertson in 2009 to topic 3419:

GET /rest/discussion/topic/3419?year=2009&name=Robertson HTTP/1.1

Which request header fields are required or optional and how your application
responds to them. For example, the Discussion application might specify the
following information to explain which header fields it accepts and how it responds
to them:

REST Developer’s Guide Version 9.6 24

 M  
Odd Header

Authorization. The Discussion application accepts BASIC and DIGEST

authorization. All requests must include an Authorization header.
Content-Type. Clients should include a Content-Type header with all requests.
Acceptable Content-Type values for requests that contain a body are application/
json, text/xml, text/html, and text/plain. For more information about Content-
Types, see webMethods Integration Server Administrator’s Guide.
Accept. Clients can optionally supply an Accept header to indicate the Content-
Type they want the response to use. When you specify the Content-Type for the
Accept header, Integration Server uses the content handler registered to that
Content-Type to respond to the request. For example, if the content handler
is application/json, Integration Server responds to the request with JSON
content. Acceptable values are application/json, text/xml, and text/html. If no
Accept header is specified in the request, the response will use text/xml. For
more information about the Accept header, see webMethods Integration Server
Administrator’s Guide.
Whether a body is required and what structure the body should have.
Documentation for the Discussion example might provide the following examples to
illustrate body structure:
Example 1: Creating a new topic
Request:
POST /discussion/topic HTTP/1.1
Host: IS_server:5555
Authorization: BASIC <your-credentials>
Content-Length: <request-body-length>
Content-Type: text/xml; charset=utf-8

Response: If the request was valid, the Discussion application will respond with the
following:
HTTP/1.1 201 Created
Content-Length: 0
ETag: 32619
Location: http://host/discussion/topic/32619

Example 2: Adding an entry to an existing topic

Request:
PUT /discussion/topic=36219 HTTP/1.1
Host: IS_server:5555
Authorization: BASIC <your-credentials>
Content-Length: 17
Content-Type: text/xml; charset=utf-8
comment=I+agree

Response: If the request was valid, the Discussion application will respond with the
following:
HTTP/1.1 200 OK
Content-Length: 0
Location: http://host/discussion/topic/36219?comment=2

REST Developer’s Guide Version 9.6 25

 M  
Even Header

Information About Responses

Your documentation should include the following to describe the response that
corresponds to each request:
A list of HTTP Status-Codes and Reason-Phrases the application returns and the
circumstances under which it returns them. For a list of possible responses that you
can code your application to return, refer to hp://www.w3.org/Protocols/rfc2616/
rfc2616-sec10.html#sec10.2.
A list of the response header fields you return and what they mean in the context of
your application.
A description of what will appear in the body of the response.

REST Developer’s Guide Version 9.6 26

 M  
Index

Index request parsing 14

supported HTTP request methods 10
REST request messages 14
A REST server
application services 20 setting up on Integration Server 20, 20

C S
configuration 21 status line of response to REST client 16
converting an existing REST application 22
Symbols
D $httpMethod input variable 20
documentation $path input parameter 16
using effectively 5 $resourceID input parameter 15
documenting your REST application 24 _default service 20
_delete service 20
H _get service 20
header fields of response to REST client 17 _post service 20
HTTP request methods _put service 20
supported 10

I
invoke directive 22

M
message body of response to REST client 17

P
processing directives
invoke 22
rest 14, 22

R
request messages
format 14
response to REST client
header fields 17
message body 17
status line 16
REST application
directory structure 20
setting up on Integration Server 20
REST application services 20
rest directive 14
alternative name for 21
REST processing
input parameters 14
passing input to application services 14
request format from REST perspective 14

REST Developer’s Guide Version 9.6 27