Recommended
Recommended
More Related Content
What's hot
What's hot (20)
Viewers also liked
Viewers also liked (20)
Similar to Crystal clear service interfaces w/ Swagger/OpenAPI
Similar to Crystal clear service interfaces w/ Swagger/OpenAPI (20)
Recently uploaded
Recently uploaded (20)
Crystal clear service interfaces w/ Swagger/OpenAPI
- 1. Crystal clear service interfaces with Swagger/OpenAPI @scott_triglia Swagger
- 2. Yelp’s Mission: Connecting people with great local businesses.
- 4. Let’s talk some hard truths about APIs
- 5. Writing a good API is hard
- 6. The average API is functional, but not excellent
- 7. CC BY 2.0 by alebonvini
- 8. The average API is not well-documented
- 9. CC BY 2.0 by suigetsu
- 10. CC BY 2.0 by gpoo
- 11. The average API is ambiguous or under specified
- 12. The average API is written in a rush
- 13. The average API does not get a dedicated team
- 16. The average API is average!
- 17. My job: make a widget Their job: make a great API
- 18. Backend engineers make a lot of APIs
- 19. We need better tools
- 20. We need more leverage
- 21. CC BY-NC-SA 2.0 by ilri
- 22. CC BY-SA 3.0 by Michael Gäbler
- 23. We need our APIs to document themselves
- 24. We need our APIs to validate themselves
- 25. We need our APIs to manage themselves
- 26. We need something like
- 27. Our goals today:
- 28. Explain
- 29. Test Drive
- 32. Explain
- 33. A Swagger/OpenAPI spec describes a REST API
- 35. A Swagger spec is a concrete description of a REST API
- 36. And I mean *very* concrete
- 37. * Request Methods + URIs * Query, Path, Body params * Headers * Responses
- 46. Test Drive
- 49. Swagger-Editor
- 54. Swagger-UI
- 59. Integration
- 60. Server side - striglia/pyramid_swagger # In your Pyramid webapp.py conf[‘pyramid_swagger.schema_directory'] = ‘api/‘ config.include(‘pyramid_swagger')
- 61. Features
- 70. And note that we can do this on client or server!
- 74. Client side - Yelp/bravado from bravado.client import SwaggerClient client = SwaggerClient.from_url( “http://www.striglia.io/swagger.json” ) pet = client.users.get(active_only=True).result()
- 78. API-first design keeps you sane
- 79. Documenting a service’s API can be challenging
- 80. Doing it as a design exercise is pretty easy
- 81. Doing it retroactively can be horrific
- 82. For your sanity, try EXTREMELY hard to enforce the creation of these specs up front, not after the fact.
- 83. How do we distribute Swagger specs?
- 84. Easiest solution — local to service, served over HTTP for free by tooling
- 85. Problems: HTTP is unreliable and slow
- 86. Problems: What if there are N versions of the API in the wild at once?
- 87. Client Service Version A #users Call #1: Ask for spec Call #2: Get #users reference Service Version A #users 1 2
- 88. Client Service Version A #users Call #1: Ask for spec Call #2: Get #users ref Call #3: Get #orders ref Service Version B #users 1 2 #orders 3
- 89. Hacky approach — make your specs one huge document
- 90. Yelp’s direction — auto-packaged client libraries built on spec changes
- 95. Upside: no perf hit from JIT spec fetching over the network
- 96. Upside: clients explicitly expect a particular interface
- 97. Upside: a convenient place to inject other smart behavior (e.g. OpenTracing headers)
- 98. in summary
- 99. Good APIs are complicated!
- 100. Swagger lets you declaratively design APIs
- 101. Validation + Documentation come for free
- 102. And it’s all language agnostic
- 103. Raise the bar on the quality of your APIs
- 104. * Spec -> www.swagger.io * Help -> www.swagger.io/irc/ * Client: Yelp/bravado * Server: striglia/pyramid_swagger