Building a RESTful PHP Server: Output Handlers

This is the third installment in my series about writing a RESTful web service in PHP (the previous entries are about understanding the request and routing it. It is probably the last one but there are a few other things I'd like to cover such as error handling, so I might keep adding to it, especially if I get any particular requests or interesting questions in the comments. So far we've covered parsing requests to determine exactly what the user is asking for, and also looked at routing to a controller to obtain the data or perform the action required. This post gives examples of how to return the data to the client in a good way. Continue reading

API Serving JSONP

disclaimer: I am not a client-side developer, and I don't write javascript. However I am committed to supplying useful APIs of all kinds, and JSONP falls into this category

Early in the development of the new Joind.In API, someone else started consuming the service to populate the javascript widgets they were making*. Since these scripts are intended to be used on many external pages, and they retrieve data from the joind.in API, cross-domain issues were a problem. Continue reading

QR Codes with Google Charts API

I'm a big fan of the google charts API - it draws much better-looking graphs than I would ever manage and all I have to do is assemble the right URL to make it work. I recently got a feature request to add QR codes to joind.in, so that speakers and event admins could easily allow people to link in to a particular talk page.
Continue reading

PHP Returning Numeric Values in JSON

When I wrote about launching a prototype of a new joind.in API, quite a few people started to try it out. My friend David Soria Parra emailed me to point out that many of the numbers in the API were being returned as strings. He said:

It's just a standard problem of PHP REST services. When I try to access it with java I have to convert it over and over again to ints.

I did have a quick look at the PHP manual page for json_encode but I didn't see anything mentioning this. A few weeks later (my inbox is a black hole and it takes a while to process these things) I fell over a throwaway comment to an undocumented constant JSON_NUMERIC_CHECK, and I added the constant name to my todo list. In the time it took for me to actually get around to googling for this, some wonderful person updated the PHP manual page (this is why I love PHP) to include it as a documented option, and someone else had added a user contributed note about using it.

It turns out, this constant does exactly what I need. Here's a simple use case:

echo json_encode(array('event_id' => '603'));
echo json_encode(array('event_id' => '603'), JSON_NUMERIC_CHECK);

and the output:

{"event_id":"603"}
{"event_id":603}

There are probably some situations in which you don't want all your looks-like-a-number data to be returned as a number, but for now it seems to be a good fit for api.joind.in.

A Prototype API for Joind.In

Following the principle of "release early, release often", I put live a very early version of the v2 API for joind.in today (so that I can use it in another project!). I haven't updated the documentation yet but in case anyone was thinking of consuming data from joind.in, this at least gives you an idea of the direction of the project so I thought I'd share.

Things you need to know:

  • The service is an HTTP Web Service. Meaning it's RESTful apart from when it isn't
  • The endpoint is here: http://api.joind.in
  • You can fetch data about events and talks (read-only) at this point
  • Formats available are HTML or JSON. The service will guess from your accept header but you can override it with ?format=json or ?format=html
  • If you need more columns than you get by default, you can add ?verbose=yes to your request
  • Pagination is available, with parameters resultsperpage (default 20, set to zero for no limits) and start (default zero)
  • The service supports OAuth1.0a, which isn't useful at this point as we're read-only but it will come into play as we add functionality

Examples

Events list: http://api.joind.in/v2/events

Information about DPC11: http://api.joind.in/v2/events/603

Talks at DPC11: http://api.joind.in/v2/events/603/talks

Your Thoughts

Comments are welcome on this post. Bugs and feature requests should go to http://joindin.jira.com, read more about Joind.in and its community at http://joind.in/about

Invalid Protected Resource URL in Pecl_Oauth

I had a funny (funny weird, not funny haha) problem the other day when working with pecl_oauth in PHP to talk to a service. I'd gone through all the handshaking steps, got the acces token and was ready to start talking to the service itself. However when I tried to call OAuth::fetch, I got an error message:

Fatal error: Uncaught exception 'OAuthException' with message 'Invalid protected resource url, unable to generate signature base string'

There are two things to notice about this. The first one is that I should be catching exceptions thrown by this code :) The second is that I could see nothing wrong with my url, http://api.local. It turned out, after some experimentation, that what is missing here is a trailing slash, and if I supply http://api.local/, everything works perfectly nicely! I'm unclear if this is intended functionality or not, but if you see this error message and you're requesting a URL with no path info, make sure you have a trailing slash.

Quick-Start Guide for Google Charts API

Google Charts API is a nice, freely available tool for creating really good-looking graphs very painlessly. Don't be fooled by the "API" bit though, there is no need for advanced understanding of HTTP here - you generate most graphs just by adding parameters to a URL! In this post we'll take a look at a few different ways to generate charts.

One-Off Charts

If you just need a beautiful graph to put into a document or post, then the Chart Wizard is the best place to start. You simply choose the type of chart you want, input your data and choose the colours, labels, settings etc, and the wizard generates the URL for you to copy and paste!

The charts are highly configurable and can easily be changed by editing the URL to the image (view the source of this page to see the URL for the chart shown above). This makes it really easy to generate similar-but-different charts in your web applications, by using the wizard and then replacing some relevant parts of it.

Dynamic Charts

As mentioned above, it is very simple to generate charts with Google Charts API - and all the information for generating the chart is on a URL which returns a png file of the resulting chart. This makes it ideal for integrating into our dynamic web applications and charts that are generated are almost overwhelmingly configurable. That said, there are a few key options that will get you started quickly so let's take a quick tour.

Continue reading

Github API: Issues List

I'm deeply involved with an open source development project (joind.in, the event feedback site) and we recently made the decision to move our issue tracking away from GitHub (because it's awful and meets none of the requirements for a bug tracker, but that's a post for another day). In order to make this happen more smoothly, we wanted to migrate our open issues from github (to JIRA Studio, since Atlassian generously provides accounts here for worthy open source projects - thanks Atlassian!).

I looked around for some export functionality for github but I got a lot of posts complaining it wasn't there. Since I hate applications that take your data and refuse to let you remove it, I was disappointed by this news but further inspection showed that although there might be no "export from github" button, there's an API that more than has it covered. The API returns JSON which is easy to work with from many programming languages, and is perhaps even more powerful and flexible than the simple export I initially expected, so here are some examples.

Continue reading