Skip to main content

JSight Validator Golang Manual

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 demo server.
  3. Test it!

Step 1. Downloads

1.1. Download JSight Go Plugin jsightplugin.so:

Go VersionOSJSight Go Plugin
19Linux x64jsightplugin.so v.1.0.0 (Go 19)
18Linux x64jsightplugin.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:

Functions

NewJSight

Creates an instance of JSight interface, which allow 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 request headers (see Golang type Header).
  • responseBody — an HTTP response body byte array.

Returns nil if the HTTP request 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 occured.

(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 occured.

(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.