5 Ways to Build Better
Web APIs in Ruby
1. Select the right API framework and gems
Rails isn't always the right answer
Not all frameworks are ==
Cuba
Rack::Response
Rambutan
NYNY
Rails
Ramaze
0 2000 4000 6000 8000 10000
Requests/sec (Higher is better)
Neither are ORMs…
Class
Hash
AR 3.2
Datamapper
Sequel
0 1 2 3 4 5 6 7 8
new(hash)new()
Select a Serializer
Select a gem or approach that can build JSON, XML, and (perhaps) any future format as well.
(I like Roar + Representable)
Pro Tip: Select your frameworks and gems based on your actual
needs(not what someone else
says)
2. Prototype Your API
Ways to Prototype
Static files – manual response for GET only
Stubbed controllers – works for all request types
Heroku Dataclips – great for a quick way to build SQL-to-JSON for GET requests
3. Acceptance test your APIs
TDD APIs FTW!
Acceptance tests will ensure you write better APIs by mimicking how developers will consume your API
What should you use?
RSpec, Cucumber, ???
One is not better than another
Use a testing framework so a failure should break your build and report on what failed
4. Select the right API tools
Examples of API Tools
Exploration: POSTman Chrome Plugin
Documentation: RAML, Runscope, APIDesigner
Debugging: RunScope, SOAPUI
Auth/token and portal mgmt: Layer 7, Apigee, Mashery, 3Scale, Stormpath
and many others…
5. Improve the developer experience
Rails trained us to think CRUD
Stop painting your APIs with CRUD to solve problems
Take an outside-in design
What is the problem?
How does the world view the problem?
How does your API solve their problem?
Document your API
Build examples for quick wins
Speak in their terms