Creating a RESTful API for mobile applications

Slide 1

Slide 1 text

Creating a RESTful API for mobile applications Paul McMahon @pwim

Slide 2

Slide 2 text

My Company: My Product:

Slide 3

Slide 3 text

REST provides a convention for client/ server communication

Slide 4

Slide 4 text

The core idea in REST: everything is a resource

Slide 5

Slide 5 text

Example: https://community-board.herokuapp.com/communities/1 or /communities/1

Slide 6

Slide 6 text

Four methods: GET, POST, PUT, DELETE

Slide 7

Slide 7 text

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

Slide 8

Slide 8 text

Nesting Example: GET /communities/1/posts

Slide 9

Slide 9 text

These actions are all you need!

Slide 10

Slide 10 text

The resources in your API are not the same as in your application models

Slide 11

Slide 11 text

Example: Archive a community

Slide 12

Slide 12 text

POST /communities/1/archive

Slide 13

Slide 13 text

Example: Unarchive a community

Slide 14

Slide 14 text

DELETE /communities/1/archive

Slide 15

Slide 15 text

Signiﬁcance of pluralization: Many communities, but only one archive per community

Slide 16

Slide 16 text

Format of resource is independent of representation

Slide 17

Slide 17 text

So the body of a request / response could be html, json, xml, image, etc

Slide 18

Slide 18 text

Practically speaking, we use json

Slide 19

Slide 19 text

Example { “community”: { “name”: “Tokyo iOS Meetup”, “post_count”: 5, “members”: [ { “name”: “Paul” }, { “name”: “Matt” } ], “public”: true, }

Slide 20

Slide 20 text

Use HTTP Status to Indicate Status of Request

Slide 21

Slide 21 text

Important status codes 200 OK 201 Created 401 Not Authorized 404 Not Found 406 Not Acceptable 422 Unprocessable Entity

Slide 22

Slide 22 text

Authentication: Use OAuth 2.0

Slide 23

Slide 23 text

http://openam.forgerock.org/openam-documentation/openam-doc-source/doc/admin-guide/index/chap-oauth2.html#openam-oauth2-authz-server

Slide 24

Slide 24 text

API Practicalities

Slide 25

Slide 25 text

Version your api: /api/v1/communities

Slide 26

Slide 26 text

Kill Switch: Force clients to upgrade

Slide 27

Slide 27 text

Control Endpoint Domain: i.e, don’t use community-board.herokuapp.com in production

Slide 28

Slide 28 text

Don’t handcraft your json

Slide 29

Slide 29 text

Return complete URLs

Slide 30

Slide 30 text

Build your API to minimize requests for mobile client

Slide 31

Slide 31 text

So, what about Rails?

Slide 32

Slide 32 text

Anatomy of an API Controller class Api::V1::CommunitiesController respond_to :json def index @communities = Community.all respond_with @communities end end

Slide 33

Slide 33 text

Generating JSON user.as_json(include: { posts: { include: { comments: { only: :body } }, only: :title } })

Slide 34

Slide 34 text

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 } }]

Slide 35

Slide 35 text

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”}] }

Slide 36

Slide 36 text

OAuth2 with Doorkeeper class Api::V1::CommunitiesController respond_to :json doorkeeper_for :index def index @communities = Community.all respond_with @communities end end