Design Driven API Development

Design Driven API Development

1. 1. Design-Driven API Development Sokichi Fujita
2. 2. Generation of API Description Languages
3. 3. Swagger
4. 4. RAML
5. 5. API-Blueprint
6. 6. API Description Languages • XML • WADL, RADL, WSDL2 • JSON • Swagger, I/O Docs • YAML • Swagger, RAML • Markdown • API-Blueprint Popular in GitHub, NPM, …
7. 7. Why
8. 8. Server Code API Document SDKs Specification Document as a reference Manually developed resources
9. 9. Server Code API Document SDKs Specification Document Samples Mock Server API Console Test code Manually developed resources as a reference
10. 10. Server Code API Document SDKs Samples Mock Server API Console Test code Manually developed resources incorrect or doesn’t exist Sometimes…
11. 11. To avoid publishing un-updatable APIs • API changing is not so difficult, • if you can ignore lots of resources. • e.g. SDKs, Documents, Tests, Clients, …
12. 12. Design-Driven Development
13. 13. 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
14. 14. Demo
15. 15. Demo • Hacker News API • Swagger-Node • Hacker News Client • React, Swagger-js, Electron
16. 16. 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
17. 17. 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. Write controllers that meet the API specs
18. 18. filename of the controllers name of the controller
19. 19. 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
20. 20. 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