Tag: zend framework

A few days ago, we released our first beta of Apigility.
We've started our documentation effort now, and one question has arisen a few times that I
want to address: How can you use Hypermedia Application Language (HAL) in RPC services?

In my previousposts, 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.

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.

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.

A long time ago, I set out to write my own blog platform. Yes, WordPress is a fine blogging platform, as is
Serendipity (aka "s9y", and my previous
platform). And yes, I know about Habari. And, for those of you skimming
ahead, yes, I'm quite aware of Jekyll,
thank you anyways.

Why write something of my own? Well, of course, there's the fact that I'm
a developer, and have control issues. Then there's also the fact that a
blog is both a simple enough domain to allow easily experimenting with new
technology and paradigms, while simultaneously providing a complex enough
domain to expose non-trivial issues.

When I started this project, it was a technology-centered endeavor; I
wanted to play with document databases such as CouchDB and MongoDB, and with caching technologies
like memcached and redis.

Not long after I started, I also realized it was a great playground for me
to prototype ideas for ZF2;
in fact, the original DI and MVC prototypes lived as branches of my blog.
(My repository is still named "zf2sandbox" to this day, though it
technically houses just my site.)

Over time, I had a few realizations. First, my actual blog was
suffering. I wasn't taking the time to perform security updates, nor even
normal upgrades, and was so far behind as to make the process non-trivial,
particularly as I had a custom theme, and because I was proxying to my
blog via a ZF app in order to facilitate a cohesive site look-and-feel. I
needed to either sink time into upgrading, or finish my blog.

My second realization, however, was the more important one: I wanted a
platform where I could write how I want to write. I am
a keyboard-centric developer and computer user, and while I love the web,
I hate typing in its forms. Additionally, my posts often take longer than
a typical browser session -- which leaves me either losing my work in a
GUI admin, or having to write first in my editor of choice, and then
cut-and-paste it to the web forms. Finally, I want versions I can easily
browse with standard diffing tools.

When it came down to it, my blog content is basically static. Occasionally,
I'll update a post, but it's rare. Comments are really the only dynamic
aspect of the blog... and what I had with s9y was not cutting it, as I was
getting more spam than I could keep up with. New commenting platforms such
as Livefyre and Disqus
provide more features than most blogging platforms I know, and provide
another side benefit: because they are javascript-based, you can simply
drop in a small amount of markup into your post once -- meaning
your pages can be fully static!

Add these thoughts to the rise of static blogging platforms such as the
aforementioned Jekyll, and I had a kernel of an idea: take the work I'd
done already, and create a static blog generator.