@funboxteam/api-validator
v5.0.3
Published
A tool to validate server response against API Blueprint documentation
Downloads
519
Keywords
Readme
@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": "[email protected]: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 isdoc.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';
import schemas from 'src/api-schemas/schemas';
Call the validation function with response parameters and generated schemas to get validation result:
const responseInfo = {
method: 'GET',
url: '/api/auth',
data: { status: 'ok' }
};
const validationResult = validateResponse({
method: responseInfo.method,
url: responseInfo.url,
data: responseInfo.data,
schemas,
});
Examples
Example of validation in React projects
import axios from 'axios';
import settings from 'app/app.settings';
import schemas from 'api-schemas/schemas';
import { validateResponse, validationStatus } from '@funboxteam/api-validator';
axios.interceptors.response.use(response => {
const result = validateResponse({
method: response.config.method,
url: response.config.url,
data: response.data,
schemas,
basePath: settings.apiBase,
});
switch (result.status) {
case validationStatus.invalid: {
console.log(`Validation error in ${response.config.method} ${response.config.url}`);
console.log(result);
return Promise.reject();
}
case validationStatus.schemaNotFound: {
console.log(`No schema for ${response.config.method} ${response.config.url}.`);
return Promise.reject();
}
}
return response;
});
Example of validation in Angular projects
import schemas from 'api-schemas/schemas';
import { validateResponse, validationStatus } from '@funboxteam/api-validator';
angular.module('app').config(['restfulProvider', 'settings', (restfulProvider, settings) => {
restfulProvider.addInterceptor({
postProcessResponse: (respWrapper) => {
const response = respWrapper.response;
const result = validateResponse({
method: response.config.method,
url: response.config.url,
data: response.data,
schemas,
basePath: settings.apiBase,
});
switch (result.status) {
case validationStatus.invalid: {
console.log(`Validation error in ${response.config.method} ${response.config.url}`);
console.log(result);
respWrapper.isSuccessful = false;
break;
}
case validationStatus.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:
import schemas from 'api-schemas/schemas';
import { validateWebsocketResponse, validationStatus } from '@funboxteam/api-validator';
const { Socket } = require('phoenix');
const socket = new Socket('/adapter/v1', {});
socket.connect();
const channel = socket.channel('channel-topic');
channel.onMessage = (message, payload) => { // https://hexdocs.pm/phoenix/js/#channelonmessage
const result = validateWebsocketResponse({
messageTitle: message,
channel: channel.topic,
data: payload,
schemas,
});
switch (result.status) {
case validationStatus.valid:
console.log(`Schema of the message ${message} in the channel ${channel.topic} is valid`);
return payload;
case validationStatus.invalid:
console.warn(`Error during validation of the message ${message} in the channel ${channel.topic}`);
console.log(result);
return payload;
case validationStatus.schemaNotFound:
console.warn(`Schema of the message ${message} in the channel ${channel.topic} not found`);
return payload;
default:
return payload;
}
};