Creating a RESTful API for mobile applications

Creating a RESTful API for mobile applications

Dd24adb5a3a430fed83a33ed552fe1b5?s=128

Paul McMahon

March 25, 2013
Tweet

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