Slide 1
Slide 1 text
Designing & Building
RESTful JSON APIs
Ahmed Omran
@this_ahmed
github.com/aomra015
Slide 2
Slide 2 text
1.What is an API and why build one?
2.How to design & build an API
3.Misc things to consider
Slide 3
Slide 3 text
User Interface
Slide 4
Slide 4 text
Application Programming Interface
Slide 5
Slide 5 text
API
“Outside” “Inside”
Slide 6
Slide 6 text
API
“Outside”
Server,!
Device,!
Software
library, etc.
“Inside”
Slide 7
Slide 7 text
API
“Outside”
Server
“Inside”
Web APIs
HTTP
Client
Slide 8
Slide 8 text
Outside
Client
Slide 9
Slide 9 text
Multiple Clients
Slide 10
Slide 10 text
Multiple Clients
Slide 11
Slide 11 text
Multiple Clients
Slide 12
Slide 12 text
Multiple Clients
Slide 13
Slide 13 text
Multiple Clients
Slide 14
Slide 14 text
Programmer == Customer
Slide 15
Slide 15 text
Goal: happy & productive
programmer
Slide 16
Slide 16 text
API Happiness
• Shared Solution (REST)
• Flexible
Slide 17
Slide 17 text
Shared Solution
Slide 18
Slide 18 text
Shared Solution Uniform
Slide 19
Slide 19 text
Shared Solution Uniform Consistent
Slide 20
Slide 20 text
Shared Solution Uniform Consistent
Predictable
Slide 21
Slide 21 text
Representational State Transfer
Shared Solution Uniform Consistent
Predictable
Slide 22
Slide 22 text
Server
Client
Request
Response
Slide 23
Slide 23 text
Resources
Client
API
Representations
Server
Slide 24
Slide 24 text
!
Contact data
in database
Client
!
!
API
Contact Data !
JSON over HTTP
for our example…
Slide 25
Slide 25 text
How does client find resource?
Slide 26
Slide 26 text
URL = HTTP, hostname, URI
e.g. http://www.easycontacts.com/contacts
Slide 27
Slide 27 text
URL = HTTP, hostname, URI
e.g. http://www.easycontacts.com/contacts
Uniform
Resource
Identifier
Slide 28
Slide 28 text
URL = HTTP, hostname, URI
e.g. http://www.easycontacts.com/contacts
Nouns
identify
resources
Slide 29
Slide 29 text
collection: /contacts!
item: /contacts/:id
Two URIs per resource
Slide 30
Slide 30 text
Building the API
$ gem install rails-api
$ rails-api new easycontacts
It’s rails without the stuff you don’t need…
Slide 31
Slide 31 text
Respond to
• What: Uniform Resource Identifier (URI)
• How: HTTP Verb to specify action
Slide 32
Slide 32 text
Rails.application.routes.draw do
get "/contacts"
end
Slide 33
Slide 33 text
Rails.application.routes.draw do
get "/contacts"
end
URIs
HTTP
Verb
Slide 34
Slide 34 text
Rails.application.routes.draw do
get "/contacts"
get "/contacts/:id"
end
Read
Read
Slide 35
Slide 35 text
Rails.application.routes.draw do
get "/contacts"
post "/contacts"
get "/contacts/:id"
end
Read
Read
Create
Slide 36
Slide 36 text
Rails.application.routes.draw do
get "/contacts"
post "/contacts"
get "/contacts/:id"
put "/contacts/:id"
end
Read
Read
Create
Update
Slide 37
Slide 37 text
Rails.application.routes.draw do
get "/contacts"
post "/contacts"
get "/contacts/:id"
put "/contacts/:id"
delete "/contacts/:id"
end
Read
Read
Create
Update
Delete
Slide 38
Slide 38 text
Response =
Status Code + JSON
Slide 39
Slide 39 text
JSON
Slide 40
Slide 40 text
Rails.application.routes.draw do
namespace :api, :defaults => {:format => :json} do
get "/contacts"
post "/contacts"
get "/contacts/:id"
put "/contacts/:id"
delete "/contacts/:id"
end
end
Slide 41
Slide 41 text
Rails.application.routes.draw do
namespace :api, :defaults => {:format => :json} do
get "/contacts"
post "/contacts"
get "/contacts/:id"
put "/contacts/:id"
delete "/contacts/:id"
end
end
/api/URI
Slide 42
Slide 42 text
Rails.application.routes.draw do
namespace :api, :defaults => {:format => :json} do
get "/contacts", to: "contacts#index"
post "/contacts", to: "contacts#create"
get "/contacts/:id", to: "contacts#show"
put "/contacts/:id", to: "contacts#update"
delete "/contacts/:id", to: "contacts#destroy"
end
end
Slide 43
Slide 43 text
JSON Response Formatting
gem “active_model_serializers”
!
Implementation of JSON-API.org standard
Slide 44
Slide 44 text
Response =
Status Code + JSON
Slide 45
Slide 45 text
Status Codes
• 200, Ok => Successful GET
• 204, No Content => Successful DELETE or PUT
• 201, Created => Successful POST
• 422, Unprocessable Entity => Well formed request but there’s a
semantic error. i.e. problem creating or updating a resource.
• 401, Unauthorized => Authentication credentials missing or
incorrect
Slide 46
Slide 46 text
Respond with JSON & Status Code
class ContactsController < ApplicationController
def index
@contacts = Contact.all
render json: @contacts, status: :ok
end
end
200
Slide 47
Slide 47 text
class ContactsController < ApplicationController
def show
render json: @contact
end
end
200
Slide 48
Slide 48 text
class ContactsController < ApplicationController
def destroy
@contact.destroy
!
head :no_content
end
end
204
Slide 49
Slide 49 text
class ContactsController < ApplicationController
def update
if @contact.update(contact_params)
head :no_content
else
render json: @contact.errors, status: :unprocessable_entity
end
end
end
204
422
Slide 50
Slide 50 text
def create
@contact = Contact.new(params[:contact])
!
if @contact.save
render json: @contact, status: :created
else
render json: @contact.errors, status: :unprocessable_entity
end
end
201
422
Slide 51
Slide 51 text
def create
@contact = Contact.new(params[:contact])
!
if @contact.save
render json: @contact, status: :created
else
render json: @contact.errors, status: :unprocessable_entity
end
end
Verbose errors
Tell
client
what
went wrong
Slide 52
Slide 52 text
Verbose Errors
Slide 53
Slide 53 text
Consume APIs w/ REST Clients
• Front-end: ngResource, Ember Data
• Gems: ActiveResource, Rest-Client
Slide 54
Slide 54 text
Flexible
sweep complexity in the query string
Slide 55
Slide 55 text
Flexible
/contacts?key1=value1&key2=value2
Slide 56
Slide 56 text
Filtering
/contacts?relationship=friend
Slide 57
Slide 57 text
Sorting
/contacts?order=created_at:desc
Slide 58
Slide 58 text
Search
/contacts?q=ahmed
Slide 59
Slide 59 text
Pagination
/contacts?limit=25&offset=50
gem 'kaminari'
Slide 60
Slide 60 text
Side-load Associated
Resources
/contacts/25?include=notes
Slide 61
Slide 61 text
Misc.
Slide 62
Slide 62 text
Non-resource responses
• /calculate, /translate, /convert ??
• use verbs & make it clear in API docs
• or POST /calculations, /translations, /conversions
Slide 63
Slide 63 text
Use HTTPS.
# config/environments/production.rb
MyApp::Application.configure do
config.force_ssl = true
end
Slide 64
Slide 64 text
Versioning
Rails.application.routes.draw do
namespace :api, :defaults => {:format => :json} do
namespace :v1 do
… routes …
end
end
end
Slide 65
Slide 65 text
Caching
Set etag and last_modified response Headers
Slide 66
Slide 66 text
Caching
Set etag and last_modified response Headers
When
was the
resource
Last-
Modified?
Slide 67
Slide 67 text
Caching
Set etag and last_modified response Headers
Identifies
a specific
version of a
resource
Slide 68
Slide 68 text
Caching
If both haven’t changed — 304 Not Modified
Slide 69
Slide 69 text
class ContactsController < ApplicationController
def show
render json: @contact if stale?(@contact)
end
end
Slide 70
Slide 70 text
gzip compression
class Application < Rails::Application
config.middleware.use Rack::Deflater
end
Slide 71
Slide 71 text
CORS
Same-Origin Policy Problem
gem 'rack-cors'
Slide 72
Slide 72 text
Authentication
• Basic (username & password)
• Token (Api Key)
• OAuth (like Valet key)
Slide 73
Slide 73 text
Documentation
gem ‘rspec_api_documentation’
gem 'apipie-rails'
Slide 74
Slide 74 text
Test your APIs …
• Command line: cURL or httpie
• Browser: Postman, JSON-formatter
• RSpec: Request Specs
• Rails Minitest: Integration tests
Slide 75
Slide 75 text
Thank you!
Ahmed Omran
@this_ahmed
https://github.com/aomra015/api-presentation