README.md

@funboxteam/api-validator

api-validator is a frontend tool to validate server response against API Blueprint documentation.

По-русски

Rationale

Having human-readable documentation is a good way to specify a contract between client and server parts of an application. However, due to the complexity of modern web apps, a server response can contain dozens of fields and nested fields, and it is easy for backend to not comply with the documentation because of a bug or any other reason.

To minimize the number of errors on the frontend side associated with incorrect backend responses, we developed a tool for automatic validation. It extracts JSON schema from the API Blueprint documentation and allows to automatically check correspondence between the backend response and the documentation for this request.

Installation

npm install --save @funboxteam/api-validator

Usage

Extracting of JSON schemas in frontend projects

Add the next doc field inpackage.json:

"doc": {
"repo": "git@github.com:your-username/your-apib-repository.git",
"branch": "master",
"file": "doc.apib"
}

where:

• repo — repository URL (required);
• branch — target branch name (required);
• file — file name in the repository (optional, default is doc.apib).

This package exposes a binary called update-schemas, therefore you can generate schemas or update existing schemas by running update-schemas in a terminal.

This command will add required files in the project:

• src/api-schemas/schemas.json — contains schemas;
• src/api-schemas/doc-version.txt — contains the commit ID used to generate schemas.

Server response validation

Import generated schemas from the project and the validation function from the package:

import{validateResponse}from'@funboxteam/api-validator';importschemasfrom'src/api-schemas/schemas';

Call the validation function with response parameters and generated schemas to get validation result:

constresponseInfo={method: 'GET',url: '/api/auth',data: {status: 'ok'}};constvalidationResult=validateResponse({method: responseInfo.method,url: responseInfo.url,data: responseInfo.data,
schemas,});

Examples

Example of validation in React projects

importaxiosfrom'axios';importsettingsfrom'app/app.settings';importschemasfrom'api-schemas/schemas';import{validateResponse,validationStatus}from'@funboxteam/api-validator';axios.interceptors.response.use(response=>{constresult=validateResponse({method: response.config.method,url: response.config.url,data: response.data,
schemas,basePath: settings.apiBase,});switch(result.status){casevalidationStatus.invalid: {console.log(`Validation error in ${response.config.method}${response.config.url}`);console.log(result);returnPromise.reject();}casevalidationStatus.schemaNotFound: {console.log(`No schema for ${response.config.method}${response.config.url}.`);returnPromise.reject();}}returnresponse;});

Example of validation in Angular projects

importschemasfrom'api-schemas/schemas';import{validateResponse,validationStatus}from'@funboxteam/api-validator';angular.module('app').config(['restfulProvider','settings',(restfulProvider,settings)=>{restfulProvider.addInterceptor({postProcessResponse: (respWrapper)=>{constresponse=respWrapper.response;constresult=validateResponse({method: response.config.method,url: response.config.url,data: response.data,
schemas,basePath: settings.apiBase,});switch(result.status){casevalidationStatus.invalid: {console.log(`Validation error in ${response.config.method}${response.config.url}`);console.log(result);respWrapper.isSuccessful=false;break;}casevalidationStatus.schemaNotFound: {console.log(`No schema for ${response.config.method}${response.config.url}.`);respWrapper.isSuccessful=false;break;}}},});}]);

Example of validation for WebSocket connections

This example is based on JavaScript client of the Phoenix framework:

importschemasfrom'api-schemas/schemas';import{validateWebsocketResponse,validationStatus}from'@funboxteam/api-validator';const{ Socket }=require('phoenix');constsocket=newSocket('/adapter/v1',{});socket.connect();constchannel=socket.channel('channel-topic');channel.onMessage=(message,payload)=>{// https://hexdocs.pm/phoenix/js/#channelonmessageconstresult=validateWebsocketResponse({messageTitle: message,channel: channel.topic,data: payload,
schemas,});switch(result.status){casevalidationStatus.valid:
console.log(`Schema of the message ${message} in the channel ${channel.topic} is valid`);returnpayload;casevalidationStatus.invalid:
console.warn(`Error during validation of the message ${message} in the channel ${channel.topic}`);console.log(result);returnpayload;casevalidationStatus.schemaNotFound:
console.warn(`Schema of the message ${message} in the channel ${channel.topic} not found`);returnpayload;default:
returnpayload;}};