JSight Validator C Manual

JSight Validator is a C shared library, 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 C in 5 minutes:

1. Download libjsight.so binary and corresponding libjsight.h file (see below).
2. Link libjsight.so to your project as an ordinal shared library.
3. Validate HTTP requests with JSightValidateHttpRequest function.
4. Validate HTTP responses with JSightValidateHttpResponse function.

For more details see “Function reference” section.

Downloads

OS	JSight Shared Library	.h file
Linux x64	libjsight.so v.1.0.0	libjsight.h

SUPPORT

If you face any issues with installing the JSight C Shared Library, please feel free to write to our support:

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

Function Reference

JSightClearCache()

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

Description

int JSightClearCache();

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

info

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

Usage example:

JSightClearCache();

struct ValidationError* error = JSightValidateHttpRequest(api_spec_file_path, request_method, request_uri, request_headers, request_body);
freeValidationError(error);

JSightGOMAXPROCS(…)

Specifies the maximum number of threads per process, which will be used for message validation. By default, it equals the number of CPU cores. Usually, you do not need to specify this option, since it may be required only for highload services. This option sets the GOMAXPROCS runtime variable.

Description

int JSightGOMAXPROCS(int n);

Input parameters:

• n — GOMAXPROCS value.

Usage example:

JSightGOMAXPROCS(1);

JSightSerializeError(…)

Serializes message validation error into a string in a specified format.

Description

char* JSightSerializeError(char* format, struct ValidationError* cErr);

Input parameters:

• format — serializing format. Only json format is supported in this version.
• cErr — an error, which was previously returned by call to functions: JSightValidateHttpRequest(…) or JSightValidateHttpResponse(…).

Returns serialized string, according to the specified format.

Usage example:

struct ValidationError* error = JSightValidateHttpRequest(api_spec_file_path, request_method, request_uri, request_headers, request_body);

if( error != NULL ) {
  char* s = JSightSerializeError("json", error);
  printf(s);
  free(s);
  freeValidationError(error);
}

JSightStat()

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

Description

char* JSightStat();

Usage example:

char* stat = JSightStat();
printf(stat);
free(stat);

JSightValidateHttpRequest(…)

Validates HTTP request against JSight API specification.

Description

struct ValidationError* JSightValidateHttpRequest(
  char*           apiSpecFilePath, 
  char*           requestMethod, 
  char*           requestURI, 
  struct Header** requestHeaders, 
  char*           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 string, starting from /.
• requestHeaders — request headers, NULL-terminated array of struct Header.
• requestBody — an HTTP request body string.

Returns NULL if the HTTP request is valid. Returns pointer to struct ValidationError interface if validation fails.

Usage example:

struct ValidationError* error = JSightValidateHttpRequest(api_spec_file_path, request_method, request_uri, request_headers, request_body);

if( error != NULL ) {
  char* s = JSightSerializeError("json", error);
  printf(s);
  free(s);
  freeValidationError(error);
}

JSightValidateHttpResponse(…)

Validates HTTP response against JSight API specification.

Description

struct ValidationError* JSightValidateHttpResponse(
  char*           apiSpecFilePath, 
  char*           requestMethod, 
  char*           requestURI, 
  int             responseStatusCode, 
  struct Header** responseHeaders, 
  char*           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 string, starting from /.
• responseStatusCode — an integer, representing response HTTP status code.
• responseHeaders — response headers, NULL-terminated array of struct Header.
• responseBody — an HTTP response body string.

Returns NULL if the HTTP response is valid. Returns pointer to struct ValidationError interface if validation fails.

Usage example:

struct ValidationError * error = JSightValidateHttpResponse(api_spec_file_path, request_method, request_uri, response_status_code, response_headers, response_body);

if( error != NULL ) {
  char* s = JSightSerializeError("json", error);
  printf(s);
  free(s);
  freeValidationError(error);
}

freeValidationError(…)

Deallocates the memory previously allocated by call to functions JSightValidateHttpRequest(…) or JSightValidateHttpResponse(…).

Description

void freeValidationError(struct ValidationError * error) 

Input parameters:

• error — a ValidationError pointer to be deallocated.

Usage example:

struct ValidationError * error = JSightValidateHttpResponse(api_spec_file_path, request_method, request_uri, response_status_code, response_headers, response_body);

freeValidationError(error);

Structs

struct ErrorPosition

Represents the position of an error.

struct ErrorPosition {
    char * Filepath;
    int  * Index;
    int  * Line;
    int  * Col;
};

struct Header

Represents a single HTTP header.

struct Header {
    char * Name;
    char * Value;
};

struct ValidationError

Represents a validation error.

struct ValidationError
{
    char * ReportedBy;
    char * Type;
    int Code;
    char * Title;
    char * Detail;
    struct ErrorPosition * Position;
    char ** Trace; // Null-terminated array of strings.
};