Request Format

The request format defines the required format for each request sent to Zend Server. The request format for all Zend Server Web API requests are formatted as described in this page, regardless of the specific method used.

Request Method, URL, and Headers

Web API HTTP requests use HTTP GET for read-only API calls, and HTTP POST for all state changing API calls.

The request URL is different for each action, and is in one of the following formats:

Zend Server - Where <ACTION> is the action to perform (e.g. “disableServer”):

http://example.com:10081/ZendServer/Api/<ACTION>

All HTTP requests must include the following HTTP headers:

Date - Contains the current date and time in the GMT time zone, in the format specified by the HTTP RFC for date fields (e.g. “Wed, 07 Jul 2010 17:10:55 GMT”). This value is used to verify the authenticity of the request, and is expected to be in sync with the server time (within 30 seconds).
User-agent - The user agent string is logged by the server and used for message authenticity verification. It cannot be empty.
Host - The HTTP host header is expected to be present and is used for message authenticity verification.
X-Zend-Signature - The API key name and calculated request signature which is used to authenticate and validate the request. See Authentication and Message Verification for additional information on calculating the signature.

In addition, you should send the Accept HTTP request header to designate your supported API version(s). If the Accept header is missing, the server will fall back to the default API version. This is described in detail in API Versioning Negotiation.

For POST requests, including any parameters or payload, clients must set the Content-type header to either "application/x-www-form-urlencoded" or "multipart/form-data", depending on the payload. You must specify the size of the request body as required by the HTTP/1.1 protocol, that is by using the Content-length header, the Content-transfer-encoding: chunked header or simply by closing the connection.

Passing Request Parameters

API methods that require passing parameters may be passed in the following forms:

For GET requests, parameters are passed in the URL query part (following the ‘?’) in a URL-encoded format, similar to how HTML forms sent using the GET method are encoded.
For POST requests, parameters should be passed in the request body, encoded using either the "application/x-www-form-urlencoded" (as specified by the HTML 4.01 standard) or "multipart/form-data" (as specified in RFC-2388) encoding methods.
For some methods (namely methods that may transfer large amounts of binary data), the ‘multipart/form-data’ encoding method must be used.

Refer to specific method documentation for a list of required and optional parameters.

Examples

Usage Example

Figure 1. The following is an example of a call to the (obviously fake) “makePizza” method (some lines are broken for readability):

POST /ZendServer/Api/makePizza HTTP/1.1
Host: zscm.local

Date: Sun, 11 Jul 2010 13:16:10 GMT

User-agent: Zend_Http_Client/1.10
Accept: application/vnd.zend.serverapi+xml;version=1.0

X-Zend-Signature: bob.at.example.com;
7f0db29a3d82a81ec6f5387f5aae96e295530b4c8acf2074488185902dc900f4
Content-type: application/x-www-form-urlencoded
Content-length: 100
style=thinCrust&extraCheese=TRUE&extras%5B0%5D=pepperoni&extras%5B1%5D=onion&extras%5B2%5D=pineapple

The request above is for the “makePizza” method, with the following parameters: style, extraCheese, extras.

Figure 2. The following example shows a call to a read-only “getPizzaStatus” method:

GET /ZendServer/Api/getPizzaStatus?pizzaId=53 HTTP/1.1
Host: zscm.local|
Date: Sun, 11 Jul 2010 13:16:10 GMT
User-agent: Zend_Http_Client/1.10
Accept: application/vnd.zend.serverapi+xml;version=1.0
X-Zend-Signature: bob.at.example.com;
02dcbf4cb338a0a8b807c83a84a7888929f5c06491105d6752f290da47a24619

Notice that the ‘pizzaId’ parameter is passed as part of the URL’s query string.