Trusting an API Spec
•Download as PPTX, PDF•
0 likes•264 views
How Springworks improved their API workflow by using Swagger API specs to generate documentation and web server routing. Slides from a lightning talk at Nordic.js 2016.
Recommended
Recommended
More Related Content
What's hot
What's hot (20)
Similar to Trusting an API Spec
Similar to Trusting an API Spec (20)
Recently uploaded
Recently uploaded (20)
Trusting an API Spec
- 1. 2016-09-07 connected-car.js Improving the API workflow with Swagger and Node.js
- 2. What Springworks are doing SPRINGWORKS – CONNECTING CARS Create end user value by connecting their car to local services. …
- 3. How to trust an API spec
- 4. Working with APIs • Connected cars Lots of valuable data • REST API:s for data (internal and external) • 9 different REST API:s within different domains SPRINGWORKS – CONNECTING CARS
- 5. Where we were • API documentation typed to README.md • Docs not always correct Confusion, Waste of time • No protocol tests Broken implementations SPRINGWORKS – CONNECTING CARS
- 6. Possible Paths SPRINGWORKS – CONNECTING CARS Annotate Code Generate Docs Separate API spec Generate docs (and code?)
- 7. api.jsapi.js Generate docs & code based on API spec api.js + fixtures SPRINGWORKS – CONNECTING CARS API.md swagger-md Webserver hapi hapi-swaggerize api.js Static API Webserver hapi hapi-swaggerize @springworks/static-api-server fixture-loader api.jso n GET /v1/vehicles/{vin} 200 OK POST /v1/users 201 Created ... GET /v1/vehicles/{vin} 200 OK POST /v1/users 201 Created ... ## GET /v1/vehicles/{vin} … ## POST /v1/users …
- 8. Where we are today • All API changes made to the spec and only to the spec • Documentation and API spec always correct • Protocol tests from all apps and internal services SPRINGWORKS – CONNECTING CARS
- 9. Join Us to Change The World™ • We’re building fun and challenging products • We can have a true impact on the world (really) • We’re looking for more exceptional talent SPRINGWORKS – CONNECTING CARS
Editor's Notes
- Hello World! Great to be here. I hope you’re all enjoying the conference so far. I’m Kristofer Sommestad. CTO @ Springworks I will talk about how we improved our API workflow with Swagger and Node.
- So, who are Springworks? 30++ employees, mostly 10+ years experience Building eco systems for connected cars Create end user value by connecting their car to local services, e.g. your insurance company, workshop, parking, road side assistance etc First official product launch on our platform this year; Telia Sense. More to come on other global markets.
- I’ll talk about how we ensure that our API:s do what they claim to do.
- API:s are central in our tech stack. Lots of data generated We and others need to access the data to provide end users with features Today, we have 9 different API:s (in all sizes)
- Our previous set up was to have API document in a manually-updated document within the Github repo. Problems: API docs not always correct (too easy to forget to change it) Lack of protocol tests (no spec to test against)
- We saw 2 possible paths ahead. Start annotating code with documentation and generate API docs based on that. Big migration effort, still risk of mistakes. Specify API in machine-readable file and generate needed code + docs. Less migration effort, less risk of mistakes. We went with the 2nd option.
- Generating code & docs based on API spec was the best choice for us. Write the API spec on Swagger format (as .js files to add more sugar than .json) Generate API docs as Markdown using a home-made library (swagger-md) Read API spec in web server and let swaggerize-hapi configure routing in Hapi Generate static API server, which can be used stand-alone, responding with static fixtures (home-made modules)
- Today, we’re rid of the problems with incorrect API documentation and we can easily run protocol tests against our servers. A bonus is that the Swagger spec makes it easier to share and collaborate around the API with other stakeholders.
- We need to be more people to continue doing great things. We’re building fun and challenging products We can actually have an impact on the world, i.e. by helping people find parking spots and reducing traffic in cities We need to be more great people Come by and have a chat in the next room. Or just try our car race track.
- Thanks, enjoy your conference!