In my previous posts, I covered basics of JSON hypermedia APIs using Hypermedia Application Language (HAL), and methods for reporting errors, including API-Problem and vnd.error.

In this post, I'll be covering documenting your API — techniques you can use to indicate what HTTP operations are allowed, as well as convey the full documentation on what endpoints are available, what they accept, and what you can expect them to return.

While I will continue covering general aspects of RESTful APIs in this post, I will also finally introduce several ZF2-specific techniques.

In my last post, I covered some background on REST and the Richardson Maturity Model, and some emerging standards around hypermedia APIs in JSON; in particular, I outlined aspects of Hypermedia Application Language (HAL), and how it can be used to define a generic structure for JSON resources.

In this post, I cover an aspect of RESTful APIs that's often overlooked: reporting problems.

RESTful APIs have been an interest of mine for a couple of years, but due to circumstances, I've not had much chance to work with them in any meaningful fashion until recently.

Rob Allen and I proposed a workshop for PHP Benelux 2013 covering RESTful APIs with ZF2. When it was accepted, it gave me the perfect opportunity to dive in and start putting the various pieces together.

Zend Server has a very cool Page Caching feature. Basically, you can provide URLs or URL regular expressions, and tell Zend Server to provide full-page caching of those pages. This can provide a tremendous performance boost, without needing to change anything in your application structure; simply enable it for a set of pages, and sit back and relax.

I was recently shopping around for inexpensive cloud hosting; I want to try out a couple of ideas that may or may not have much traffic, but which aren't suited for my VPS setup (the excellent ServerGrove); additionally, I'm unsure how long I will maintain these projects. My budget for this is quite small as a result; I'm already paying for hosting, and am quite happy with it, so this is really for experimental stuff.

I considered Amazon, Orchestra.io, and a few others, but was concerned about the idea of a ~$50/month cost for something I'm uncertain about.

When I asked in #zftalk.dev, someone suggested OpenShift as an idea, and coincidentally, the very next day Zend announced a partnership with RedHat surrounding OpenShift. The stars were in alignment.

In the past month, in the few spare moments I've had (which included an excellent OpenShift hackathon at ZendCon), I've created a quick application that I've deployed and tested in OpenShift. These are my findings.

One of the exciting features of the newly released Zend Framework 2 is the new module system.

While ZF1 had modules, they were difficult to manage. All resources for all modules were initialized on each request, and bootstrapping modules was an onerous task. Due to the difficulties, modules were never truly "plug-and-play", and thus no ecosystem ever evolved for sharing modules.

In Zend Framework 2, we've architected the MVC from the ground up to make modular applications as easy as possible. Within ZF2, the MVC simply cares about events and services — and controllers are simply one kind of service. As such, modules are primarily about telling the MVC about services and wiring event listeners.

To give you an example, in this tutorial, I'll show you how to install the Zend Framework 2 skeleton application, and we'll then install a module and see how easy it is to add it to the application and then configure it.

A number of months ago, Ed Finkler started a discussion in the PHP community about "MicroPHP"; to summarize, the movement is about:

• Building small, single-purpose libraries.
• Using small things that work together to solve larger problems.

I think there are some really good ideas that have come out of this, and also a number of questionable practices¹.

One piece in particular I've focussed on is the concept of so-called “microframeworks”.

In Zend Framework 1, controller's had an init() method, which was called after the controller was instantiated. The reason for it was to encourage developers not to override the constructor, and thus potentially break some of the functionality (as a number of objects were injected via the constructor). init() was useful for doing additional object initialization.

class MyController extends Zend_Controller_Action
{
    public function init()
    {
        // do some stuff!
    }
}

But this feature is missing from ZF2; how can we accomplish this sort of pattern?

Forms are a nightmare for web development. They break the concept of separation of concerns:

• They have a display aspect (the actual HTML form)
• They have a validation aspect
• And the two mix, as you need to display validation error messages.

On top of that, the submitted data is often directly related to your domain models, causing more issues:

• Not all elements will have a 1:1 mapping to the domain model — buttons, CSRF protection, CAPTCHAs, etc. usually are application-level concerns, but not domain issues. Names valid for your domain model may not be valid names for HTML entities.

Add to this that the validation logic may be re-usable outside of a forms context, and you've got a rather complex problem.