Share
Embed
Build API with Swagger
Wu Jiang
October 12, 2015
Transcript
49 slides
-
Swagger Implement Web API documents Jiang Wu 2015-10-11 Jiang Wu
Swagger 2015-10-11 1 / 49 -
Context 1 Introduction 2 Swagger 3 PostgREST 4 Summary Jiang
Wu Swagger 2015-10-11 2 / 49 -
Oops!…I did it again Figure: RubyConf Taiwan 2015 Jiang Wu
Swagger 2015-10-11 5 / 49 -
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 -
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 -
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 -
Constraints HTTP/1.1 JSON data format REST architecture style Jiang Wu
Swagger 2015-10-11 9 / 49 -
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 -
Components Rails + doorkeeper OAuth admin page OAuth grant flow
Grape + doorkeeper Handle OAuth token Jiang Wu Swagger 2015-10-11 11 / 49 -
API documentations Must be significant, clear and accurate. 重要 跨项⽬组,跨公司
清楚 减少交流成本 正确 和代码保持同步 Jiang Wu Swagger 2015-10-11 12 / 49 -
程序员最痛恨两件事 写⽂档 别⼈不写⽂档 Coders hate 2 things: writing documentation and
no documentation. Solution ’D’o not ’R’epeat ’Y’ourself Priciple Jiang Wu Swagger 2015-10-11 13 / 49 -
Remove duplication documentation -> code WSDL code -> documentation RDoc,
YARD, Rocco(annotated source code) literate programming noweb, Org Mode, Literate Haskell Jiang Wu Swagger 2015-10-11 14 / 49 -
Context 1 Introduction 2 Swagger 3 PostgREST 4 Summary Jiang
Wu Swagger 2015-10-11 16 / 49 -
Definitions Swagger Describe REST services Swagger UI Live testable documentation
grape-swagger Generate API description Jiang Wu Swagger 2015-10-11 18 / 49 -
Describe REST services API routes Input types Output types Authorizations
Jiang Wu Swagger 2015-10-11 19 / 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 -
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 -
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 -
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 -
Input types params do requires :name, type: String optional :public,
type: Boolean, default: false end Jiang Wu Swagger 2015-10-11 24 / 49 -
Validation of input types Validate requests and return 400 status
code for typecast error or missing value. Jiang Wu Swagger 2015-10-11 25 / 49 -
Output types class Project < Grape::Entity # Output fields expose
:name, documentation: { type: 'string', desc: 'Project name' } end Jiang Wu Swagger 2015-10-11 26 / 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 -
Swagger information (1) Delare with add_swagger_documentation api_version mount_path authorizations info
Jiang Wu Swagger 2015-10-11 28 / 49 -
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 -
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 -
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 -
Short summary of Swagger API routes Input types Output types
Authorizations Jiang Wu Swagger 2015-10-11 32 / 49 -
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 -
WebView or not? 1st edition, use WebView 2nd edition, native
view 3rd edition, WebView (Electron) Jiang Wu Swagger 2015-10-11 34 / 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 -
Context 1 Introduction 2 Swagger 3 PostgREST 4 Summary Jiang
Wu Swagger 2015-10-11 36 / 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 -
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 -
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 -
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 -
Pagination -> Range headers GET /items HTTP/1.1 Range-Unit: items Range:
0-24 HTTP/1.1 206 Partial Content Accept-Ranges: items Content-Range: 0-24/100 Range-Unit: items Jiang Wu Swagger 2015-10-11 41 / 49 -
DML -> HTTP methods insert POST update PATCH upsert/merge PUT
delete DELETE Jiang Wu Swagger 2015-10-11 42 / 49 -
DB Roles -> Authorizations Need extra work to support normal
database-based authentication and authorizations. Jiang Wu Swagger 2015-10-11 43 / 49 -
Why PostgREST? Counter attack to NoSQL Bare metal speed (written
in Haskell) HTTP protocol Jiang Wu Swagger 2015-10-11 44 / 49 -
Context 1 Introduction 2 Swagger 3 PostgREST 4 Summary Jiang
Wu Swagger 2015-10-11 45 / 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 -
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 -
Apply DRY principle Abstract instead of duplicate Select proper tools
Bring values Jiang Wu Swagger 2015-10-11 48 / 49 -
Q&A Questions? Twitter: @masterwujiang Github: @nouse Linkedin: @nouse Jiang Wu
Swagger 2015-10-11 49 / 49