PowerPoint Presentation

Pick Your Protocol
Creating Web Services
with Zend Framework

Matthew Turland
September 17, 2008

Everyone acquainted?

Lead Programmer for surgiSYS, LLC

ZCE, ZFCE, and Zend Framework contributor

Blog: http://ishouldbecoding.com

You're probably wondering...

... what you're doing here this early in the morning.

Web services? Anyone? Anyone?

According to the W3C, "a software system designed to support interoperable machine-to-machine interaction over a network."

This by itself is vague. The remainder of the definition gets into specifics about SOAP, which is too exclusive.

What are web services?

For our purposes, web applications implementing communication standards for receiving requests from other web applications to return or operate on data.

Automate interactions between software systems that would otherwise require (more) human intervention.

Scapegoat for the existence of a number of acronyms in today's IT industry. More on these shortly.

What is Zend Framework?

Open source web application framework for PHP 5.

Sponsored by Zend Technologies.

Technology partners include IBM, Google, and Microsoft.

Developed by Zend and volunteers since 2005.

Great way to develop web services regardless of the implementation method you want to use.

What We're Covering

Implementation of HTTP authentication to restrict access to web services.

Background information on commonly used standards and methodologies for development of web services.

Timely details on the state and use of Zend Framework components used to accelerate web service development.

HTTP Authentication

Extension of the HTTP protocol used for identity authentication as described in RFC 2617.

Sees limited use in access control implementations for web services and general web applications.

Two flavors: Basic and Digest. The latter implements more measures for security than the former, but is less commonly used.

Less often used than implementing authentication at the application level using request parameters for receiving authentication credentials.

HTTP auth can often be implemented at the web server level depending on the desired resolver.

Zend_Auth_Adapter_Http

Offers support for Basic and Digest authentication schemes and authentication via local and proxy servers.

Some Digest features, such as nonce tracking for stale support, are not implemented yet.

Uses resolvers to authenticate provided credentials against a data source.

Uses a file-based resolver by default and offers an interface to implement custom resolvers.

Server will challenge client with all schemes and client can respond with any it supports.

An example of a custom resolver is one that uses a database.

File Resolver Formats

Format is the same for both Basic and Digest schemes, but supplied data differs between schemes.

Basic
[$username]:[$realm]:[base64_encode($password)]

Digest
[$username]:[$realm]:[md5($username . ':' . $realm . ':' . $password)]

Digest currently only supports the MD5 hashing algorithm. Support for other algorithms may be added in the future.

Configuration

$basicResolver = new Zend_Auth_Adapter_Http_Resolver_File('path/to/file');

$adapter = new Zend_Auth_Adapter_Http(array(

'accept_schemes' => 'basic',
'realm' => '[Web Service Name]'

));

$adapter // request and response are from controller
->setRequest($this->_request)
->setResponse($this->_response)
->setBasicResolver($basicResolver);

Use Case

// Pulls authentication credentials from the request

$result = $adapter->authenticate();

if (!$result->isValid()) {

$errors = $result->getMessages();

} else {

$identity = $result->getIdentity();

}

HTTP Resources

RFC 2616 HyperText Transfer Protocol

RFC 3986 Uniform Resource Identifiers

"HTTP: The Definitive Guide" (ISBN 1565925092)

"HTTP Pocket Reference: HyperText Transfer Protocol" (ISBN 1565928628)

"HTTP Developer's Handbook" (ISBN 0672324547) by Chris Shiflett

Ben Ramsey's blog series on HTTP

Common Server Components

Zend_Server_Interface "enforces" the use of the SoapServer API on server classes.

Zend_Server_Reflection extends the PHP 5 Reflection API to add various features used in server introspection for delivering API metadata to clients.

Zend_Server_Abstract is likely to be deprecated or significantly refactored in future releases.

Zend_Server_Reflection additions include retrieval of parameter and return value types and descriptions as well as function and method prototypes and descriptions.

Zend_Server_Abstract currently does very little and is only in use by Zend_Rest_Server and Zend_Soap_AutoDiscover (only in the sense that it extends it, doesn't really do much else with it).

Acronym #1

REST: REpresentational State Transfer

Born in 2000 in the dissertation of Roy Fielding, a principal author of the HTTP specification.

Not tied to a specific protocol, but most often implemented on an HTTP server.

A collection of network architecture principles centered around resources and operations to facilitate transfer of state between clients and servers.

Fielding presented REST as an alternative to other distributed computing specifications such as CORBA (Common Object Request Broker Architecture).

He has also been involved in the development of HTML and URIs, was a cofounder of the Apache HTTP Server project, and was a member of the interim OpenSolaris Boards.

He is currently working on a new protocol called Waka intended to be a binary token-based replacement for HTTP.

What's a resource?

Source of specific information in a particular format (known as its representation).

Platform-independent machine equivalent of a noun.

Referred to using Universal Resource Identifiers or URIs.

A client can interact with a resource by knowing its URI, the operation to perform, and how to interpret the returned resource representation.

Multiple URIs per logical resource is allowed, but one is more desirable. The former is not considered to be un-RESTful so long as one of the URIs is considered canonical.

Operations

HTTP

POST

GET

PUT

DELETE

CRUD

Create, Update, Delete

Retrieve

Create, Delete/Create

Delete

PUT is generally used to overwrite or replace an existing resource.

Representations

Anything with an associated MIME type.

A single resource can have multiple representations.

Content negotiation allows the client to indicate what representations it supports and prefers.

Some web services add a request parameter or extension to the resource URI to indicate the requested representation. Not very RESTful, but easier to use.

MIME type is included in the Content-Type header of the server response.

Best approach is likely one generic resource for content negotiation with additional URIs that point to specific representations for ease of use.

Twitter is an example of an API that uses extensions to indicate the desired representation. (i.e. XML, JSON, RSS, Atom)

Still don't get it?

REST is not a standard, protocol, or architecture so much as an architectural style or set of design principles.

Check out "RESTful Web Services" by Leonard Richardson and Sam Ruby, ISBN 0596529260.

Keep listening, contrasts later on in this presentation may make the nature of REST more clear.

Zend_Rest_Server

Exposes normal functions and class methods for remote invocation.

Can return or directly output return values of the exposed functions and methods.

Supports output of DOMNode, DOMDocument, and SimpleXMLElement return values.

Non-XML return types are converted to XML using DOM.

Sound strange?

Only HTTP methods supported are GET and POST, so it ends up being more like "REST-RPC" than REST.
(Ben Ramsey has a good blog post on this.)

XML output is assumed, which makes the class inflexible toward other representations (ex: JSON via Zend_Json).

Very sparse documentation.

$server = new Zend_Rest_Server();

$server->addFunction('someFunctionName');

$server->addFunction('someOtherFunctionName');

$functions = $server->getFunctions();

$server->setClass(

'Some_Class_Name',

null, // namespace from Zend_Server_Interface

$args // for Some_Class_Name::__construct()

);

$server->handle($request); // $request = $_REQUEST

$server->returnResponse(true);

$return = $server->handle($request);

Show me the code!

Don't bother with these...

// They either are stubs or they may as well be.

$server->setEncoding('UTF-8');

$encoding = $server->getEncoding();

$server->loadFunctions($functions);

$server->setPersistence($mode);

$headers = $server->getHeaders();

Alternative Approach

Zend_Rest_Server is likely to be on the chopping block in the 2.0 branch. Don't use it for new projects and make it a long-term goal to migrate existing projects using it.

Use Zend Framework MVC features together with the ContextSwitch action helper to vary the returned resource representation.

Keep an eye out for new developments to support REST services.

RESTful Routing

Default routes in the rewrite router offer no standard conducive toward the REST approach.

Zend_Controller_Router_Route_Rest is a new (as in not-yet-approved) proposal by Luke Crouch to implement a common URI-to-action mapping for RESTful web services.

Zend_Rest_Client

Lightweight wrapper for Zend_Http_Client geared toward consuming REST-based services.

Can be used to implement automated test suites for application components that use Zend_Rest_Server.

__call() implementation follows suit with the REST-RPC style of the server component.

Using Zend_Http_Client itself is likely a better idea.

REST Demo

Check my blog for slides and demo source code after the conference.

Acronym #2

XML-RPC: eXtensible Markup Language Remote Procedure Call

Created by Dave Winer of UserLand Software in 1998 in conjunction with Microsoft.

RPC model using XML as its data exchange format and HTTP as its data transport protocol.

Intended to be a simple, minimalistic, and easy to use protocol.

One distinctive trait of XML-RPC is that it is the only standard with native procedure namespacing support.

What is XML?

eXtensible Markup Language

General-purpose spec for creating custom markup languages (ex: XHTML, RSS, Atom, SVG).

Fee-free W3C-recommended open standard.

Primary purpose is to help information systems share structured data.

I know XML

What is RPC?

Remote Procedure Call

Originated in 1976 in RFC 707.

Also referred to as remote (method) invocation.

General term for the ability of a computer program to execute a subroutine in a remote address space.

Popular paradigm for implementation of the client-server model of distributed computing using message passing.

REST versus RPC

REST

Nouns

Principles

Architecture

Generally atomic

RPC

Verbs

Standards

Implementation

Generally not

REST focuses on the object of an action and provides few basic actions, while RPC focuses more on the action itself and provides a standard for remotely invoking them.

Being focused on message passing, most RPC-style systems natively provide for some form of data typing while REST only goes as far as establishing the concept of a resource representation.

RPC establishes set standards for method invocation, request and response formats, creating service descriptions, etc. REST focus is more on architectural principles.

RPC requests, while they can be atomic, generally aren't. Authentication tokens are often used to retain identity after an initial authentication request. In true REST services, all information needed to complete a request is contained within that request. That is, each request is self-contained and does not rely on requests that were previously sent.

Zend_XmlRpc_Server

Zend_XmlRpc_Server is a full-featured XML-RPC server implementation of the specifications found at http://xmlrpc.com.

Natively supports procedure namespaces and implements expected system.* procedures internally using Zend_Server_Reflection.

Prevents output of information for exceptions not thrown by the server component using a whitelisting approach.

XML-RPC Components

Zend_XmlRpc_Request and Zend_XmlRpc_Response are data structures for client requests to servers and server responses to clients respectively.

Zend_XmlRpc_Server allows for injection of custom request instances and use of custom response classes.

Zend_XmlRpc_Server_Fault manages whitelisting of exceptions that may be thrown during server operations, in order to ensure application security.

Boxcarring Requests

Extension to the XML-RPC protocol that allows multiple procedure calls to be sent within a single server request.

Not supported by all servers. Support is denoted by the presence of system.multicall in response to a call to system.listMethods.

Zend_XmlRpc_Server supports this feature.

Zend_XmlRpc_Server_Cache

System.* methods support uses Zend_Server_Reflection to handle class introspection, which can be expensive.

Zend_XmlRpc_Server_Cache can be used to cache server definitions to a file for better performace.

If get($cacheFilePath, $xmlRpcServerInstance) returns true, skip server configuration. Otherwise, configure your server class like normal and then call save($cacheFilePath, $xmlRpcServerInstance).

Zend_XmlRpc_Server_Cache has a very simple file-based implementation and unfortunately doesn't currently use or take advantage of the more flexible Zend_Cache. This is a potential point for improvement in future versions of Zend Framework.

Zend_XmlRpc_Client

Zend_XmlRpc_Client supports consumption of remote XML-RPC services and unit testing of server implementations.

Automatically handles type conversion between PHP and XML-RPC data types and allows for independent handling of both HTTP errors and XML-RPC faults.

Natively supports introspection operations on servers that support the de facto system methods.

Zend_XmlRpc_Client_ServerProxy

Zend_XmlRpc_Client_ServerProxy proxies remote XML-RPC namespaces to allow them to function as native PHP objects.

Ex: $client->getProxy()->system->listMethods();
vs. $client->call('system.listMethods');

XML-RPC Demo

And now for something completely different: a demo that actually uses the server components I was just talking about!

Acronym #3

JSON-RPC: JavaScript Object Notation Remote Procedure Call

RPC model similar to XML-RPC except that it uses using JSON as its data exchange format instead of XML.

Designed for extreme ease of use.

Current working draft version is 1.1.

Specification proposal for version 2.0 was released in March 2008.

What is JSON?

JSON: JavaScript Object Notation

Text-based human-readable data interchange format.

Based on a subset of JavaScript, but considered to be a language-independent format.

Detailed in RFC 4627 by Douglas Crockford.

Crockford is a senior JavaScript architect at Yahoo! best known for his work on the JSON-RPC protocol.

JSON versus XML

Pros of JSON

Extremely simple

Lighter payload

Native data type support

Cons of JSON

Fewer available supporting technologies

No native support for binary data or namespaces

Primitive data type support is weak

Not extensible

Supporting technologies for XML include XPath and XQuery for search, DTD and RELAX NG for validation, and XSLT for transformation.

Where XSD has float, double, decimal and precisionDecimal, JSON has only Number. JSON has no equivalents for XSD base64Binary or hexBinary.

JSON is for data exchange, XML is for document exchange. XML is intended to be extended to create new markup languages. Comparing the two is really like comparing apples and oranges.

Zend_Json_Server

Supports versions 1 and 2 of the JSON-RPC specification found at http://json-rpc.org.

Zend_Json_Server_Smd supports the Service Mapping Description specification for providing service metadata to clients.

Interoperable with Zend_Dojo_Data, the new data component for the Dojo toolkit in Zend Framework 1.6.

JSON-RPC Components

Zend_Json_Server_Request and Zend_Json_Server_Response are data structures for client requests to servers and server responses to clients respectively.

Zend_Json_Server_Error is a data structure for exceptions that may occur in processing requests.

Zend_Json_Server allows for injection of request and response instances.

Zend_Json_Client ... NOT!

Poor Man's Zend_Json_Client

Populate a Zend_Json_Server_Request instance with a method, parameters, and a request identifer.

Send the return value of $request->toJson() to the service endpoint via an HTTP POST operation using Zend_Http_Client.

Pass the HTTP response body to Zend_Json::decode() to get the equivalent PHP data structure.

Significant need was not perceived at the time that Zend_Json_Server was being developed. May be included in a future release, but was not feasible for the release that included the JSON-RPC components.

This applies to testing a client for a remote service that returns JSON or is based on JSON-RPC. To test a local Zend_Json_Server-based service, simply pass a populated request instance to handle() and use getResponse() to get the resulting response for evaluation.

JSON Demo

This is the last one... after the next one, of course.

Acronym #4

SOAP (pre-1.2 - Simple Object Access Protocol)

Protocol for exchanging XML-based messages.

Originally designed by Dave Winer, Don Box, Bob Atkinson, and Mohsen Al-Ghosein in 1998, with backing from Microsoft, to be the successor of XML-RPC.

Version 1.2 of the spec became a W3C recommendation in June 2003. Spec is currently maintained by the W3C XML Protocol Working Group.

"... once stood for 'Simple Object Access Protocol' but this acronym was dropped with Version 1.2 of the standard, as it was considered to be misleading." --Wikipedia article on SOAP

"SOAP is XML-RPC expanded to justify more development budget." -mitchitized on Twitter

Focuses more on the structure of the data returned.

SOAP versus XML-RPC

SOAP message structure is more complex and syntax more verbose than XML-RPC because it allows for extensive message customization.

SOAP supports user-defined data types (UDTs) while XML-RPC types are finite and predefined.

SOAP supports enumerations, XML namespaces, XML Schemas, and other advanced features.

XML-RPC 8 pages versus SOAP 62 pages.

More verbose syntax promotes human readability and facilitates fault handling, but can also have performance implications.

Zend_Soap_Server

Intended purpose of Zend_Soap_Server is to simplify use and implementation of SOAP within PHP applications.

API is compatible with the SoapServer component of the standard PHP SOAP extension. Composes it to add request, response, and service metadata handling.

Same two modes of operation: WSDL and non-WSDL.

Zend_Soap_Server inherits SoapServer's compatibility with SOAP 1.1 and 1.2.

What is WSDL?

Web Services Description Language

XML-based language for describing how to access and use web services and the structure of their output.

Not tied to SOAP, but often used with it.

Version 2.0 (formerly 1.2) is a W3C recommendation and has better support for RESTful services, but is less widely adopted than its predecessor version 1.1.

Writing it is about as pleasant as getting a root canal.

SOAP + WSDL is like PB&J.

Zend_Soap_Autodiscover

Zend_Soap_Autodiscover can generate WSDL from the source code of the class you expose as a SOAP service.

It has a SoapServer-compatible API, but doesn't implement any logic for most methods. Instantiate within a controller, call setClass or addFunction, handle, done.

Uses Zend_Server_Reflection to get class and type information, Zend_Soap_Wsdl for WSDL generation, and current request information for endpoint metadata.

Zend_Server_Reflection uses phpDoc-compatible docblocks for parameter and return type information.

Dependencies of the web service class should be included above the class definition so that they will be detected and added to the WSDL automatically when it's being generated.

extractComplexTypes parameter of the Zend_Soap_Autodiscover constructor defaults to true. Pass false to have complex types render with the generic type xsd:anyType.

Zend_Soap_Client

Composes the SoapClient component of the standard PHP SOAP extension to add request and response handling and accessor and mutator methods for all configuration options.

Includes methods that can be overridden in custom clients for preprocessing of arguments and service operation results.

Useful for testing Zend_Soap_Server-based services.

SOAP Demo

OK, this really is the last one this time. Really.

In conclusion...

... people who end their presentations with sentences starting with "in conclusion" have no creativity. Or are just inherently lazy. Or both.

As in many arenas, there is no end-all be-all "best" choice of implementation. It's all about what your needs are and what tools can meet them.

Zend Framework supports RAD development for the common methods of web service in today's marketplace.

Questions?

No heckling... OK, maybe just a little.

I will hang around afterward if you have questions, points for discussion, or just want to say hi. It's cool, I don't bite or have cooties or anything. I have business cards too.

I work with Zend Framework on a fairly regular basis these days and generally blog about my experiences at http://ishouldbecoding.com.

Thanks for coming!