Design Driven API Development

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