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
|
|
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.
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.
|
| |
