I Love APIs 2015

1. Design Driven APIs with Node.js and Swagger
Jeremy Whitlock (@whitlockjc)
Software Engineer
1

2. What is an API?
2

3. 3
Need vectors of these elements
Need correct
heart

4. API Documentation
4

5. 5
Need vectors of these elements
Need correct
heart

6. 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. 7
Need vectors of these elements
Need correct
heart

8. 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. 9
Need vectors of these elements
Need correct
heart

10. Good API Documentation
10©2015 Apigee. All Rights Reserved.

11. Good API Documentation
11
API Documentation should be easy to understand.

12. 12
Need vectors of these elements
Need correct
heart
WHY ALL THE API DOCUMENTATION TALK?

13. Swagger
13

14. 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

15. Swagger Emerging as an Industry Standard
15©2015 Apigee. All Rights Reserved.

16. There is More to Swagger Than This!
16©2015 Apigee. All Rights Reserved.

17. How Do I Use Swagger?
17

18. Code Driven Swagger
18©2015 Apigee. All Rights Reserved.
Swagger
Duplication

19. Code Driven Swagger
19©2015 Apigee. All Rights Reserved.
Swagger

20. Swagger Driven Code
20©2015 Apigee. All Rights Reserved.

21. Emphasis slide
21
Before (43 lines) After (14 lines)

22. 22
Need vectors of these elements
Need correct
heart
WHICH APPROACH IS BETTER?

23. Swagger Driven APIs
23

24. API Design
24
http://apistudio.io

25. API Design
25
http://apistudio.io

26. API Design
26
http://apistudio.io

27. 27
Need vectors of these elements
Need correct
heart

28. Swagger Driven Node.js APIs
28
npm install -g swagger

29. Swagger Driven Node.js APIs
29
npm install -g swagger
Swagger
Swagger Metadata
Routing
Security
Request Validation
Response Validation
Business Logic

30. Thank You
30