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:
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, application/xml, 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, application/xml, 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
