API Strat & APIdays Berlin 2015 : Extending swagger for enhanced code generation

nomossoftware nomos-software.com

Extending Swagger for virtual, diagnostic-rich APIs

API Strategy/APIDays Berlin, April 2015

David Garry, CTOdavid.garry(at)nomos-software.com

www.nomos-software.comCopyright © 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


Traditional softwareAPIs / 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


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


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


Example Swagger Description

The paths / operationsPOST customerGET customerPUT (update) customer based on idGET customer based on idDELETE customer based on id

POST paymentMeanetc

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


Swagger UI

Swagger Tools


Swagger Editor

Swagger Tools


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


Swagger Description

RulesFunctioning 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 Nomosgenerates JAX-RS server with:

- JSON syntax validation- JSON schema validation- Validation against rules- Simulated responses


Server Generation from Swagger

Basic What isPossible

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)


Rapid prototyping process – very fast iteration

Immediate regeneration

Virtual API

Swagger UISwagger Description

Rules

EDIT

EDIT

Faster than iteratively updating server-side code as ideas on the design and behaviour of the API develop


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


“Support” Benefits

Rich diagnostics

Improved developer / API Consumer experience

Self-service support : lower cost, and more effective for high volume customers


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


(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


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


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


• 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 softwareAPIs / Digital Services

Support

Build and deliver

Design


Find out more

www.nomos-software.com/developers

Email david.garry(at)nomos-software.com

API Strat & APIdays Berlin 2015 : Extending swagger for enhanced code generation

Software

Transcript of API Strat & APIdays Berlin 2015 : Extending swagger for enhanced code generation