Do you remember this?
Jiang Wu Swagger 2015-10-11 3 / 49
Slide 4
Slide 4 text
本尊在此 It’s me!
Jiang Wu Swagger 2015-10-11 4 / 49
Slide 5
Slide 5 text
Oops!…I did it again
Figure: RubyConf Taiwan 2015
Jiang Wu Swagger 2015-10-11 5 / 49
Slide 6
Slide 6 text
Presentation Tools
Rabbit
▶ Written in Ruby
▶ Matz uses this
▶ Has time control
Please allow me off topic one more page…
Jiang Wu Swagger 2015-10-11 6 / 49
Slide 7
Slide 7 text
Code of Conduct
Ruby China played well against
sexism.
RubyConf China should have
conference code of conduct.
Bundler now creates contributor code
of conduct for you.
Jiang Wu Swagger 2015-10-11 7 / 49
Slide 8
Slide 8 text
Scenario
Rails application
3 types of API consumers
▶ Native application
(iOS/Android/PC/Mac)
▶ Third party service
▶ JavaScript: single page application
Jiang Wu Swagger 2015-10-11 8 / 49
Slide 9
Slide 9 text
Constraints
HTTP/1.1
JSON data format
REST architecture style
Jiang Wu Swagger 2015-10-11 9 / 49
Slide 10
Slide 10 text
Ruby Libraries
grape REST services
doorkeeper OAuth provider
Thanks yorkxin’s blog for the help.
Will try wine bouncer next time(thanks
sinalpha).
Jiang Wu Swagger 2015-10-11 10 / 49
Implementation
1
Grape basic declaration
2
Namespace and routes
3
’params’ -> input type
4
Grape::Entity -> output type
5
Swagger information
Jiang Wu Swagger 2015-10-11 20 / 49
Slide 21
Slide 21 text
Grape basic declaration
class API < Grape::API
# API routes prefix
prefix 'api'
# API version
version 'v1', using: :path
# load other API
mount Endpoints
end
Jiang Wu Swagger 2015-10-11 21 / 49
Slide 22
Slide 22 text
namespaces
namespace "projects" do
mount ProjectsAPI
# could be variable value
# and cascadable
namespace ":identity" do
mount SingleProjectAPI
end
end
Jiang Wu Swagger 2015-10-11 22 / 49
Slide 23
Slide 23 text
API routes
Sinatra like DSL, declared with HTTP
methods.
desc "Show single project"
# get|post|put|patch|delete
get "/:project" do
# Your implementation
end
Jiang Wu Swagger 2015-10-11 23 / 49
Refer to other types
class Project < Grape::Entity
expose :owner,
# with 'using'
using: Account,
documentation: {
type: 'Account'
}
end
Jiang Wu Swagger 2015-10-11 27 / 49
Slide 28
Slide 28 text
Swagger information (1)
Delare with
add_swagger_documentation
api_version
mount_path
authorizations
info
Jiang Wu Swagger 2015-10-11 28 / 49
Slide 29
Slide 29 text
Swagger informations (2)
Add documentaions of
namespace
params
output types (options of ’desc’)
OAuth scopes (options of ’desc’)
API codes (options of ’get’/’post’)
Jiang Wu Swagger 2015-10-11 29 / 49
Slide 30
Slide 30 text
Live Test
Similiar as doctest of Python
""" input and output, REPL way
>>> factorial(5)
120
"""
def factorial(n):
Documentation is both sample and test.
Jiang Wu Swagger 2015-10-11 30 / 49
Slide 31
Slide 31 text
API test before Swagger
Write it by yourself
Browser plugins (not quite works)
RestClient Firefox + Chrome
Proprietary softwares
Postman Chrome + NodeJS
Paw Mac
Jiang Wu Swagger 2015-10-11 31 / 49
Slide 32
Slide 32 text
Short summary of Swagger
API routes
Input types
Output types
Authorizations
Jiang Wu Swagger 2015-10-11 32 / 49
Slide 33
Slide 33 text
Swagger clients
REST clients, not Swagger specific.
Generate with swagger-codegen,
supports Android and iOS.
Dynamic code generation in
JavaScript/Ruby/Python.
Jiang Wu Swagger 2015-10-11 33 / 49
Pitfall
Grape supports wildcard(*) path, while
live documentation doesn’t, and we found
out bug was in grape-swagger.
Jiang Wu Swagger 2015-10-11 35 / 49
Unleash power of database
API Database
Routes Tables/Views
Input types Constraints, Types
Output types Table columns
Authorizations Roles
Jiang Wu Swagger 2015-10-11 37 / 49
Slide 38
Slide 38 text
Design philosophy
Can we use the declarative
information in a relational db
schema to mechanically generate
an HTTP API?
begriffs
Jiang Wu Swagger 2015-10-11 38 / 49
Slide 39
Slide 39 text
Features of PostgreSQL
Data types Array, HStore, GIS,
JSONB(since 9.4)
Procedure languages PL/pgSQL,
PL/Python, PL/V8
Message queue NOTIFY/LISTEN
Full text search tsvector/tsquery
Jiang Wu Swagger 2015-10-11 39 / 49
Slide 40
Slide 40 text
Schema -> API
Schema path -> API version
Tables/views -> API routes
Where clause -> query params
GET
/projects?age=lt.P7D&public=eq.true
Query projects created in 7 days and
public.
Jiang Wu Swagger 2015-10-11 40 / 49
Swagger
Describe REST services.
Provide Live testable documentation
with Swagger UI.
Can generate with grape-swagger.
Disadvantage: have to investigate
across components when debugging.
Jiang Wu Swagger 2015-10-11 46 / 49
Slide 47
Slide 47 text
PostgREST
DB Schema -> API
Rediscover values of RDBMS
Advantage: can utilize mature tools
built around RDBMS, like graphivz
Jiang Wu Swagger 2015-10-11 47 / 49