HTTP method reference for CICS web support

HTTP requests include a method, which is a keyword explaining the action that the client wants the server to perform for the material included in the request. CICS® web support implements all the standard request methods defined by the HTTP/1.1 specification, and some additional methods that were accepted in earlier CICS releases.

For detailed guidance on the correct use of methods and the correct actions in response to them, and information on applicable requirements, always consult the HTTP specification to which you are working.
  • For requests received from HTTP/1.1 web clients (when CICS is an HTTP server), the standard methods defined by the HTTP/1.1 specification are accepted. These methods are GET, HEAD, POST, PUT, OPTIONS, and DELETE.
  • For requests received from HTTP/1.0 web clients and earlier (when CICS is an HTTP server), the methods defined by the HTTP/1.0 specification, and some additional methods, are accepted:
    • The methods defined by the HTTP/1.0 specification are GET, HEAD, and POST.
    • The additional methods accepted on HTTP/1.0 requests inbound to CICS are PUT, DELETE, LINK, UNLINK, and REQUEUE.
  • For requests made by CICS as an HTTP client:
    • The standard methods defined by the HTTP/1.1 specification can be used. These methods are GET, HEAD, POST, PUT, OPTIONS, and DELETE.
    • The LINK, UNLINK, and REQUEUE methods are not supported for this purpose.
    • The version of the request is always given as HTTP/1.1.
    • Some HTTP/1.0 servers may accept methods that are not defined in the HTTP/1.0 specification. An HTTP/1.0 server should return the status code 501 Not Implemented for methods that it cannot accept.
  • Message bodies are appropriate for some request methods and inappropriate for others.
    • For CICS as an HTTP server, you should be aware that some clients (particularly user-written clients) might send a message body for a method where it is not appropriate, and you can handle or ignore this as you choose.
    • For CICS as an HTTP client, CICS bars the sending of a message body for methods where it is inappropriate, and requires it for methods where it is appropriate.
  • When CICS is an HTTP server, for requests received from a web client, CICS web support takes a range of actions in response to the method, depending on the method and the HTTP version of the client.
    • Requests with most methods are passed directly to the application program for handling.
    • CICS automatically returns appropriate responses for the OPTIONS method, without calling a user application program.
    • If a method is not implemented at the HTTP version for the request, CICS returns an error response to the web client, without calling a user application program.
  • In addition to the standard request methods defined in the HTTP specifications, nonstandard request methods, known as extension methods, might be implemented by some servers.
    • For CICS as an HTTP server, CICS web support does not accept requests with nonstandard methods on the HTTP protocol. (Before CICS Transaction Server for z/OS®, Version 5 Release 4, these requests were accepted and processed as non-HTTP.) If you need to receive requests with nonstandard methods, this can be done with the user-defined protocol (USER option on the TCPIPSERVICE definition), where HTTP acceptance checks do not take place.
    • For CICS as an HTTP client, you cannot use nonstandard methods on EXEC CICS WEB API commands.

The tables in this reference list the circumstances in which each method may be used. Consult the HTTP specification to which you are working, for more detailed guidance about the methods mentioned in this reference.

CICS as an HTTP server: Handling request methods received from a web client

Table 1 shows the actions that CICS takes for request methods, and the actions suggested for a user application program. It is important to check the HTTP specification to which you are working, for detailed guidance and any relevant requirements.

Table 1. CICS as an HTTP server: Request methods received from a web client
Method CICS action with HTTP/1.0 client CICS action with HTTP/1.1 client Message body appropriate on request? Suitable action by user application program
GET (Request for resource) Accepted. Request passed to application. Accepted. Request passed to application. No Send resource to the web client, or send an error response explaining why you cannot do this.
HEAD (Request for response headers) Accepted. Request passed to application. Accepted. Request passed to application. No Send resource to the web client exactly as if responding to a GET request for the same resource. CICS removes response body to leave only headers.
POST (Send input data) Accepted. Request passed to application. Accepted. Request passed to application. Yes Support for method is optional. Extract data (which might be form fields), process it and send a response to the web client. May also be used for changing or creating a resource, in which case handle as for a PUT request.
PUT (Send new item) Accepted. Request passed to application. Accepted. Request passed to application. Yes Support for method is optional. If request is valid, create a resource with the specified URL using the content of the message, or replace your existing resource with the content of the message, as appropriate. Send an acknowledgment to the web client. The HTTP/1.1 specification has detailed requirements for correct operation.
Tip: This request type is unlikely to be applicable for your CICS web support implementation. If wanted, it could be fulfilled by creating a URIMAP definition for the specified URL, and storing the resource to be provided as a static response.
TRACE (See request's path and final state) Rejected with status code 501 Not Implemented. No user application called. Rejected with status code 501 Not Implemented. No user application called. No Not passed to user application.
OPTIONS (Request for information about server) Rejected with status code 400 Bad request. No user application called.

CICS supports OPTIONS without a path. In this case, CICS accepts and responds to OPTIONS * requests without a handler and no user application is called.

CICS supports OPTIONS with a path only if an OPTIONS handler program has been specified by feature toggle com.ibm.cics.http.options.handler. In this case, CICS accepts and responds to OPTIONS requests by invoking the specified handler program. The handler is responsible for sending a response to the client.

If the feature toggle is not specified, requests specifying OPTIONS with a path are rejected with 405.

 Undefined Not passed to user application. When no handler has been specified, CICS returns response with basic information (the HTTP version and server software description). If a handler has been specified, the handler is invoked and is responsible for responding to the client.
DELETE (Delete resource) Accepted. Request passed to application. Accepted. Request passed to application. No Support for method is optional. If request is valid, delete your existing resource, and send an acknowledgment to the web client.
LINK, UNLINK, REQUEUE Accepted. Request passed to application. Rejected with status code 501 Not Implemented. No user application called. Undefined Use not recommended, as not described in HTTP/1.1 specifications. For compatibility, HTTP/1.0 request is still passed to application.

CICS as an HTTP client: Using methods on requests to a server

Table 2 lists the request methods supported by the CICS API for HTTP client requests, and summarizes the correct use of the methods. For guidance on the correct use of each method, and any requirements that apply to an HTTP client using the method, check the HTTP specification to which you are working.

Table 2. CICS as an HTTP client: Request methods sent to a server
Method Send to HTTP/1.0 server? Send to HTTP/1.1 server? Message body on request? Purpose
GET (Request for resource) Yes Yes No Obtain a resource from the server.
HEAD (Request for response headers) Yes Yes No Obtain the headers for a resource from the server. Enables you to check on the nature, status or size of the resource without having to retrieve the whole body.
POST (Send input data) Yes Yes Yes Send data to a server. For example, form data might be sent in this way. Servers are not required to support this method.
PUT (Send new item) Might not be supported by server. Yes Yes Create or modify a resource on the server. The URL for your request is the URL that the resource has on the server. The request can be used to update an existing item or to create a new item. Servers are not required to support this method.
TRACE (See request's path and final state) Might not be supported by server. Yes No Obtain a response showing the final state of your request and the path it took to the server (shown in the Via header). You can see what proxy servers are being used to handle your request. Servers are not required to support this method.
OPTIONS (Request for information about server) Might not be supported by server. Yes Allowed, but no purpose defined for it at present. Obtain information about the server. Apply the request to the whole server by specifying * (asterisk) as the request path, or specify a full request path to get information about that resource. Servers are not required to support this method.
DELETE (Delete resource) Might not be supported by server. Yes No Delete a resource on the server. The request URL is the URL of the item to be deleted. Servers are not required to support this method.
LINK, UNLINK, REQUEUE, and extension methods generally Not permitted. INVREQ response returned and request not sent. Not permitted. INVREQ response returned and request not sent. Undefined Not available on WEB API for CICS as an HTTP client.