Are Subqueries RESTful?

Twitter is great for one-liners, but it’s very difficult to carry on any kind of advanced conversation there. Therefore when I saw this tweet yesterday, I knew I’d be picking a different medium to reply:

The blog seems like a good place, as I can put examples and all kinds other things here, and waffle at length (which is really why I like it!). Because when condensed to tweet form, the answer is really “it depends”.

The Problem(s)

REST is all about representations of resources. They might come in different formats, and they might appear at their own URI as well as in one or more collections, but essentially you just get a representation of a thing. This is great, apart from when it isn’t.

  • What if you want a smaller result set with only a limited number of fields?
  • What if you want related data? For every resource in a collection?

Continue reading

Endpoints for HTTP Testing

While working on a book (“PHP Web Services” from O’Reilly, not out yet but soon!) recently, I was looking for some place I could make HTTP requests to, to show off how to make different kinds of requests with different tools. On my own machine, I have a couple of scripts that chatter back giving debug information about the requests that were made, but I wanted to get the tools examples going without any additional dependencies at all. I hadn’t used anything like these tools before, but I found quite a few alternatives, so I thought I’d share what I came up with. Continue reading

How NOT to Design Your API

Recently I tweeted as a #linktuesday link the 10 Worst API Practices post from ProgrammableWeb. Today, in search of some concrete examples of APIs implementing unhelpful antipatterns, I sent out a tweet for help:

[blackbirdpie id=”289014953954930688″]

In the raft of responses (and thankyou all, this was fabulous, helpful and entertaining in equal parts!), there were some definite patterns that I’d like to share with you, in no particular order. Continue reading

Datapoint: Weather API from the MetOffice

I’m working on a little hobby project which needs to know what the weather is going to be. I had a look around and noticed that the MetOffice had released a new API called DataPoint. They have a selection of APIs, including some map overlays and some actual weather data (more on that another day) but I was especially charmed by their text APIs – this is basically the basis of weather forecasts used everywhere :)
Continue reading

Github API Access Tokens via Curl

I’m working on some demos for a tutorial I’m giving next month and since I’d like to show off Github’s API, I needed an access token for it. They have the usual web flow but I’m cutting as many corners as I can to keep the demos nice and quick, so I looked into the support Github has for generating an API key programmatically. Continue reading

API Documentation with IODocs

I write a lot of APIs, and I also preach that your API isn’t finished until it has excellent documentation. Which is great, but that means I therefore have to lead by example and document my APIs :) Enter iodocs from the talented folk at Mashery.

Iodocs is a node.js application (which is fun for a PHP developer. Most developers write a bit of JS, but this one hasn’t). You describe your API and all its methods in JSON, and then iodocs presents an interface for you to enter API keys, add parameters to each request and press the “try it!” button. This makes your API call and shows you the results on screen, which seems like a great way to demonstrate what all the various parameters do!

iodocs screenshot
Continue reading

Posting Raw Data with Curl

This week I’ve been working on a feature which handles an incoming API call from an external source (actually Paypal’s IPN service). Making external calls into my development platform isn’t how I usually work, so instead I captured the body of the request that was being sent, and replayed it against my local script using curl.

I put the data into a separate file, data.txt and then used curl to direct that data at my local URL:

curl -X POST http://localhost/app/test.php --data @data.txt

I find this approach useful for testing, but since I had to look up how to do it, I thought I’d put it here for reference!

Bit.ly API: Bundles and Short URLs

I am a huge fan of bit.ly and use their tools for a wide variety of different things. They recently did a big relaunch with some lovely new features, which are for the most part pretty good, but which are inaccessible in places. In particular, it seems that there aren’t any short URLs for the bundles – which is annoying for me as I use that feature a lot!

To get around this, I used their API to make a page which lists my bit.ly bundles, and creates shortlinks for each of them (once you’ve created a shortlink for a given URL once, bit.ly just re-uses the same ones the next time you ask to shorten the same URL, so this is less silly than it sounds).

In case the code is helpful, I thought I’d share. Continue reading

Fetching Your Talks from the Joind.In API

I’m a regular speaker at a variety of (okay, mostly technical, so not really that varied!) events, and I submit talks to many CfPs (calls for papers). Whenever this happens, I tend to look back at whether I have any existing talks that I gave and liked and which would be a good fit. I use my joind.in speaker page for this: http://joind.in/user/view/110 as it’s simpler than dredging through my directory of talks/articles on my hard drive (this is now rather large and unmanageable!).

I’ve recently been thinking that I should also do a better job of linking through to the various talks I’m giving/have given – and at around the same time I was contacted by the good folk at mojoLive about integrating against joind.in. To cut a long story short, the joind.in API now has the functionality for users to retrieve their list of talks! Continue reading