Zend Server WebAPI spotlight: WebAPI 101

December 16, 2013

Zend Server

Hey everybody,

My name is Yonni Mendes. I’m the Technological Lead for the Zend Server UI and WebAPI. I’ve been with Zend Server 6 since it was a spark in a product manager’s eye. I’m happy to have seen Zend Server 6 go through planning, design, development and deployment.

This is the first in a series of posts about the Zend Server WebAPI. In this series we will go over the WebAPI’s capabilities and what you can expect from process automation in Zend Server. Before we dig into the obscure corners of the Zend Server WebAPI, I should probably tell you a little about this system in general.

Welcome to the Zend Server WebAPI

The Zend Server WebAPI is reflected in everything our UI does. Practically anything you see in the UI can be done, at least to some degree, through the Zend Server WebAPI. Few are the cases where the UI resorts to bypassing the WebAPI and uses a privileged action to achieve some display goal.

The Zend Server WebAPI is accessible in a few ways but all of them rely on the same basic method – an HTTP request to a Zend Server WebAPI action. This central gateway goes through a uniform authentication process. The server then initiates the desired WebAPI action which will be executed like any other ZF2 controller/action request. This request then renders an output – in JSON or XML, which is sent to client to be consumed.

Words to actions

We can see this process with the following script.
Note that this is a sytnax synopsis for a ZF2 http client.

$client = new \Zend\Http\Client();
$client->setUri('http://<host>:10081/ZendServer/Api/<action>')
 ->setEncType(\Zend\Http\Client::ENC_FORMDATA)
 ->setMethod('<POST|GET>')
 ->setHeaders(array(
   'User-Agent' => 'Zend the first',
   'Date' => gmdate('D, d M Y H:i:s') . ' GMT',
   'X-Zend-Signature' => "<key-name>;<signature>",
   'Accept' => 'application/vnd.zend.serverapi...
       ...[+<xml|json>][;version=<version-number>]'
))

A few interesting things can be observed in this snippet of code, particularly the headers:

X-Zend-Signature is a custom http header which contains the webapi request credentials. key-name is the webapi key’s identifier, which is provided by Zend Server. This identifier is similar in idea to a username (Zend Server produces a key called “admin” during bootstrap for you). The signature field contains a cryptographic signature of the other headers to authenticate the request. This hash is keyed using the secret webapi key that is provided with the key-name. Read on to see how a signature is actually produced, it’s crazy-simple.

The Accept header describes a vendor specific content-type for the Zend Server WebAPI. This type can include the output (xml or json) and a particular version to access. If no version is specified, version negotiation will attempt to find the earliest available version which supplies the desired webapi action.

Note that the Zend Server WebAPI provide an alternative X-Accept header that can be used to specify the vendor type in the same way, in case the Accept header cannot be modified in your client. Should you not provide an Accept or X-Accept headers, the request will not be considered a Zend Server UI Request and be directed to the UI … which will probably respond with an error.

Date and User-Agent are also specified because they are to be used by the signature’s hashing process and so must be passed to the server. Note that Date has a very specific format – provided above in the example.

Producing a signature

To produce a signature, you will need a few things:

  • Header values for Date and User-Agent headers
  • Host and Path parts of the URI
  • The WebAPI\SignatureGenerator class (or something that behaves similarly)

Note: you can find the SignatureGenerator class in
<zend-server>/gui/module/WebAPI/src/WebAPI/SignatureGenerator.php

Creating a Zend Server WebAPI signature

Creating a signature is easy: Set the different headers and URI values using their corresponding setters into the SignatureGenerator object. Once the object was initialized, hit the hash() method. The result will be a 40 characters-long signature hash which will be effective for the next few minutes for the particular request you specified. Insert this signature string into the X-Zend-Signature header, fire the request away.

Depending on the WebAPI action you’ve chosen, you will receive some form of output or an error. Errors are handled uniformly, meaning that when an error is returned from the Zend Server WebAPI you will always receive the same structure of error.

Congratulations! By performing these steps you have now gained access to Zend Server’s WebAPI. Check out our extensive documentation for the WebAPI to get an idea of the capabilities we provide.

In the coming weeks I will expand on specific topics and actions provided by the Zend Server WebAPI, feel free to suggest topics that interest you in comments.

,

About YonmaN

Yonni Guido Mendes is a seasoned developer and integration expert who's been writing PHP for the past 12 years. He's worked on websites, billing, external integration and user interfaces on different platforms and in varying methodologies. Yonni is also a father, a gamer and a technophile.

View all posts by YonmaN

Trackbacks/Pingbacks

  1. Zend Server WebAPI spotlight: Asynchronous Actions « DevelopersArena.com - December 26, 2013

    […] the previous Spotlight, we took a look at the basic steps of connecting to and using the Zend Server WebAPI. Many of the […]

Leave a Reply

You must be logged in to post a comment.