npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@funboxteam/api-validator

v5.0.3

Published

A tool to validate server response against API Blueprint documentation

Downloads

519

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 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';
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;
  }
};

Sponsored by FunBox