Rule x for swagger explained

nomossoftware nomos-software.com

RuleX for Swagger Explained

Technical explanation of RuleX Code Generation

RuleX = Product from Nomos SoftwareSwagger = Framework for APIs

www.nomos-software.comCopyright © Nomoséire Limited 2015 trading as Nomos Software nomossoftware

Swagger describes & visualizes APIs

Swagger UI created from the swagger description, ref https://github.com/swagger-api/swagger-ui

Swagger description for a Product Order API – ref swagger.io


Swagger Description

RuleX for Swagger generates a virtual API based on rules

Swagger-api swagger-ui

https://github.com/swagger-api/swagger-ui

Rules = OCL for validating and queryinghttp://clients.nomos-software.com/RuleXOCLUserGuide.html

Action rules for simulated responseshttp://clients.nomos-software.com/RuleXActionsUserGuide.html

Swagger Description + Rules

(including swagger definition section) RuleX

Virtual API = WAR file

Containing endpoints that validate an API request & simulate responses


RuleX generates JAX-RS endpoints for swagger paths

The paths / operationsPost ProductOrderGet ProductOrders

Delete ProductOrder based on idGet ProductOrder based on idPut (update) based on id

Swagger description


RuleX generates java classes for swagger definitions

The parameters and responsesThe definitions section defines the data model for the operation parameters and responses

Based on JSON schema

Swagger description


RuleX generates java classes for the validation rules

Validation rules expressed in OCL

self.requestedStartDate.before(self.requestedCompletionDate)

"The requested start date must be before the requested completion date"

"The Port Id for voice resources (UNIV) must be 0 or 1"

self.id = 'UNIV' implies self.product.productCharacteristic->forAll (d |

d.name = 'Port Id' implies d.value.toInteger() >= 0 and d.value.toInteger() <=1)

self.orderItem->size() <= 10 "A maximum of 10 items can be ordered"


RuleX generates java classes for the action rules

Action rules that simulate API responses

// Create and return a product order// based on the request

ProductOrder newPO : ProductOrder.create();newPO.id : id;newPO.externalId : 'An external Id';newPO.priority : cpo.priority; newPO.description : cpo.description;newPO.category : cpo.category; newPO.requestedStartDate : cpo.requestedStartDate;newPO.requestedCompletionDate : cpo.requestedCompletionDate;

foreach o in (cpo.orderItem)ProductOrderItem newO : ProductOrderItem.copy(o);newPO.orderItem.add(newO);

endeach;

return newPO;


RuleX JAX-RS Endpoint Logic Explained

RuleX Generated Jax-RS Endpoint Logic

Validate request parametersvalidate json syntaxvalidate against the swagger definitions validate against the rules

If not okayreturn error diagnostics

Elserun action rule to simulate response


Example Error Diagnostics from RuleX Virtual API

{"Validation Report": "04/02/15 15:39",[

{"Error": "The requested start date must be before the requested completion date","Line 6": "requestedStartDate","Line 7": “requestedCompletionDate"

}]

}

JSON syntax errors

Diagnostic information is returned for:

Swagger definition validation errors

OCL rule validation errors


Example RuleX Simulated Response from Virtual API

{"id": "A server side generated id","externalId": "NomosId","priority": "0","requestedStartDate": "2009-02-26T20:00:00","requestedCompletionDate": "2009-02-27T20:00:00","orderItem": [

{"id": "AVCD","action": "action","product": {

"href": "AVCD href","relatedParty": null,"productCharacteristic": [

{"name": "AVC Type","value": "1:1"

},….

Simulated responses are returned for valid requests


Download from www.nomos-software.com/developers

Ask us for help

Send us your comments

Email support(at)nomos-software.com

Evaluate RuleX Eclipse Plugin for Swagger

Technology

Rule x for swagger explained