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
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.
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:
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.
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
- If you need more columns than you get by default, you can add
?verbose=yesto your request
- Pagination is available, with parameters
resultsperpage(default 20, set to zero for no limits) and
- 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
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
If you are attending my Web Services tutorial at PHP Community Conference (if not, probably nothing for you to see here) later this week then you might like to download the sample code. I'll be referring to this and inviting you to "play along" as I go creating services during the session on Thursday - see you there!
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.
Recently the nice folks at Addison Wesley sent me a review copy of "The Developer's Guide to Social Programming" by Mark Hawker (you can find it here on amazon). This is right up my street as I'm doing so much with with APIs, social and otherwise, at the moment and the book covers things I'm using such as OAuth and google's services.
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.
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.
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.
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.