1. RESTful API practices

2. One Backend
Multiple Clients
Web Front-end Mobile
(backbone.js, (Android, iOS,
javascriptmvc.js etc.) BlackBerry,
Symbian, WP7?)
Third party
applications

3. API planning
• RESTful - no-brainer for Rails people
• Minimum viable API - Released features must be
maintained and probably supported in next versions
• Versioning - URI design
• Formats - Json ... (xml?)
• Authentication

4. Versioning
From the client side
• URI design
• www.myapp.com/api/v1
• api.myapp.com/v1
• Custom header X-SMTH-Api-ver: 1

5. Versioning
From the back-end
• Sub-controllers
• app/controllers/api/v1/
• app/controllers/api/v2/
• Routes
• Models - mixins

6. Request and response
formats
respond_with method in Rails 3

7. Authentication
• Session based - Devise
• Request based - client provides his ID and a
signature

8. Testing
describe "post create" do
Create Post
describe "when post is valid" do
[POST] /api/v1/post.json
it "should respond with created"
[PROPERTIES]
it "should respond with created post"
• post: this object specifies the data to be created as a post (required)
• third_party_id (required) it "should have only allowed attributes in response object"
• content (required)
end
[EXAMPLE REQUEST]
describe "when post is invalid" do
POST http://cannedapps.com:3838/api/post.json
"post": { it "should respond with unprocessable entity"
"third_party_id": 142,
"content": "Hi Guys!" end
}
end
On Success:
Http status code 201 is returned, with a response body including the created
participant id.
[EXAMPLE RESPONSE]
{
"id": 767,
"third_party_id": 142,
"content": "Hi Guys!",
"updated_at": "2011-04-14 07:18:43"
}
If a create or update action failed, HTTP status code 422 Unprocessable Entity
and a JSON-encoded body of localized error messages will be returned.

9. Example
https://github.com/naru/API-practices-demo

10. Thank you!
Anton Narusberg
Cannedapps
github.com/naru
anton@cannedapps.com
@antonnarusberg