JSight Validator Golang Manual

JSight Golang Validator is a golang plugin, which validates all your API requests and responses against your API specification, written with JSight API language.

JSight Validator is 100% free.

Quick Start Guide

You can start using JSight on Go in 5 minutes. Just perform three simple steps:

1. Download JSight Go plugin.
2. Create a demo server.
3. Test it!

Golang JSight Demo

Check the Golang JSight Demo on GitHub: https://github.com/jsightapi/golang-demo

Step 1. Downloads

1.1. Download JSight Go Plugin jsightplugin.so:

Go Version	OS	JSight Go Plugin
19	Linux x64	jsightplugin.so v.1.0.0 (Go 19)
18	Linux x64	jsightplugin.so v.1.0.0 (Go 18)

1.2. Download to the same folder the file jsight.go:

Download `jsight.go`.

Step 2. Demo Server

2.1. Create in the same folder the API specification file my-api-spec.jst with this content:

my-api-spec.jst

JSIGHT 0.3

POST /users // Create a user
  Request 
    @user
  200
    "OK"

TYPE @user
{
  "id": 1,
  "login": "tom",
  "name": "John" // {optional: true}
}

2.2. Create in the same folder the file main.go with this code:

main.go

package main

import (
    "fmt"
    "io"
    "net/http"
)

var jSight JSight

func main() {
    jSight = NewJSight("./jsightplugin.so")
    http.HandleFunc("/", handle)
    fmt.Println("Listening on 8000 port…")
    http.ListenAndServe(":8000", nil)
}

func handle(w http.ResponseWriter, req *http.Request) {

    jsightSpecPath := "./my-api-spec.jst"
    reqBody, _ := io.ReadAll(req.Body)

    jSight.ClearCache() // Comment this line in production.

    err := jSight.ValidateHTTPRequest(
        jsightSpecPath,
        req.Method,
        req.RequestURI,
        req.Header,
        reqBody,
    )

    if err != nil {
        w.WriteHeader(400)
        w.Write([]byte(err.ToJSON()))
        return
    }

    responseStatusCode := 200
    responseBody := []byte("\"User created!\"\n")
    responseHeaders := http.Header{}

    err = jSight.ValidateHTTPResponse(
        jsightSpecPath,
        req.Method,
        req.RequestURI,
        responseStatusCode,
        responseHeaders,
        responseBody,
    )

    if err != nil {
        w.WriteHeader(500)
        w.Write([]byte(err.ToJSON()))
        return
    }

    w.WriteHeader(responseStatusCode)
    w.Write([]byte(responseBody))
}

2.3. Start the demo server:

go run main.go jsight.go

You will get:

$ go run main.go jsight.go
Listening on 8000 port…

Step 3. Testing

3.1. Test the API with a valid request:

curl --request POST localhost:8000/users -d '{"id":123,"login":"john"}'

You will get a successful response, like this:

$ curl --request POST localhost:8000/users -d '{"id":123,"login":"john"}'
"User created!"

3.2. Test the API with an invalid request:

curl --request POST localhost:8000/monsters -d '{"id":123,"login":"john"}'

You will get a validation error, something like this:

$ curl --request POST localhost:8000/monsters -d '{"id":123,"login":"john"}'
{
  "reportedBy": "HTTP Request validation",
  "type": "path_error",
  "code": 24001,
  "title": "Request path is not allowed",
  "detail": "Request `POST /monsters` is not allowed."
}

That's it! For more info on JSight Validator functions learn the “Functions” and “type JSight” sections.

SUPPORT

If you face any issues with installing the JSight Go Plugin, please feel free to write to our support:

• Email: support@jsight.io
• Telegram: @jsight_support

Functions

NewJSight

Creates an instance of JSight interface, which allows you to access the JSight Go Plugin functions.

Description

func NewJSight(pluginPath string) JSight

Input parameters:

• pluginPath — path to jsightplugin.so file.

Usage example:

jSight := NewJSight("./lib/jsightplugin.so")

type JSight

Interface JSight provides access to the JSight Go Plugin functions.

JSight interface definition:

type JSight interface {
    ClearCache()
    Stat() string
    ValidateHTTPRequest(apiSpecFilePath, requestMethod, requestURI string, requestHeaders map[string][]string, requestBody []byte) JSightValidationError
    ValidateHTTPResponse(apiSpecFilePath, requestMethod, requestURI string, responseStatusCode int, responseHeaders map[string][]string, responseBody []byte) JSightValidationError
}

(j) ClearCache()

Clears JSight Validator cache (where compiled API Specifications are cached).

Description

func (JSight) ClearCache()

It is useful to call ClearCache() in debug mode each time before data validation.

info

Avoid calling ClearCache() in production mode! It slows down validation dramatically.

Usage example:

jSight := NewJSight("./lib/jsightplugin.so")

jSight.ClearCache()

(j) Stat()

Returns current JSight Go Plugin status info (cache usage, etc.).

Description

func (JSight) Stat() string

Usage example:

jSight := NewJSight("./lib/jsightplugin.so")

jSight.Stat()

(j) ValidateHTTPRequest(…)

Validates HTTP request against JSight API specification.

Description

func (JSight) ValidateHTTPRequest(
  apiSpecFilePath string, 
  requestMethod   string, 
  requestURI      string, 
  requestHeaders  map[string][]string, 
  requestBody     []byte
) JSightValidationError | nil

Input parameters:

• apiSpecFilePath — a path to a JSight API specification file.
• requestMethod — HTTP 1.1 method name in upper case (e. g. "GET").
• requestURI — a request URI string, starting from /.
• requestHeaders — a map of request headers (see Golang type Header).
• requestBody — an HTTP request body byte array.

Returns nil if the HTTP request is valid. Returns JSightValidationError interface if validation fails.

Usage example:

err := jSight.ValidateHTTPRequest(
  jsightSpecPath,
  method,
  requestURI,
  header,
  body,
)

if err != nil {
  fmt.Println(err.ToJSON())
}

(j) ValidateHTTPResponse(…)

Validates HTTP response against JSight API specification.

Description

func (JSight) ValidateHTTPResponse(
  apiSpecFilePath    string, 
  requestMethod      string, 
  requestURI         string, 
  responseStatusCode int, 
  responseHeaders    map[string][]string, 
  responseBody       []byte
) JSightValidationError | nil

Input parameters:

• apiSpecFilePath — a path to a JSight API specification file.
• requestMethod — HTTP 1.1 method name in upper case (e. g. "GET").
• requestURI — a request URI string, starting from /.
• responseStatusCode — an integer, representing response HTTP status code.
• responseHeaders — a map of response headers (see Golang type Header).
• responseBody — an HTTP response body byte array.

Returns nil if the HTTP response is valid. Returns JSightValidationError interface if validation fails.

Usage example:

err = jSight.ValidateHTTPResponse(
  jsightSpecPath,
  req.Method,
  req.RequestURI,
  responseStatusCode,
  responseHeaders,
  responseBody,
)

if err != nil {
  fmt.Println(err.ToJSON())
}

type JSightValidationError

JSightValidationError interface represents a validation error.

JSightValidationError interface definition:

type JSightValidationError interface {
    Code()       int
    Detail()     string
    Position()   JSightPosition
    ReportedBy() string
    Title()      string
    Type()       string
    ToJSON()     string
}

(e) Code()

func (JSightValidationError) Code() int

Returns a validation error code.

(e) Detail()

func (JSightValidationError) Detail() string

Returns a validation error detail.

(e) Position()

func (JSightValidationError) Position() string

Returns an instance of JSightPosition interface, which represents the position, where the error has occurred.

(e) ReportedBy()

func (JSightValidationError) ReportedBy() string

Returns a validation error reporter.

(e) Title()

func (JSightValidationError) Title() string

Returns a validation error title.

(e) Type()

func (JSightValidationError) Type() string

Returns a validation error type.

(e) ToJSON()

func (JSightValidationError) ToJSON() string

Returns the JSON representation of an error.

Usage example:

err := jSight.ValidateHTTPRequest(
  jsightSpecPath,
  method,
  requestURI,
  header,
  body,
)

if err != nil {
  fmt.Println(err.ToJSON())
}

type JSightPosition

JSightPosition interface represents the position of an error.

JSightPosition interface definition:

type JSightPosition interface {
    Col()      int
    Filepath() string
    Index()    int
    Line()     int
}

(p) Col()

func (JSightPosition) Col() string

Returns a column number of an error position.

(p) Filepath()

func (JSightPosition) Filepath() string

Returns a file path, where an error has occurred.

(p) Index()

func (JSightPosition) Index() string

Returns an index of an error position.

(p) Line()

func (JSightPosition) Line() string

Returns a line number of an error position.