Building Mobile Friendly APIs in Rails

Building Friendly APIs in Rails

Authentication
Support
Usability

user_id: 1
admin: false
prefers_mobile_site: true

:cookie_store
:active_record_store

user browser server database
user_id: 1
admin: false
prefers_desktop_site: false
session_id: 09497d46978bf6f32265fefb5cc52264
session_id:
09497d46978bf6f3226...
6eabede90ce558ade5...
user_id:
1
7
admin:
false
true
prefers_mobile:
true
true

Both Methods Rely on
Cookies to Maintain
the User’s Session

But...
Cookies Only Work
in the Browser

user app server database
GET /users/1/profile
Host: galaxies.com
Authorization: Bearer 09497d46978bf6f3226...
access_token:
09497d46978bf6f3226...
6eabede90ce558ade5...
user_id:
1
7
admin:
false
true
token_expires:
1466913490
1466913501

Wait... the :cookie_store
didn’t need to check with
the database everytime

We can avoid storing
tokens in the database
using... TOKENS!

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.
eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZ
SI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydW
V9.TJVA95OrM7E2cBab30RMHrHDcEfxjo
YZgeFONFh7HgQ
JSON Web Tokens
or JWTs.

header.
payload.
verify_signature
JSON Web Tokens
Encoded but not Encrypted

{
"alg": "HS256",
"typ": "JWT"
}
Header
Algorithm & Token Type

{
"iss": "your-service",
"exp": 1300819380,
"user_id": "1",
"admin": true
}
Payload
The Data

Payload Claims
http://self-issued.info/docs/draft-ietf-oauth-json-web-token.html#RegisteredClaimName
Read More:
"iss": "your-service",
"exp": 1300819380,
"user_id": "1",
"admin": true
Registered
Defined by
the spec.
Public
Defined by
your app

HMACSHA256(
base64UrlEncode(header) + "." +
base64UrlEncode(payload),
SECRET_KEY_BASE
)
Verify Signature
The Guarantee

JWTs are self contained
so the server can confirm
the user is authenticated
by verifying the signature.
This is similar to how rails secures cookies...

How do I add JWT
to my Project?
<<

Using Devise?
Add a Warden Strategy

module Devise
module Strategies
class JsonWebToken < Base
def valid?
!request.headers['Authorization'].nil?
end
def authenticate!
if claims and user = User.find_by_id(claims.fetch('user_id'))
success! user
else
fail!
end
end
private
def claims
auth_header = request.headers['Authorization'] and
token = auth_header.split(' ').last and
::JsonWebToken.decode(token)
rescue
nil
...
end
Determines whether or
not the strategy should
be ignored...
Provides the current_user

http://zacstewart.com/2015/05/14/using-json-web-tokens-to-authenticate-javascript-front-ends-on-rails.html
JWT + Devise Tutorials
JWT via Warden Strategy by Zac Stewart:
I prefer this method over my own tutorial as I find the Warden strategy to
be more elegant than additional controller logic.
https://github.com/jimjeffers/rails-devise-cors-jwt-example
https://www.youtube.com/watch?v=_CAq-F2icp4
Rails + Devise + CORS + JWT Example & Screencast:
This is an example I put together for a client last year. The screencast got quite
a bit of views and the example project may help you.

Knock
Seamless JWT authentication for Rails API
class User < ActiveRecord::Base
has_secure_password
end
Works with any model that
has an authenticate method
Like the one rails provides via has_secure_password...
https://github.com/nsarno/knock#knock

Knock
Seamless JWT authentication for Rails API
class ApplicationController < ActionController::API
include Knock::Authenticable
end
class SecuredController < ApplicationController
before_action :authenticate_user
def index
# etc...
end
end
https://github.com/nsarno/knock#knock

JWT Works Within OAuth
but Doesn’t Replace it.
http://www.seedbox.com/en/blog/2015/06/05/oauth-2-vs-json-web-tokens-comment-securiser-un-api/
Check out this article explaining JWT vs. OAuth:
What about OAuth?

Doorkeeper.configure do
access_token_generator "Doorkeeper::JWT"
end
Doorkeeper
https://github.com/doorkeeper-gem/doorkeeper#custom-access-token-generator
https://github.com/chriswarren/doorkeeper-jwt
Doorkeeper Gem (custom access token generator):
Doorkeeper::JWT Gem:

What’s OAuth?
I don’t have time to
cover it in this talk

OAuth addresses security
concerns such as revoking
tokens or refreshing tokens
to allow your user to
remain authenticated.

OAuth Resources
JWT + Refresh Tokens = OAuth2?
https://stormpath.com/blog/jwt-authentication-angularjs
Try out Doorkeeper
https://github.com/doorkeeper-gem/doorkeeper

We can’t rely on
rails’ magical cookies

Instead...
implement a token based
authentication strategy

Consider... implementing
OAuth via Doorkeeper
or Other Means

user web app server
V1V1
Updates to a monolithic
rails web app / api...

user web app server
V2 V2
Are instant!
for the most part...

V2
Not with external clients!
i.e. mobile apps!
V2
V1

You Lose Control of the Upgrade Process...
V3
V1 V3V3V2
V3

The Mobile Dev(s) Might Not
be on Their A-Game Slowing
Their Own Release Cycle.

Respective App Stores Take
Time to Review and Propogate
the Update to Your Mobile App
At least it’s down to about 1 day vs. a week...

Your Users Might Not Upgrade
for a Variety of Reasons

1 Version the API
2 Track the Client Builds

Versioning is Trivial
if You Start Early

Without Versioning
Code Smell
is Highly Likely

...or You’ll Probably
Break the App
...at some point not immediately apparent...

Namespace Your Controllers
module V1
class ArticlesController < ApplicationController
def index
articles = Article.trendy
respond_to do |format|
format.json do
render json: articles
end
end
end
end
end
Just Wrap’em in a Module!

Use a Route Constraint
This constraint parses the version from an HTTP Header.
class ApiConstraint
attr_reader :version
def initialize(options)
@version = options.fetch(:version)
end
def matches?(request)
request.headers.fetch(:accept).include?("version=#{version}")
end
end

Scope Your Routes
See the full tutorial on how to do this via Big Nerd Ranch:
https://www.bignerdranch.com/blog/adding-versions-rails-api/
Rails.application.routes.draw do
scope module: :v1, constraints: ApiConstraint.new(version: 1) do
resources :articles, only: :index
end
scope module: :v2, constraints: ApiConstraint.new(version: 2) do
resources :articles, only: :index
end
end

Also Check Out Grape
http://www.ruby-grape.org

Mounts as an Engine
Rails.application.routes.draw do
mount Twitter::API => '/'
end

Supports Versioning
class Twitter::API < Grape::API
mount Twitter::APIv1
mount Twitter::APIv2
end

Has its Own DSL
module Twitter
class Grape < Grape::API
version 'v1', using: :header, vendor: 'twitter'
format :json
prefix :api
resource :statuses do
desc 'Return a public timeline'
get :public_timeline do
Status.limit(20)
end
end

Separates API from Web App
app
api
models
views
controllers

Grape solves a lot of problems
specific to building an API
that Rails does not and
perhaps is never meant to
[Rails is a web application framework]

2 Track Client Builds
Version the API

Multiple Iterations of the
App Now Supported
V3
V1V3V3 V2
V3 V2 V1

What Happens When You Need/Want
to Stop Supporting a Version?
V3
V1V3V3 V2
V3 V2 V1

$ curl http://localhost:3000/api/builds/457
[{"support_level":”active”}]
Communicate to Your Users
Treat Builds/Platforms Like a Resource

[{"support_level":”supported”}]
Everything works as usual...

[{"support_level":”deprecated”}]
Prod User to Upgrade
oknot now
A new version is
available. You
really ought to
download it!

[{"support_level":”unsupported”}]
Force User to Upgrade
Go to App Store
This Version is
Not Supported

Several Releases of the App Can
be Using Any Version of the API
V3
V1V3V3 V2
V3 V2 V1
2.1.0
2.0.2
2.0.1
1.9.0
1.8.9

What if a Release Ships w/ a
Catastrophic Bug?
V1V3V3 V2
2.1.0
2.0.2
2.0.1
1.9.0
1.8.9

[{"support_level":”unsupported”}]
Force User to Upgrade
Go to App Store
This Version is
Not Supported

Supply the Build & Platform
on All Requests
$ curl -H “X-API-Client: iOS_457”
http://localhost:3000/api/articles

Patch the Emergency
module Twitter
class Grape < Grape::API
...
helpers do
def issue_119?
headers[”X-API-Client”] == “iOS_457”
end
end
resource :statuses do
desc 'Return a public timeline'
get :public_timeline do
return fix_for_119 if issue_119?
Status.limit(20)
end
end

Monkey Patching Your
API Should Only be a
Temporary Solution
FOR EMERGENCY USE ONLY

When a Rails Application
is Behaving as an API
but Does Not Have Versioning
Implemented... You Might
See a Lot of Monkeying Around.

Version the API
Track Client Builds

What’s Wrong with the Date?
{
event_name: “Beer ‘o Clock”,
starts_at: “2015-07-04 5:00PM”
}

See you at 5pm?
Never EVER Forget about Timezones :)
PST
CST
EST

Rely on Standards
Time.now.utc.iso8601
"2016-06-28T01:13:54Z"
Time.now.utc.to_i
1467076518

Your Mobile Client Knows What
Timezone Your User is in. Let
it Convert UTC to Local Time.

Ruby is too Convenient!
Which of the Following Should You
Use to Query Dates on the Server?
Date.today Time.current
system time application time
https://robots.thoughtbot.com/its-about-time-zones

Avoid Excessive Biz
Logic on the Client
When Possible

# /users/current
{
”linked_device”:”none”,
”can_edit_health_metrics”:true,
”health_services_enabled”:false
}

# User.swift
func canUseHealthKit() -> Bool {
return linkedDevice == ”none” &&
canEditHealthMetrics &&
!healthServicesEnabled
}

# /users/current
{
...
”device_health_service”:”Available”,
...
}

# SettingsViewController.swift
let user = Session.currentUser()
if user.deviceHealthService == .Available {
...
}

Saves You from Duplicate
Logic in iOS and Android

Biz Logic is More Nimble
if You Can Avoid Hardcoding
it in the Client Libraries

Utilize Tokens Preferably
Lightweight ones Like JWTs.

Have Your API and Client
Share their Versions.

Let the Client handle Formatting

Simplify Complex State on the Server

Building Mobile Friendly APIs in Rails

Recommended

Recommended

More Related Content

What's hot

What's hot (20)

Similar to Building Mobile Friendly APIs in Rails

Similar to Building Mobile Friendly APIs in Rails (20)

Recently uploaded

Recently uploaded (20)

Building Mobile Friendly APIs in Rails