Skip to content

Server-side request validator for Node.js based on OpenAPI

License

Notifications You must be signed in to change notification settings

apideck-libraries/reva

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

43 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

npm (scoped) npm GitHub Workflow Status

@apideck/reva 🕵

Server-side request validator for Node.js based on OpenAPI

  • Supports all OpenAPI parameters
  • Based on AJV
  • Readable and helpful errors (by @apideck/better-ajv-errors)
  • High quality TypeScript definitions included
  • Minimal footprint: 42 kB including AJV (gzip + minified)

Install

$ yarn add @apideck/reva

or

$ npm i @apideck/reva

Usage

Create a Reva instance and call the validate method with your OpenAPI operation and your request data.

import { Reva } from '@apideck/reva';

const reva = new Reva();

const result = reva.validate({
  operation, // OpenAPI operation
  request: {
    headers: { 'X-My-Header': 'value', Cookie: 'Key=Value' },
    pathParameters: { id: 'ed55e7a3' },
    queryParameters: { order_by: 'created' },
    body: { name: 'Jane Doe' },
  },
});

if (result.ok) {
  // Valid request!
} else {
  // Invalid request, result.errors contains validation errors
  console.log(result.errors);
  // {
  //   "ok": false,
  //   "errors": [
  //     {
  //       "path": "request.query",
  //       "message": "'order_by' property must be equal to one of the allowed values",
  //       "suggestion": "Did you mean 'created_at'?",
  //       "context": { "errorType": "enum", "allowedValues": ["created_at", "updated_at"] }
  //     },
  //     {
  //       "path": "request.header",
  //       "message": "request.header must have required property 'x-required-header'",
  //       "context": { "errorType": "required" }
  //     },
  //     {
  //       "path": "request.body",
  //       "message": "'name' property is not expected to be here",
  //       "context": { "errorType": "additionalProperties" }
  //     }
  //   ]
  // }

}

API

Reva

Reva is the main Request validation class. You can optionally pass options to the constructor.

new Reva(options?: RevaOptions)

Parameters

  • options: RevaOptions
    • allowAdditionalParameters?: true | OpenApiParameterType[] Allow additional parameters to be passed that are not defined in the OpenAPI operation. Use true to allow all parameter types to have additional parameters. Default value: ['header', 'cookie']
    • partialBody?: boolean Ignore required properties on the requestBody. This option is useful for update endpoints where a subset of required properties is allowed. Default value: false
    • groupedParameters?: OpenApiParameterType[] Validate multiple OpenAPI parameter types as one schema. This is useful for APIs where parameters (query,path, etc) are combined into a single parameters object. Default value: []
    • paramAjvOptions?: AjvOptions Custom AJV options for request param validation.
    • bodyAjvOptions?: AjvOptions Custom AJV options for request body validation.

reva.validate(options: RevaValidateOptions)

Validate requests based on OpenAPI. Parameter validation uses type coercion, request body validation does not. When a Content-Type header is passed, it has to match a Content-Type defined in the OpenAPI operation. Default Content-Type is application/json.

Parameters

  • options: RevaValidateOptions
    • operation: OpenApiOperation Your OpenAPI operation object to validate against
    • request: RevaRequest The request data to validate. All properties are optional
      • queryParameters?: Record<string, unknown> Query parameters to validate
      • headers?: Record<string, unknown> Headers to validate
      • pathParameters?: Record<string, unknown> Path parameters to validate
      • body?: unknown Request body to validate
    • options?: RevaOptions Override options set in the Reva constructor

Return Value

  • Result<ValidationError>
    • ok: boolean Indicates if the request is valid or not
    • errors?: ValidationError[] Array of formatted errors. Only populated when Result.ok is false
      • message: string Formatted error message
      • suggestion?: string Optional suggestion based on provided data and schema
      • path: string Object path where the error occurred (example: .foo.bar.0.quz)
      • context: { errorType: DefinedError['keyword']; [additionalContext: string]: unknown } errorType is error.keyword proxied from ajv. errorType can be used as a key for i18n if needed. There might be additional properties on context, based on the type of error.