Skip to content

Latest commit

 

History

History
154 lines (118 loc) · 8.48 KB

README.md

File metadata and controls

154 lines (118 loc) · 8.48 KB
Raw

lua-oasvalidator: REST Request Validator

Language Lua Github releases Mac build Linux build License API Docs

lua-oasvalidator is a Lua binding for the cpp-oasvalidator library, designed for the validation of HTTP requests against OpenAPI 3.x specifications. By integrating this module with your Lua-based REST servers or API gateways, you can ensure that only compliant requests interact with your backend services.

With support for OpenAPI 3.x, this module streamlines the process of validating various components of an HTTP request, from methods and routes to detailed parameters and JSON body.

🌟 Key Features

  • Lua Integration: Seamless integration with Lua, allowing you to use the capabilities of cpp-oasvalidator within API gateways like Kong/NGINX.
  • Efficient, Sequential Validation: Validates requests in a logical order, starting from the HTTP method down to the header parameters. This means if you validate a later stage, preceding steps are validated as well.
  • In-Depth Error Reports: Returns an insightful error enumeration coupled with an extensive error message in JSON format to pinpoint inaccuracies.
  • Optimized Performance: Utilizes lazy deserialization, only processing content when all prior checks pass.
  • Broad Parameter Support: Deserializes parameters across a spectrum of styles and data types, ensuring a wide range of OpenAPI configurations are supported.

📜 Validation Sequence

lua-oasvalidator validates HTTP requests in the following order:

  1. HTTP Method Validation: Ensures that the HTTP method (GET, POST, PUT, etc.) aligns with the OpenAPI spec.
  2. Route Validation: Checks if the provided route matches the specification.
  3. Body Validation: Validates the JSON body structure and data against the OpenAPI spec.
  4. Path Parameter Validation: Validates path parameters.
  5. Query Parameter Validation: Ensures query parameters are consistent with the OpenAPI spec.
  6. Header Parameter Validation: Confirms headers are in line with the OpenAPI specification.
  7. Request Validation: Validates the whole HTTP request starting from method, route, body (if provided), path/query params (if specified in specs) and/or headers. To address all variations, four overloaded methods are provided.

For a comprehensive understanding, refer to API Reference.

🛠 Parameter Styles, data types & Deserialization

cpp-oasvalidator can deserialize and parse parameters of all data types serialized in various styles provided by Swagger/OpenAPI. Following tables provide the details.

Path Parameters

Style Explode Primitive String Array of primitives Array of strings Object
simple* false* ✅ ✅ ✅ ✅ ✅
simple true ✅ ✅ ✅ ✅ ✅
label false ✅ ✅ ✅ ✅ ✅
label true ✅ ✅ ✅ ✅ ✅
matrix false ✅ ✅ ✅ ✅ ✅
matrix true ✅ ✅ ✅ ✅ ✅

* Default serialization method

Query Parameters

Style Explode Primitive String Array of primitives Array of strings Object
form* true* ✅ ✅ ✅ ✅ ✅
form false ✅ ✅ ✅ ✅ ✅
spaceDelimited true N/A N/A ✅ ✅ N/A
spaceDelimited false N/A N/A ✅ ✅ N/A
pipeDelimited true N/A N/A ✅ ✅ N/A
pipeDelimited false N/A N/A ✅ ✅ N/A
deepObject false N/A N/A N/A N/A ❌

* Default serialization method

Header Parameters

Style Explode Primitive String Array of primitives Array of strings Object
simple* false* ✅ ✅ ✅ ✅ ✅
simple true ✅ ✅ ✅ ✅ ✅

* Default serialization method

🚫 Error Handling

lua-oasvalidator returns a specific ERROR_CODE value, indicating the error type:

 NONE                 = 0
 INVALID_METHOD       = -1
 INVALID_ROUTE        = -2
 INVALID_PATH_PARAM   = -3
 INVALID_QUERY_PARAM  = -4
 INVALID_HEADER_PARAM = -5
 INVALID_BODY         = -6
 INVALID_RSP          = -7

An accompanying detailed error message, structured in JSON, elucidates the error:

{
  "errorCode": "INVALID_BODY",
  "detail": {
    "specRef": "#/paths/%2Fpet/put/requestBody/content/application%2Fjson/schema",
    "code": "type",
    "description": "Property has a type 'string' that is not in the following list: 'array'.",
    "instance": "#/photoUrls",
    "schema": "#/properties/photoUrls"
  }
}

🚀 Getting Started

🔧 Installation

Prerequisites:

  • lua development environment
    • lua-devel (linux)
    • or luavm(windows)
    • or brew install lua luarocks
    • or any equivalent on your system
  • cmake >= 3.1.0, cmake 2.8 may work but not well tested.
  • A C++11 compatible compiler.

Building and Installing:

To build and install lua-oasvalidator, follow the steps below:

  1. Clone and initialize the git submodules
  2. Navigate to the root directory of the lua-oasvalidator
  3. Run luarocks make to build and install 
    git clone --recurse-submodules https://github.com/nawaz1991/lua-oasvalidator.git
cd lua-oasvalidator
sudo luarocks make

🎬 Initialization

To utilize lua-oasvalidator, include the module and initialize the validator with your OpenAPI specification:

local oasvalidator = require("oasvalidator")
print(oasvalidator._VERSION)

-- Initialize and get validators
local validators = oasvalidator.GetValidators("/path/to/your/spec.json")

err_code, err_msg = validators:ValidateRoute("PUT", "/pet")
if err_code ~= 0 then
   print(err_msg)
end

For a detailed breakdown of each API, refer to the API Reference.

📜 Conclusion

lua-oasvalidator bridges the power of cpp-oasvalidator to the Lua based requirements like to write the plugins for Kong and NGINX etc. With its organized validation order, expansive parameter style support, and meticulous error reporting, it ensures your Lua-based services stay compliant with your OpenAPI specs.

📄 License

This project is licensed under the MIT License. See the LICENSE file for the full license text.

© 2024 Muhammad Nawaz. All Rights Reserved.