1. DevNet API Scavenger Hunt
How I built a REST microservice
Ashley Roach – Cisco DevNet
Principal Engineer & Evangelist
@aroach

2. About Me API & Cloud Evangelist 10+ Yrs Technical Product Mgmt
Life-long, self-taught developer
Denver, CO
github.com/aroach & github.com/ciscodevnet
Podcast: devtools.libsyn.com
slideshare.net/aroach

3. DevNet Vision Help developers build solutions and grow their careers.
Learn
Code
Inspire
Monetize

4. §1: Why and What
§2: Show the code

5. §1: Why and What

6. Cross-train our technical field

7. What Did We Do?
Created background “mini-hacks” activity at sales conference
Needed a way for them to submit answers
Why not make them do it via an API?!

8. How we ran it Three challenges per day (Jive site)
Answers were provided at the beginning of the next day
Support via a Cisco Spark room
Submissions were analyzed after the event
Small monetary rewards to top 3 finishers

9. Meetup!

10. Solution evaluation was hardest part
Wrote a CLI
Created manually, but could have used swagger-code- gen
Wrote test cases
Manual validation in the end

11. § 2: Show the code

12. Project Requirements Build an API quickly (~a couple days)
Data Persistence
User and API Authorization
Only an API (No UI for user)
Package in a “cloud native” way

13. Infrastructure Architecture
Scheduler
CI/CD
DBaaS

14. Technologies involved and evaluated
I know MEAN stack (Mongo, Express, Angular, Node)
I wanted to try out building using a REST modeling tool
Swagger-node
Osprey (RAML-based): seemed less feature rich
Containerized to be deployed on ciscoshipped.io
GitHub
Postman
MongoHub (Mongo client)
mLab (Hosted mongo)

15. OpenAPI Spec (fka Swagger)
Open specification for describing REST APIs
A top-down approach where you would use the Swagger Editor to create your Swagger definition and then use the integrated Swagger Codegen tools to generate server implementation.
A bottom-up approach where you have an existing REST API for which you want to create a Swagger definition. 

16. Dockerfile FROM node:5.11.1 # Create app directory
RUN mkdir -p /usr/src/app
# Establish where your CMD will execute
WORKDIR /usr/src/app
# Bundle app source into the container
COPY ./node_modules /usr/src/app/node_modules
COPY ./api /usr/src/app/api
COPY ./config /usr/src/app/config
COPY ./app.js /usr/src/app/
# Expose the port for the app
EXPOSE 10010
# Execute "node app.js"
CMD ["node", "app.js"]

17. Docker run --link
Legacy container links within the Docker default bridge.
This is a bridge network named bridge created automatically when you install Docker.
Superceeded by Docker Networks feature

18. Makefile
run:
docker run --rm --name $(NAME)-$(INSTANCE) $(LINK) $(PORTS) $(VOLUMES) $(ENV) $(NS)/$(REPO):$(VERSION)
$ make run
$ docker run --rm --name devnet-challenge-api-default --link mymongo:mongo -p 8080: env-file=.env ciscodevnet/devnet-challenge-api:v1

19. Node Libraries Used Swagger-node Express: Node HTTP server
Bcrypt: Password hashing in DB
Mongoose: Node mongo library
Jsonwebtoken: JWT library
Password-generator: generate random passwords
Marked: Convert Markdown to HTML for docs

20. Swagger-node Runtime environment that includes Swagger Editor
swagger project <command>
Start
Edit
node app.js for proper deployments

21. Swagger Editor

22. My swagger-node workflow
IDEA
Swagger Edit
Add/Edit Model & Controller
Swagger test
Make build & run
Verify
git add / commit / push
shipped deploy

23. Anatomy of project Correspond to swagger properties: // swagger.yaml
├── Dockerfile
├── README.md
├── api
│   ├── controllers
│   │   ├── README.md
│   │   ├── authenticate.controller.js
│   │   ├── challenge.controller.js
│   │   ├── challenge.model.js
│   │   ├── health.controller.js
│   │   ├── user.controller.js
│   │   └── user.model.js
│   ├── helpers
│   │   └── mongoose
│   │   ├── common-fields.js
│   │   └── search.js
│   ├── mocks
│   │   └── README.md
│   └── swagger
│   └── swagger.yaml
Correspond to swagger properties:
// swagger.yaml
x-swagger-router-controller
operationId

24. # swagger.yaml
paths:  /users:
    x-swagger-router-controller: user.controller
    post:
      description: Create a user account
      operationId: createUser
      produces:
        - application/json
      parameters:
        - name: user
          in: body
          description: Your requested username
          required: true
          schema:
            $ref: "#/definitions/NewUser"
      responses:
        "201":
          description: "created user"
            $ref: "#/definitions/NewUserResponse"
        "400":
          description: Bad request (duplicate user)
            $ref: "#/definitions/ErrorResponse"
        default:
          description: "unexpected error"
// user.controller.js
exports.createUser = function(req, res) { }

25. var express = require('express'); app.use(express.static('static'));
├── app.js
├── config
│   ├── README.md
│   ├── default.yaml
│   └── seeds
│   └── basic.js
├── env_make
├── Makefile
├── package.json
├── static
│   ├── css
│   │   └── main.css
│   └── howto.md
└── test
└── api
├── controllers
│   ├── authenticate.js
│   └── health.js
└── helpers
└── README.md
// app.js
var express = require('express');
app.use(express.static('static'));

27. Takeaways Swagger-node provides fast REST API creation
Prototyping, mocking
Spec-first development was an adjustment
Container-based workflows made deployment super simple

28. Helpful Links
scavenger-hunt
membership-via-google-forms
with-a-makefile/

29. Thank you!