Skip to main content

JSight Validator Java Manual

JSight Java Validator is a Java native library, which validates all your API requests and responses against your API specification, written with JSight API language.

JSight Validator is 100% free.

Installation guide​

1. Download JSight Shared Library libjsight.so to /usr/local/bin folder*:​

wget https://jsight.io/downloads/jsight-shared-library/1.0.0/linux-x64/libjsight.so
mv libjsight.so /usr/local/bin

* You can put libjsight.so in any other folder, but in this case, you should specify its path later in JSight.Init(String) method.

2. Download JSight Java Adapter libjsightjava.so to /usr/java/packages/lib*:​

wget https://jsight.io/downloads/jsight-java-adapter/1.0.0/linux-x64/libjsightjava.so 
mv libjsightjava.so /usr/java/packages/lib

* You can put libjsightjava.so in any other folder, but in this case, you should specify its path in java.library.path property.

3. Download JSight *.java files and put them into io.jsight namespace of your Java code​

wget https://jsight.io/downloads/jsight-java-adapter/1.0.0/io.jsight.zip
unzip io.jsight.zip -d {YOUR JAVA PROJECT ROOT}/src/main/java

This archive consists of the following files:

  • ./io/jsight/JSight.java — Java adapter to JSight Shared Library.
  • ./io/jsight/ValidationError.java — supporting class.
  • ./io/jsight/ErrorPosition.java — supporting class.
  • ./io/jsight/spring/JSightFilter.java — JSight filter for Spring Boot application.
  • ./io/jsight/spring/CachedHttpServletRequest.java — supporting class.
  • ./io/jsight/spring/CachedServletInputStream.java — supporting class.

4. Check that everything is fine​

Call the function JSight.Stat():

import io.jsight.JSight;

String stat = JSight.Stat();
System.out.println(stat);

This will print out the JSight Shared Library cache, memory, and CPU usage info.

 

SUPPORT

If you face any issues with installing and configuring the JSight Shared Library or JSight Java Adapter, please feel free to write to our support:

Quick Start Guide​

Spring Boot​

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

  1. Install JSight into your Spring Boot project (see Installation guide).
  2. Describe your API using JSight API language.
  3. Set up the JSight filter.
Spring Boot Demo

Check the Spring Boot Demo application with JSight integrated on GitHub: https://github.com/jsightapi/spring-demo

Step 1. Install JSight​

See the Installation guide.

Step 2. Describe your API​

  1. Create a file, which will contain your API specification, e. g. my-api-spec.jst in the Java resource folder: ./src/main/resources/my-api-spec.jst.
  2. Specify your API in my-api-spec.jst file using JSight API language. You can use JSight Online Editor for this purpose.

For example, you can use this demo API specification:

my-api-spec.jst
JSIGHT 0.3

GET /api/users // Returns all users.
  200 [@user]

POST /api/users // Creates a new user
  Request @user
  200 @user

GET /api/users/{id} // Returns a user with the specified id.
  200 @user

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

Step 3. Set up the JSight filter​

Add @ComponentScan annotation to Spring Boot Application class, and specify "io.jsight" namespace in basePackages parameter. This will help Spring to find and load io.jsight.spring.JSightFilter component. For example, your main file can look like this:

com.example.demo.DemoApplication.java
package com.example.demo;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.ComponentScan;

@SpringBootApplication
@ComponentScan(basePackages = {"com.example.demo", "io.jsight"})
public class DemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }
}

In io.jsight.spring.JSightFilter class specify the path to the API description file in the private field apiSpecPath:

io.jsight.spring.JSightFilter.java
...

public class JSightFilter implements Filter {
    private final String apiSpecPath = defineSpecAbsolutePath("my-api-spec.jst");

    @Override
    public void doFilter(ServletRequest req, ServletResponse resp, FilterChain filterchain) 
        throws IOException, ServletException 
    {
        ...

4. Check that everything is fine​

Now start the Spring Boot server and check that everything works fine:

curl -X POST -d '{"id": 1}' localhost/users

You will get a validation error, something like this:

$ curl -X POST -d '{"id": 1}' localhost/api/users
{
  "reportedBy": "HTTP Request validation",
  "type": "http_body_error",
  "code": 32001,
  "title": "HTTP body error",
  "detail": "Required key(s) \"login\" not found",
  "position": {
    "index": 0,
    "line": 1,
    "col": 1
  }
}

That's it! Your JSight filter is installed. Now all your API requests and responses will be validated against the JSight API specification.

info

The class io.jsight.spring.JSightFilter is very simple and straightforward. You can always adjust it according to your needs. (E. g. you can change the error processing logic).

You can learn more about Java filters in the Filter javadoc.

You can learn more about JSight Validator functions in the reference section below.

class JSight​

io.jsight.JSight

Static class JSight provides access to the JSight Shared Library functions.

Call the Init method before calling the other methods. Example:

JSight.Init();
ValidationError error = JSight.ValidateHttpRequest("my-api-spec.jst", "POST", "/users", headers, body);

It is not necessary to call Init() each time. You can call it once in static section:

static {
    JSight.Init(); 
}

JSight.Init()​

Initializes JSight Shared Library (libjsight.so), which must be located in /usr/local/lib folder.

If JSight Shared Library is located in another directory, use Init(String) instead.

Call this (or Init(String)) method before calling other JSight methods.

Description

public static void Init()

Usage example:

JSight.Init();
ValidationError error = JSight.ValidateHttpRequest("my-api-spec.jst", "POST", "/users", headers, body);

It is not necessary to call Init() each time. You can call it once in static section:

static {
    JSight.Init(); 
}

JSight.Init(String)​

Initializes JSight Shared Library. Call this (or Init()) method before calling other JSight methods.

Description

public static void Init(String jsightLibDir)

Input parameters:

  • jsightLibDir — path to the directory, where JSight Shared Library (libjsight.so) resides.

Usage example:

JSight.Init("/app/lib");
ValidationError error = JSight.ValidateHttpRequest("my-api-spec.jst", "POST", "/users", headers, body);

It is not necessary to call Init(String) each time. You can call it once in static section:

static {
    JSight.Init("/app/lib"); 
}

JSight.ClearCache()​

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

Description

public static void ClearCache()

It might be 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.ClearCache()

JSight.Stat()​

Returns current JSight Shared Library status info (cache usage, memory usage, CPU usage, etc.).

Description

public static String Stat()

Usage example:

String stat = JSight.Stat();
System.out.println(stat);

JSight.ValidateHTTPRequest(…)​

Validates HTTP request against JSight API specification.

Description

public static ValidationError ValidateHTTPRequest (
    String apiSpecFilePath, 
    String requestMethod, 
    String requestUri, 
    Map<String,List<String>> requestHeaders, 
    byte[] requestBody
);

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 path string, starting from /, e. g. /users.
  • requestHeaders — a map of request headers (compatible with Spring HttpHeaders).
  • requestBody — an HTTP request body byte array.

Returns null if the HTTP request is valid. Returns ValidationError if validation fails.

Usage example:

ValidationError error = JSight.ValidateHTTPRequest(
  "my-api-spec.jst", // JSight specification path
  "POST",            // method name
  "/users",          // request path
  headers,
  body,
);

if (error != null) {
  System.out.println(error.ToJSON())
}
REMAINDER

Do not forget to initialize JSight Shared Library by the JSight.Init() method before!

JSight.ValidateHTTPResponse(…)​

Validates HTTP response against JSight API specification.

Description

public static ValidationError ValidateHttpResponse(
    String apiSpecFilePath, 
    String requestMethod, 
    String requestUri, 
    int responseStatusCode, 
    Map<String,List<String>> responseHeaders, 
    byte[] responseBody
);

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 path string, starting from /, e. g. /users.
  • responseStatusCode — an integer, representing response HTTP status code.
  • responseHeaders — a map of response headers (compatible with Spring HttpHeaders).
  • responseBody — an HTTP response body byte array.

Returns null if the HTTP response is valid. Returns ValidationError if validation fails.

Usage example:

ValidationError error = JSight.ValidateHTTPResponse(
  "my-api-spec.jst", // JSight specification path
  "POST",            // method name
  "/users",          // request path
  200,               // response status code
  headers,           // response headers
  body,              // response body
);

if (error != null) {
  System.out.println(error.ToJSON())
}
REMAINDER

Do not forget to initialize JSight Shared Library by the JSight.Init() method before!

class ValidationError​

io.jsight.ValidationError

The ValidationError class represents a validation error.

ValidationError.getCode()​

public int getCode()

Returns a validation error code.

ValidationError.getDetail()​

public String getDetail()

Returns a validation error detail.

ValidationError.getPosition()​

public ErrorPosition getPosition()

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

ValidationError.getReportedBy()​

public String getReportedBy()

Returns a validation error reporter.

ValidationError.getTitle()​

public String getTitle()

Returns a validation error title.

ValidationError.getType()​

public String getType()

Returns a validation error type.

ValidationError.toJSON()​

public String toJSON()

Returns the JSON representation of an error.

Usage example:

ValidationError error = JSight.ValidateHTTPResponse(
  "my-api-spec.jst", // JSight specification path
  "POST",            // method name
  "/users",          // request path
  200,               // response status code
  headers,           // response headers
  body,              // response body
);

if (error != null) {
  System.out.println(error.ToJSON())
}

class ErrorPosition​

io.jsight.ErrorPosition

The ErrorPosition class represents the position of an error.

ErrorPosition.getCol()​

public Integer getCol()

Returns a column number of an error position.

ErrorPosition.getFilepath()​

public String getFilepath()

Returns a file path, where an error has occurred.

ErrorPosition.getIndex()​

public Integer getIndex()

Returns an index of an error position.

ErrorPosition.getLine()​

public Integer getLine()

Returns a line number of an error position.