Rails%203%20In%20Action

384 CHAPTER 13 Designing an API
git push
renaming name to title for projects"
Alright, so now you’ve got two versions of your API. Generally, there’s much more than
a single change in a new API version, but this is a good start. When you announce this
API to the people who use your application, they can switch their libraries over to
using it immediately, or, ideally, remain using the old version. After a while, you may
elect to turn off the first version of the API, and you would do that by giving your users
considerable notice such as a month, and then un-defining the routes and deleting
the controllers and tests associated with that version. Out with the old and in with the
new, as they say.
You’ve now seen how you can serve data from your application using an API, but
how do you read it? The answer to that lies in a part of Rails called Active Resource.
13.5 Summary
You’ve seen in this chapter how you can use the Rack::Test::Methods module, given
to you for free by the rack-test gem, to test that requests to URLs provided by your
application return valid API responses in JSON and XML formats. Users will then be
able to make these same requests for their own applications or libraries to get at the
data in your system. What they come up with is up to their imagination. In this chapter,
we only covered one aspect (projects) for your API, but with the knowledge found in
this chapter you could easily create the other aspects for tickets, users, states, or tags.
In the second section of this chapter you saw how you can limit the request rate to
your API on a per-user basis. Users can make up to 100 requests to your system, and
when they attempt to make their 101st the application denies them the request and
provides a relevant error message. This is to deter people from excessively using the
API, as you do not want your server to become overloaded immediately.
Last, you saw how you can generate a new version of your API so that you can introduce
a change, or changes, so as to not break the previous version of the API. Once an
API has been released to the public, its output shouldn’t be modified, as this may
affect the libraries referring to it. The easiest way to introduce these modifications is
through a new version, which is what you did. Eventually, you may choose to deprecate
the old API, or you may not. It’s really a matter of personal choice.
Your application’s at a pretty great point now and is ready for prime time! To show
it off to the masses, it’s best that you put the code on a computer dedicated to serving
the application, rather than running it on some local hardware. In chapter 14, you’ll
deploy your application to an Ubuntu 10.10 box, learning about the core components
to a deployment software stack as you go.