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 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.
As an experiment, I migrated my website over to OpenShift yesterday. I've been hosting a pastebin there already, and have found the service to be both straightforward and flexible; it was time to put it to a more thorough test.
In the process, I ran into a number of interesting issues, some of which took quite some time to resolve; this post is both to help inform other potential users of the service, as well as act as a reminder to myself.
This is a post I've been meaning to write for a long time, and one requested of me personally by Evert Pot during the Dutch PHP Conference in June 2012. It details some observations I have of php-fig, and hopefully will serve as a record of why I'm not directly participating any longer.
I was a founding member of the Framework Interoperability Group, now called "php-fig". I was one of around a dozen folks who sat around a table in 2009 in Chicago during php|tek and started discussions about what we could all do to make it possible to work better together between our projects, and make it simpler for users to pick and choose from our projects in order to build the solutions to their own problems.
The first "standard" that came from this was PSR-0, which promoted a standard class naming convention that uses a 1:1 relationship between the namespace and/or vendor prefix and the directory hierarchy, and the class name and the filename in which it lives. To this day, there are both those who hail this as a great step forward for cooperation, and simultaneously others who feel it's a terrible practice.
And then nothing, for years. But a little over a year ago, there was a new push by a number of folks wanting to do more. Paul Jones did a remarkable job of spearheading the next two standards, which centered around coding style. Again, just like with PSR-0, we had both those feeling it was a huge step forward, and those who loathe the direction.
What was interesting, though, was that once we started seeing some new energy and momentum, it seemed that everyone wanted a say. And we started getting dozens of folks a week asking to be voting members, and new proposal after new proposal. Whether or not somebody likes an existing standard, they want to have backing for a standard they propose.
And this is when we started seeing proposals surface for shared interfaces, first around caching, and now around logging (though the latter is the first up for vote).
Cal Evans has organized another DayCamp4Developers event, this time entitled "PHP Master Series, Volume 1". I'm honored to be an invited speaker for this first edition, where I'll be presenting my talk, "Designing Beautiful Software".
Why would you want to participate? Well, for one, because you can interact directly with the various speakers during the presentations. Sure, you can likely find the slide decks elsewhere, or possibly even recordings. But if we all do our jobs right, we'll likely raise more questions than answers; if you attend, you'll get a chance to ask some of your questions immediately, and we may even answer them!
On top of that, this is a fantastic lineup of speakers, and, frankly, not a lineup I've ever participated in. In a typical conference, you'd likely see one or two of us, and be lucky if we weren't scheduled against each other; if you attend this week, you'll get to see us all, back-to-back.
What else will you be doing this Friday, anyways, while you wait for the end of the world?
So, do yourself a favor, and register today!
Unusually for me, I did not speak on a Zend Framework topic, and had only one regular slot (I also co-presented a Design Patterns tutorial with my team). That slot, however, became one of my favorite talks I've delivered: "Designing Beautiful Software". I've given this talk a couple times before, but I completely rewrote it for this conference in order to better convey my core message: beautiful software is maintainable and extensible; writing software is a craft.
I discovered today that not only was it recorded, but it's been posted on YouTube:
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.