Rails%203%20In%20Action

348 CHAPTER 13 Designing an API
One great example of how an API is used is Twitter. Twitter has had an API for an
exceptionally long time now, and people have written Twitter clients for just about
every operating system out there using this API. The functionality of the site is effectively
the same, but people have come up with interesting ways of displaying and modifying
that information, such as the Twitter for Mac clients.
There are many, many Rails sites out there that already provide an API interface,
such as GitHub 3 and (as previously mentioned) Twitter. 4 Both of these APIs have
exceptionally well-documented examples of how to use them and what can be done
with them, which is a great way to convince people to start using your API. API documentation,
however, is an exercise best left for you after this chapter’s done.
APIs aren’t unique to Rails. There are plenty of other sites out there that have
implemented their own APIs, such as the StackExchange services that run on Microsoft.Net.
Furthermore, APIs created in one language are not for exclusive use of API
clients written in that specific language. For example, if you wanted to parse the data
from the StackExchange API in Ruby, you could do that just fine.
In Rails, however, it’s extremely easy to make a modern API for an application, as
you’ll see in this chapter. Your application will serve in two formats: JSON and XML.
Back to the Twitter and GitHub examples now, and one further thing to note is
both of these APIs are also versioned. The point of this is that an API should be presented
in a “frozen” state and should not be modified once it’s considered stable. This
way, a user is be able to use an API without fear of it changing and potentially breaking
the code that they’re using to parse the data from the API.
Twitter has a URL such as http://api.twitter.com/1/statuses/public_timeline.json
that has the version as the first part of the URL after the site name and then the format
as an extension at the end. Github’s is slightly different, with a URL such as
http://github.com/api/v2/json/repos/show/rails3book/ticketee having the version
prefixed with a v as the second part of the URL, and the format as the part of the
URL directly after. The v prefix here makes the version part of the URL clearer to
those who are reading it, which is a good thing.
You’re going to borrow ideas from both of these API designs, presenting your API
at the base URL of /api/v1 and the format at the end of the URL, like most web
requests. Your URLs will look like /api/v1/projects.json, which will be the URL to
return a list of projects that the user is able to read. The reason for this versioning is so
that you can always provide data that is predictable to your end users. If you wished to
change the format of this data, you would create a new version namespace, which is
the final thing we look at toward the end of this chapter. Really, these new version
numbers can be whatever you wish, with minor versions such as 0.1 being the standard
3 The octopi gem was built to interact with the GitHub API—you can see the source at http://github.com/
fcoury/octopi.
4 The (non-official) twitter gem was built to interact with the API that Twitter provides; you can see the
source of this gem at http://github.com/jnunemaker/twitter.