Last updated for version 0.1.28

Types

KAPIR defines several types that form the basis of its response structure.

Core Types

At the root of KAPIR types, there are six core types:

NULL
Which represents the absence of a value.
STRING
Which represents a sequence of Unicode characters.
BOOLEAN
Which represents a true or false value.
NUMBER
Which represents numeric values, including integers and floating-point numbers.
ARRAY
Which represents an ordered list of values.
OBJECT
Which represents a collection of key-value pairs (members).

Extended Types

From these core types, KAPIR defines three extended types:

STATUS Extended Type

The STATUS type is an extension of the STRING core type. Its value is either success or error, indicating whether the request was successful or not.

ERROR Extended Type

The ERROR type is an extension of the OBJECT core type. It contains information about an error that occurred during the processing of a request. It has the members:

code
A STRING representing a machine-readable error code.
message
A STRING providing a human-readable description of the error.
errors
An ARRAY of SUBERROR objects providing additional details about the error.

SUBERROR Extended Type

The SUBERROR type is also an extension of the OBJECT core type. It provides additional details about a specific error that occurred during the processing of a request. It has the members:

code
A STRING representing a machine-readable suberror code.
message
A STRING providing a human-readable description of the suberror.

These core and extended types are the foundation of KAPIR responses. Their basic yet flexible structure makes them serialization-agnostic and easy to implement across various existing data formats like JSON, XML, and YAML.

Response Structure

A KAPIR response is an OBJECT with the following members:
Members marked with a question mark (?) are optional and may be omitted if not applicable.
status • STATUS
A STATUS value indicating whether the request was successful or not.
version • STRING
A STRING representing the version of the KAPIR specification used in the response.
data • *
A member of any type containing the actual response data.
message? • STRING|NULL
A STRING providing additional information about the response.
error? • ERROR|NULL
An ERROR object providing details about any error that occurred during the processing of the request.
meta? • OBJECT|NULL
An OBJECT containing any additional metadata about the response.
ext? • OBJECT|NULL
An OBJECT containing any extension-specific data. More about extensions

In the end, a KAPIR response might look like this:

JSON used for illustration purposes.

Successful Response Example

 
{
    "status": "success",
    "version": "0.1.28",
    "data": {
        "id": 12345,
        "name": "John Doe",
        "email": "john.doe@mail.example.com",
        "roles": [
            "user",
            "admin"
        ]
    },
    "message": "User retrieved successfully",
    "meta": {
        "requestId": "abcde-12345-fghij-67890",
        "timestamp": "2024-10-22T06:22:00+02:00"
    }
}

Error Response Example

 
{
    "status": "error",
    "version": "0.1.28",
    "data": null,
    "message": "Invalid username or password",
    "error": {
        "code": "403_FORBIDDEN",
        "message": "Invalid authentication credentials",
        "errors": [
            {
                "code": "AUTH_INVALID_USERNAME",
                "message": "The provided username does not exist"
            }
        ]
    "meta": null
}