Creating a RESTful API for mobile applications

Presented at http://www.tokyorubyistmeetup.org/events/2814

Transcript

1. Creating a RESTful API for mobile applications Paul McMahon @pwim
2. My Company: My Product:
3. REST provides a convention for client/ server communication
4. The core idea in REST: everything is a resource
5. Example: https://community-board.herokuapp.com/communities/1 or /communities/1
6. Four methods: GET, POST, PUT, DELETE
7. 5 standard actions in APIs GET /communities List communities POST /communities Create a community GET /communities/1 Get a community PUT /communities/1 Update a community DELETE /communities/1 Delete a community
8. Nesting Example: GET /communities/1/posts
9. These actions are all you need!
10. The resources in your API are not the same as in your application models
11. Example: Archive a community
12. POST /communities/1/archive
13. Example: Unarchive a community
14. DELETE /communities/1/archive
15. Significance of pluralization: Many communities, but only one archive per community
16. Format of resource is independent of representation
17. So the body of a request / response could be html, json, xml, image, etc
18. Practically speaking, we use json
19. Example { “community”: { “name”: “Tokyo iOS Meetup”, “post_count”: 5, “members”: [ { “name”: “Paul” }, { “name”: “Matt” } ], “public”: true, }
20. Use HTTP Status to Indicate Status of Request
21. Important status codes 200 OK 201 Created 401 Not Authorized 404 Not Found 406 Not Acceptable 422 Unprocessable Entity
22. Authentication: Use OAuth 2.0
23. http://openam.forgerock.org/openam-documentation/openam-doc-source/doc/admin-guide/index/chap-oauth2.html#openam-oauth2-authz-server
24. API Practicalities
25. Version your api: /api/v1/communities
26. Kill Switch: Force clients to upgrade
27. Control Endpoint Domain: i.e, don’t use community-board.herokuapp.com in production
28. Don’t handcraft your json
29. Return complete URLs
30. Build your API to minimize requests for mobile client
31. So, what about Rails?
32. Anatomy of an API Controller class Api::V1::CommunitiesController respond_to :json def index @communities = Community.all respond_with @communities end end
33. Generating JSON user.as_json(include: { posts: { include: { comments: { only: :body } }, only: :title } })
34. RABL # app/views/posts/index.rabl collection @posts attributes :id, :title, :subject child(:user) { attributes :full_name } node(:read) { |post| post.read_by?(@user) } [{ "post" : { "id" : 5, title: "...", subject: "...", "user" : { full_name : "..." }, "read" : true } }]
35. ActiveModel Serializers class PostSerializer < ActiveModel::Serializer attributes :id, :title, :body has_many :comments end class CommentSerializer < ActiveModel::Serializer attributes :id, :text end # /posts/1 { “post” : { “id”: 1, “title”: “Sample”, “body”: “Sample Body”, “comments”: [ {“id”: 1, “text”: “comment 1”}}, {“id”: 2, “text”: “comment 2”}] }
36. OAuth2 with Doorkeeper class Api::V1::CommunitiesController respond_to :json doorkeeper_for :index def index @communities = Community.all respond_with @communities end end