Swagger for your REST API        Tony Tam
REST as the “new” APIRevisiting the JAR•  Expose & share low-level functionality•  Reduced plumbing, focus on business log...
REST as the “new” API•  Complex building blocks for your application    •  Authentication    •  Photo storage    •  Analyt...
Integrating   3 rd   Party APIs           How about         Documentation?"
Integrating    3 rd   Party APIs                               IDE    Javadocs?"               support?"             How a...
Integrating   3 rd   Party APIs
Integrating   3 rd   Party APIs
Integrating   3 rd   Party APIs
Integrating   3 rd   Party APIs
So… How do we describe APIs?      Javadocs?"    WADL"                   WADL2?"     Developer       WSDL?"      Docs?"
The Swagger SpecificationIt’s a spec!•  JSON•  Coupled of decoupled•  Machine-readable•  Language agnostic•  Distributed b...
Benefits of an InterfaceIt’s done in JSON                                 Existing•  Generate manually                    ...
Benefits of an InterfaceMachine-readable     Your boss                    can try your                        API
Benefits of an InterfaceDistributed design                API Declaration"            /pet"                  Server 1"    ...
How does this help you?                     Server"                       Developer"  Client-Side  Developer"
How does this help you?                     Server"                       Developer"  OMG I can   code w/o  waiting for   ...
How about your clients?REST or SDK?•  Please! Strive to   remove your logic   from clients         /api/pet.json/1?delete ...
How about your clients?REST or SDK?•  Please! Strive to   remove your logic   from clients         /api/pet.json/1?delete ...
How about your clients?Swagger can help (if you like)•  Machine-readable => code generator•  Uses non-ghetto {{mustache}} ...
How about your API service?Swagger can again help (if you like)•  Code-generator, not “client generator”•  Build your serv...
Interfaces are nice•    Developers know what they’re building•    Clients know what they’re getting•    Machines and human...
Swagger is FOSS
Where to go nextMore info + demohttp://developers.helloreverb.com/swagger/Swagger specificationhttps://github.com/wordnik/...
Upcoming SlideShare
Loading in...5
×

Swagger for-your-api

12,065

Published on

Slides from http://apistrategyconference.com/ on swagger in your REST api

Published in: Technology

Transcript of "Swagger for-your-api"

  1. 1. Swagger for your REST API Tony Tam
  2. 2. REST as the “new” APIRevisiting the JAR•  Expose & share low-level functionality•  Reduced plumbing, focus on business logic•  Helped us build big, monolithic apps •  Dependency hell
  3. 3. REST as the “new” API•  Complex building blocks for your application •  Authentication •  Photo storage •  Analytics•  Language & deployment independent•  Vertical scaling addressed by smaller, decoupled services
  4. 4. Integrating 3 rd Party APIs How about Documentation?"
  5. 5. Integrating 3 rd Party APIs IDE Javadocs?" support?" How about Documentation?" Stack Overflow?" JSDoc?"
  6. 6. Integrating 3 rd Party APIs
  7. 7. Integrating 3 rd Party APIs
  8. 8. Integrating 3 rd Party APIs
  9. 9. Integrating 3 rd Party APIs
  10. 10. So… How do we describe APIs? Javadocs?" WADL" WADL2?" Developer WSDL?" Docs?"
  11. 11. The Swagger SpecificationIt’s a spec!•  JSON•  Coupled of decoupled•  Machine-readable•  Language agnostic•  Distributed by Design An Interface for your API
  12. 12. Benefits of an InterfaceIt’s done in JSON Existing•  Generate manually API? •  Deploy statically•  Generate automatically by server integration •  9 languages, 16+ frameworks
  13. 13. Benefits of an InterfaceMachine-readable Your boss can try your API
  14. 14. Benefits of an InterfaceDistributed design API Declaration" /pet" Server 1" /store" Server 2"Resource" Listing" /user" Swagger Spec Server" Server 3"
  15. 15. How does this help you? Server" Developer" Client-Side Developer"
  16. 16. How does this help you? Server" Developer" OMG I can code w/o waiting for The client back end!" developer isn’t bugging me!" Client-Side Developer"
  17. 17. How about your clients?REST or SDK?•  Please! Strive to remove your logic from clients /api/pet.json/1?delete (GET) /api/pet.json/1 (DELETE) /api/pet.json/1 (POST empty)
  18. 18. How about your clients?REST or SDK?•  Please! Strive to remove your logic from clients /api/pet.json/1?delete (GET) /api/pet.json/1 (DELETE) /api/pet.json/1 (POST empty) These all (This is your “work” job, not your clients’)
  19. 19. How about your clients?Swagger can help (if you like)•  Machine-readable => code generator•  Uses non-ghetto {{mustache}} templates•  Make client libraries “your way”
  20. 20. How about your API service?Swagger can again help (if you like)•  Code-generator, not “client generator”•  Build your server from the interface
  21. 21. Interfaces are nice•  Developers know what they’re building•  Clients know what they’re getting•  Machines and humans can interpret them•  Teams can develop in parallel
  22. 22. Swagger is FOSS
  23. 23. Where to go nextMore info + demohttp://developers.helloreverb.com/swagger/Swagger specificationhttps://github.com/wordnik/swagger-core/wiki @fehguy"JVM server implementationhttps://github.com/wordnik/swagger-coreNode.js server implementationhttps://github.com/wordnik/swagger-coreswagger-uihttps://github.com/wordnik/swagger-uiswagger-codegenhttps://github.com/wordnik/swagger-codegen
  1. A particular slide catching your eye?

    Clipping is a handy way to collect important slides you want to go back to later.

×