design driven api development
TRANSCRIPT
Design-Driven API DevelopmentSokichi Fujita
Generation of API Description Languages
Swagger
RAML
API-Blueprint
API Description Languages
• XML • WADL, RADL, WSDL2
• JSON
• Swagger, I/O Docs
• YAML
• Swagger, RAML
• Markdown
• API-Blueprint
Popular in GitHub, NPM, …
Why
Server Code
API Document SDKs
Specification Document
Samples
Mock Server
API Console
Test code
Manually developed resources
as a reference
Server Code
API Document SDKs
Samples
Mock Server
API Console
Test code
Manually developed resources
It is incorrect or
doesn’t exist
Sometimes,
To avoid publishing un-updatable APIs
• Publishing or updating API are not so hard,
• if you can ignore lots of related resources.
• e.g. SDKs, Documents, Tests, Clients, …
Design-Driven Development
Server Code
API Document SDKs
API Schema
generate/validate
SamplesAPI ConsoleMock Server
Non-manually developed resources
codegenswagger-UIswagger-node
swagger-spec
swagger-editor
swagger-js
Demo
Demo
• Hacker News API
• Swagger-Node
• Hacker News Client
• React, Swagger-js, Electron
Swagger-nodeElectron
*.yaml
Swagger Editor
Express
express-swagger
controller
React
Swagger-js
- component DidMount etc.
state
render
(Dynamically JS SDK)
Cheerio
https://news.ycombinator.com
Server : Swagger-Node
swagger project create [project name]
swagger project edit
1. Generate a template for express | hapi | restify | sails
2. Write API specs
vim api/controller/[controller file name].js
3. Just write controllers that meet the API specs
filename of the controllers
name of the controller
Client : Swagger-js
var swagger = new SwaggerClient({ url: "http://localhost:8080/swagger.yaml", success: function() { swagger.apis.hackernews.fetch( {page:api}, {responseContentType: 'application/json'}, function(res) { :
}); }});
Dynamically Swagger SDK for JavaScript
Client : Swagger-js with React
var self = this;var swagger = new SwaggerClient({ url: "http://localhost:8080/swagger.yaml", success: function() { swagger.apis.hackernews.fetch( {page:api}, {responseContentType: 'application/json'}, function(res) { self.setState({data:res.obj}); }); }});
at componentDidMount