KAPIR JavaScript

About

KapirJS is a javascript module that provides a simple way to interact with JSON KAPIR APIs. It alleviates the pain of API error handling and response parsing by providing a consistent interface for data retrieval and manipulation.

How to use

First of all, you need to import the module into your project. You can do so by linking the file in your HTML:

<script src="/path/to/your/script.js"></script>

You can instantiate the KapirApi class for every API you want to use. You can optionally pass a base to the constructor:

const apiWithoutBase = new KapirApi('');

const apiWithBase = new KapirApi('https://example.com/api');

You can then make requests to that API by using the fetch method with the path to the endpoint and the options you want to use:

let response = await apiWithBase.fetch('/users', {
    method: 'GET',
    headers: {
        'Content-Type': 'application/json'
    }
});

If the KapirApi instance was created with a base URL, the base will be prepended to the paths that start with a /. If the path does not start with a / (or if the instance doesn't have a base), it will be used as is.

The fetch method will return a KapirResponse instance.

You can then retrieve the value of different members of the response:

let status = response.status; // Returns the KAPIR status ('success' or 'error)

let version = response.version; // Returns the response format version

let data = response.data; // Returns the data from the response

let message = response.message; // Returns the message from the response

let error = response.error; // Returns the error from the response (if any)

let metadata = response.metadata; // Returns the metadata from the response (if any)

Additionally, you can use the raw property to get the raw response object:

let rawResponse = response.raw; // Returns the raw response object

You can use the following methods to get more information about the response:

let isSuccess = response.isSuccess(); // Returns true if the response status is 'success'

let isError = response.isError(); // Returns true if the response status is 'error'

let hasDebugFeature = response.hasFeature('debug'); // Returns true if the response has the 'debug' feature (can be used to check for specific custom features)

You can access a history of the responses received using the responses property of KapirApi and the getLastResponse method to get the last response:

let responses = apiWithBase.responses; // Returns an array of all responses received

let lastResponse = apiWithBase.getLastResponse(); // Returns the last response received

Adding KAPIR response format versions

You can add support for other KAPIR response formats by extending the KapirResponse class. You will have to implement the isValid and getFallback methods and add a new case in the parseResponse method of the KapirApi class.

As is, the module supports KAPIR response format 25.1.0 through the KapirResponse25_1_0 class.

Classes

• KapirApi: The main class for interacting with KAPIR APIs. It provides methods to make requests and retrieve responses.

  • constructor(base): Creates a new instance of KapirApi with an optional base URL.
  • fetch(endpoint, options): Makes a request to the API and returns a KapirResponse instance.
  • getLastResponse(): Returns the last response received from the API.
  • responses: An array of all responses received from the API.
  • parseResponse(response, version = null): Parses the raw response and returns a KapirResponse instance.
  • getEndpointURL(endpoint): Returns the full URL for a given endpoint, prepending the base URL if necessary.

• KapirResponse: The base class for KAPIR responses. It provides methods to retrieve response data and metadata.

  • constructor(raw, formatVersion): Creates a new instance of KapirResponse with the raw response and version.
  • isValid(): Checks if the response is valid.
  • getFallback(): Returns a fallback response in case of an error.
  • isSuccess(): Checks if the response status is 'success'.
  • isError(): Checks if the response status is 'error'.
  • hasFeature(flag): Checks if the response has a specific feature.
  • raw: The raw response object.
  • status: The KAPIR status of the response ('success' or 'error').
  • version: The version of the KAPIR response format.
  • data: The data from the response.
  • message: The message from the response.
  • error: The error from the response (if any).
  • metadata: The metadata from the response (if any).

• KapirResponse25_1_0: A class that extends KapirResponse for KAPIR response format version 25.1.0. It implements the specific parsing logic for this version.

License

This module is released under the MIT License.

2025 © DELAN Mia