Embed Size (px)
Citation preview
Design Driven APIs with Node.js and SwaggerJeremy Whitlock (@whitlockjc)Software Engineer
1
What is an API?
2
3
Need vectors of these elements
Need correct heart
API Documentation
4
5
Need vectors of these elements
Need correct heart
API Documentation is “Critical”
"While APIs are meant for computers, applications, and other systems, integrations all begin with helping other humans understand the what, and how of what an API does, making API docs a critical point in the API journey."
6©2015 Apigee. All Rights Reserved.
7
Need vectors of these elements
Need correct heart
If It Isn't Documented, It Doesn't Exist
“No matter how wonderful your library is and how intelligent its design, if you're the only one who understands it, it doesn't do any good. Documentation means not just autogenerated API references, but also annotated examples and in-depth tutorials. You need all three to make sure your library can be easily adopted.”
8©2015 Apigee. All Rights Reserved.
Nicholas Zakas
http://blog.codinghorror.com/if-it-isnt-documented-it-doesnt-exist/
9
Need vectors of these elements
Need correct heart
Good API Documentation
10©2015 Apigee. All Rights Reserved.
Good API Documentation
11
API Documentation should be easy to understand.
12
Need vectors of these elements
Need correct heart
WHY ALL THE API DOCUMENTATION TALK?
Swagger
13
Sample Swagger Document
14©2015 Apigee. All Rights Reserved.
• Written in JSON or YAML• Clearly describe:
• Available APIs• API input contract• API output contract• Required authn/authz• Success/Error responses• …
• Extensible
Swagger Emerging as an Industry Standard
15©2015 Apigee. All Rights Reserved.
There is More to Swagger Than This!
16©2015 Apigee. All Rights Reserved.
How Do I Use Swagger?
17
Code Driven Swagger
18©2015 Apigee. All Rights Reserved.
Swagger
Duplication
Code Driven Swagger
19©2015 Apigee. All Rights Reserved.
Swagger
Swagger Driven Code
20©2015 Apigee. All Rights Reserved.
Emphasis slide
21
Before (43 lines) After (14 lines)
22
Need vectors of these elements
Need correct heart
WHICH APPROACH IS BETTER?
Swagger Driven APIs
23
API Design
24
http://apistudio.io
API Design
25
http://apistudio.io
API Design
26
http://apistudio.io
27
Need vectors of these elements
Need correct heart
Swagger Driven Node.js APIs
28
npm install -g swagger
Swagger Driven Node.js APIs
29
npm install -g swagger
Swagger
Swagger Metadata
Routing
Security
Request Validation
Response Validation
Business Logic
Thank You
30
