Extending Swagger for virtual, diagnostic-rich APIs

Transcript

1. nomossoftware nomos-software.com Extending Swagger for virtual, diagnostic-rich APIs API Strategy/APIDays Berlin, April 2015 David Garry, CTO david.garry(at)nomos-software.com
2. www.nomos-software.com Copyright © Nomoséire Limited 2015 trading as Nomos Software nomossoftware • API lifecycle challenge – design and support • Introduction to Swagger • Using Swagger for server generation (virtual APIs) • Enhancing Swagger-based server generation (validation & simulation) • Benefits – API design and support • Suggestions on extending Swagger specification for rules • Summary Contents
3. www.nomos-software.com Copyright © Nomoséire Limited 2015 trading as Nomos Software nomossoftware Traditional software APIs / Digital Services Support – need to support high volume of customers with whom you have little / no contact Build and deliver – lower cost, lower pricing, higher competition, more churn, less/no customization for individual customers Design – services must be exactly right API Lifecycle Challenge New areas of focus in software lifecycle
4. www.nomos-software.com Copyright © Nomoséire Limited 2015 trading as Nomos Software nomossoftware Helps Design Helps Support Description language for APIs & with developer tools Rapid prototyping Interactive documentation API Provider API Consumer API Lifecycle Challenge Swagger – helps meet these challenges
5. www.nomos-software.com Copyright © Nomoséire Limited 2015 trading as Nomos Software nomossoftware What is Swagger? Swagger Specification Swagger for API https://github.com/swagger-api/swagger-spec Uses JSON schema to define API parameters and responses Swagger Tools Swagger UI = interactive documentation SDK Generator Server Side Code Generator Code Annotation to Swagger Generator For language-agnostic descriptions of REST APIs Developer-centric tools for working with swagger Swagger Editor
6. www.nomos-software.com Copyright © Nomoséire Limited 2015 trading as Nomos Software nomossoftware Example Swagger Description The paths / operations POST customer GET customer PUT (update) customer based on id GET customer based on id DELETE customer based on id POST paymentMean etc The data model for API request parameters and responses Based on JSON schema For a ‘telecoms’ customer management API based on TMForum defined API, reference https://www.amkbcloud.com/blog/ for details
7. www.nomos-software.com Copyright © Nomoséire Limited 2015 trading as Nomos Software nomossoftware Swagger UI Swagger Tools
8. www.nomos-software.com Copyright © Nomoséire Limited 2015 trading as Nomos Software nomossoftware Swagger Editor Swagger Tools
9. www.nomos-software.com Copyright © Nomoséire Limited 2015 trading as Nomos Software nomossoftware Virtual API Rapid Prototyping of Virtual API using Swagger Server Generators Can generate server for: - NodeJS - JAX-RS - Scalatra - Spring-MVC Swagger Editor However: - No JSON syntax validation - No JSON schema validation - No business rules validation - No definition of what the API should return when it receives a valid request Swagger Description Server Side Code Generators
10. www.nomos-software.com Copyright © Nomoséire Limited 2015 trading as Nomos Software nomossoftware Swagger Description Rules Functioning API with - rich diagnostics and - simulated responses Virtual API Rapid Prototyping of Virtual APIs - with server-side logic for validation and simulation RuleX code generator from Nomos generates JAX-RS server with: - JSON syntax validation - JSON schema validation - Validation against rules - Simulated responses
11. www.nomos-software.com Copyright © Nomoséire Limited 2015 trading as Nomos Software nomossoftware Server Generation from Swagger Basic What is Possible Possible from Swagger + Rules See Swagger editor JAX-RS Codegen See RuleX Codegen See RuleX Codegen Server with stub endpoints Dummy responses JSON syntax validation Validation against swagger definitions (json schema) Validiation based on rules Simulated responses based on rules Sample (pass and fail) API requests based on rules (not included in Server)
12. www.nomos-software.com Copyright © Nomoséire Limited 2015 trading as Nomos Software nomossoftware Rapid prototyping process – very fast iteration Immediate regeneration Virtual API Swagger UI Swagger Description Rules EDIT EDIT Faster than iteratively updating server-side code as ideas on the design and behaviour of the API develop
13. www.nomos-software.com Copyright © Nomoséire Limited 2015 trading as Nomos Software nomossoftware Rapid Prototyping Benefits Helps Design Iterative, agile approach to designing the API API Consumer plays with virtual API – Designer learns early about user expectations Swagger UI Send API request API User : Designer or Consumer Receive responses Virtual API Try out a demo of a generated virtual API: http://nomos-software.com/blog/swagger-ui-example
14. www.nomos-software.com Copyright © Nomoséire Limited 2015 trading as Nomos Software nomossoftware “Support” Benefits Rich diagnostics Improved developer / API Consumer experience Self-service support : lower cost, and more effective for high volume customers
15. www.nomos-software.com Copyright © Nomoséire Limited 2015 trading as Nomos Software nomossoftware What we do now: parallel documents in .json & .json5 format Extending Swagger Spec with Rules Swagger Description Rules .json5 format : for multi-lines Rules for - validation - simulated responses - test data generation NB: Rules are written against the definitions in the swagger .json format defining API behaviour more completely
16. www.nomos-software.com Copyright © Nomoséire Limited 2015 trading as Nomos Software nomossoftware (a) Embed rules within swagger file Extending Swagger Spec - Alternatives Could use vendor extensions Similar to how schematron embeds rules in xs:appInfo elements of XSD Need multiline format (YAML) Swagger file likely to become unwieldy
17. www.nomos-software.com Copyright © Nomoséire Limited 2015 trading as Nomos Software nomossoftware Extending Swagger Spec - Alternatives (b) Define parallel ‘rules’ file, & import to swagger .json5 format currently used by Nomos Update swagger specification with format for rules metadata & expressions – expressions could be language agnostic
18. www.nomos-software.com Copyright © Nomoséire Limited 2015 trading as Nomos Software nomossoftware Extending Swagger Tools for Rules Swagger UI Swagger Editor View rules in swagger UI API Consumer can browse details of API behaviour Edit rules (metadata + expressions) in swagger editor Could include Ace editor for rules expressions – see RuleX example Enables code generation of server-side logic : potential also for client side validations via SDK generation
19. www.nomos-software.com Copyright © Nomoséire Limited 2015 trading as Nomos Software nomossoftware • Use swagger plus rules to define API behaviour in more depth • Can automatically generate APIs with simulated behaviour and strong validation for good diagnostics • Good for API Design, good for API support Summary Traditional software APIs / Digital Services Support Build and deliver Design
20. www.nomos-software.com Copyright © Nomoséire Limited 2015 trading as Nomos Software nomossoftware Find out more www.nomos-software.com/developers Email david.garry(at)nomos-software.com