I Love APIs 2015

1. 1
WORKSHOP
Design-First API Development Using Swagger & Node
Apigee Engineering

2. Agenda
2
1.
What is Design-First API
Development?
2. Installation
3. The famous hello-world
4. Project Conventions
5. Mock mode i.e response simulation
6. Query Parameters
7. Adding a new operation
8. How about POST?
©2015 Apigee. All Rights Reserved.

3. Some social media love
3©2015 Apigee. All Rights Reserved.

4. Some social media love
@apigee Awesome API development workshop #iloveapis #nodejs
4©2015 Apigee. All Rights Reserved.

5. APIs are for…
Developers
Apps :
● External
● Internal
Microservices
Devices
5©2015 Apigee. All Rights Reserved.

6. Design-First API
Development
6

7. Zen of API Development
The code defines the API
The API generates the code
The code is the API
API-driven code
7©2015 Apigee. All Rights Reserved.

8. API-driven code philosophy
8©2015 Apigee. All Rights Reserved.
The API must be designed first.
The artifact that represents the API design must drive the API runtime.
The API design will change, and the framework must make it possible to
adapt quickly without letting the code, design, and documentation fall out
of sync.
The "DRY" Principle

9. Swagger-Node
9

10. Swagger-Node
10©2015 Apigee. All Rights Reserved.
The API is written in Swagger, optionally using Swagger-Editor
The Swagger API document is parsed when server starts
Incoming calls are classified, validated, and routed in real time
Integrates with Connect, Express, Hapi, Restify, Sails...
Incorporates a plugin model for Swagger (or non-Swagger) extensions

11. Swagger-Node: Flow Diagram
11©2015 Apigee. All Rights Reserved.

12. But why Swagger ?
12©2015 Apigee. All Rights Reserved.

13. But why Node.js ?
13©2015 Apigee. All Rights Reserved.

14. Installation
14

15. Installation -1
1. Make sure you have node.js installed. v4.1.2 preferred.
https://nodejs.org/en/
$ node --version
15©2015 Apigee. All Rights Reserved.

16. Installation -2
Install
$ sudo npm install -g swagger
Verify:
$ swagger --version
0.7.4
DONE
16©2015 Apigee. All Rights Reserved.

17. What do you get?
• CLI
• project scaffolding
• project lifecycle
• Your own API Studio (sort of :-))
• Write YAML
• Immediate feedback loop
• Try-it on the fly
• Runtime
17©2015 Apigee. All Rights Reserved.

18. Let’s take a tour of API Studio
• Code Completion
• Immediate feedback loop
• Simulated Response aka “Mock Mode”
• Collaboration
• Download YAML/JSON & Node.js project
• Generated doc
• Raw Spec endpoint
18©2015 Apigee. All Rights Reserved.

19. Let’s create a project
$ swagger project create
19©2015 Apigee. All Rights Reserved.

20. Let’s run the project
$ cd $project-name
$ swagger project start
20©2015 Apigee. All Rights Reserved.

21. Let’s make some API call
$ curl http://127.0.0.1:10010/hello?name=Scott
21©2015 Apigee. All Rights Reserved.

22. Let’s not forget the tests
$ swagger project generate-test
$ swagger project test
22©2015 Apigee. All Rights Reserved.

23. How about editing ?
$ swagger project edit
23©2015 Apigee. All Rights Reserved.

24. Dissecting it
• Project Conventions
• swagger spec
• controllers
• helpers
24©2015 Apigee. All Rights Reserved.

25. Let’s add something new
• A new path that uses POST operation
25©2015 Apigee. All Rights Reserved.

26. ..which requires
• A new controller
26©2015 Apigee. All Rights Reserved.

27. Try it out
curl -X POST http://127.0.0.1:10010/conf/add -H
"content-type:application/json" -d '{"x":5,"y":6}'
27©2015 Apigee. All Rights Reserved.

28. How about some API Management
• Let’s add quota
28©2015 Apigee. All Rights Reserved.

29. Quota : Get the bits
• Let’s add quota [This is subject to change. See latest at https://github.com/apigee-
127/volos-swagger-apply/blob/master/README.md]
npm install --save volos-swagger-apply
npm install --save volos-quota-memory
29©2015 Apigee. All Rights Reserved.

30. Quota : Annotate your Swagger
x-volos-resources:
MyQuota:
provider: volos-quota-memory
options:
timeUnit: minute
interval: 1
allow: 1
x-volos-apply:
MyQuota: {}
30©2015 Apigee. All Rights Reserved.

31. Quota : Tell the framework about it.
Add fitting to config/default.yaml to swagger_controllers :
- volos-swagger-apply
31©2015 Apigee. All Rights Reserved.

32. Quota : Verify that it works
curl -X POST http://127.0.0.1:10010/conf/add -H "content-type:
application/json" -d '{"x":5,"y":6}'
{"message":"exceeded quota","status":403}
32©2015 Apigee. All Rights Reserved.

33. Deploy to Apigee
sudo npm install -g apigeetool
apigeetool deploynodeapp -u sdoe@apigee.com -o sdoe -e test -n 'Test Node App 2' -d . -m app.js -b /node2
OR
a127 project deploy
33©2015 Apigee. All Rights Reserved.

34. Source: https://github.com/prabhatjha/iloveapi2015
Community: https://community.apigee.com
Github:
github.com/apigee
github.com/apigee-127
Where can I get help?
34©2015 Apigee. All Rights Reserved.

35. Thank You
35