Before you execute the program for the first time, you should check in your config and data files.

The config.json file should look something like this:

{   
    "appname": "New app",
    "debug": true,
    "admin-path": "admin.jserv",
    "key-path": "keys.jserv",
    "ip": "localhost", 
    "port": 4040, 
    "Requests": 
    {   
        "GET": true, 
        "POST": true, 
        "PUT": false, 
        "HEAD": true, 
        "DELETE": true, 
        "PATCH": false, 
        "OPTIONS": false 
    }, 
    "Permissions": 
    { 
        "QObject": "user", 
        "QAllObjects": "user",
        "QAttribute": "user", 
        "QAllAttributes": "user", 
        "QByAttribute": "user", 
        "QnewId": "admin", 
        "AEmpty": "user", 
        "AObject": "user", 
        "AAttribute": "user", 
        "MObject": "user", 
        "MAttribute": "user", 
        "DObject": "user", 
        "DAttribute": "user" 
    },
    "Aliases":
    {
        "127.0.0.1":"localhost"
    }
}

Change the IP and port to whatever you need. Debug mode will show more detailed request errors. The requests list determines which requests the program will accept. For now, you can leave this alone.

The permissions list determines which requests can be made with the user keys, whereas admin keys will have access to all of them.

The aliases list will change how certain addresses are displayed within the console.

When you run the program for the first time, an Admin API key will generate in the admin.jserv file, and a User API key will generate in the keys.jserv file at the paths specified in the config files. The program will reject any requests that do not have these keys in the "x-api-key" header.

If you want the config file in a different path, you can enter the path as a command line argument when running jServ.

jServ relies on the use of HTTP requests. This is how data is sent back and forth between the instance and your program. There are several built-in request handlers that allow a variety of methods to work with your data (See below).

Each request will give a response in the form of a JSON object. It appears as the following (with example values),

{
    "status": "ok",
    "message": "Successfully queried some-database for some-object",
    "data": {
        "id": 0,
        "data": {"some-key": "some-value"}
    }
}

The status value will appear as either "ok" or "error", and the message value will display a message either confirming the success, or giving an error message. The data value may be empty, and will only contain data if the request returns it.

To get set up quickly, consider using one of our libraries with methods to handle the requests.

Python - https://github.com/Codealchemi/jServ-python-lib

The data structure relies on three classes, DataObject, AttributeContainer, and Collection.

DataObject is the class that all instances in the database come from. When serialized as a JSON object, it appears as the following (with example values),

{
    "id": 0,
    "data": {"some-key": "some-value"}
}

The reason the object has only two fields is that the developer defines what attributes each object will have within the data field. The id field is the only definite field to any object, as it is required for the API to be functional. It is dependent on you to implement field enforcement in your applications, and to ensure that the data fields are consistent across all objects.

AttributeContainer is a class that serves the sole purpose of being a proxy between JSON objects passed in the API requests. When serialized as a JSON object, it appears as the following (with example values),

{
    "some-key": "some-value"
}

Some of the requests require a single value to be passed in to the request body in the form of an AttributeContainer object, as this is the only way to maintain flexible typing within the database. The AttributeContainer class acts as a model within the program to translate that data seamlessly to the Collection and DataObject classes.

Collection is simply a container within the program for a database and its name. When written as a JSON object, it appears as the following (with example values),

{
    "name": "some-name",
    "data-list": [
        {
        "id": 0,
        "data": {"some-key": "some-value"}
        }
    ]
}

The Collection class exists to keep track of each database within the server. Within the program, the name corresponds to a filename in the Databases folder, which is what comprises the dataList in the class.

jServ's API is built around a system of specific requests and query parameters.

__/query

Queries a collection for a specific object by id. Returns the whole object in JSON.
Query Parameters:

• db - The name of the collection you're querying
• id - The id of the object you're querying

__/query/objects

Queries a collection for all objects. Returns a list of objects in JSON.
Query Parameters:

• db - The name of the collection you're querying

__/query/attribute

Queries a collection for a specific attribute of an object by id and name. Returns the attribute value in an AttributeContainer object.
Query Parameters:

• db - The name of the collection you're querying
• id - The id of the object you're querying
• a - The name of the attribute you're querying

__/query/allAttributes

Queries a collection for all attributes of a specific key in every object. If an object does not have an attribute of the passed key, the object is skipped. The query returns a list of ids of the DataObjects that have the attribute.
Query Parameters:

• db - The name of the collection you're querying
• a - the name of the attributes you're querying

__/query/byAttribute

Queries a collection for objects that share the same value of a specific attribute. If an object does not have an attribute of the passed key, the object is skipped. The query returns a list of all the objects with the attribute and value. (Requires an AttributeContainer JSON object to be passed in the body)
Query Parameters:

• db - The name of the collection you're querying
• a - The name of the attributes you're querying

__/query/newId

Returns an unused id in a collection
Query Parameters:

• db - The name of the collection you're querying

__/add

Adds a new empty object to a collection by id.
Query Parameters:

• db - The name of the collection you're adding to
• id - The id of the object you're adding

__/add/object

Adds a new JSON object to a collection (Requires an DataObject JSON object to be passed in the body).
Query Parameters:

• db - The name of the collection you're adding to

__/add/attribute

Adds an attribute to an object in a collection by id (Requires an AttributeContainer JSON object to be passed in the body).
Query Parameters:

• db - The name of the collection you're object is in
• id - The id of the object you're adding to
• a - The name of the attribute you're adding

__/mod/object

Modifies the id of an object in a collection by id.
Query Parameters:

• db - The name of the collection the object is in
• id - The id of the object you're modifying
• v - The new id of the object you're modifying

__/mod/attribute

Modifies an attribute of an object in a collection by id (Requires an AttributeContainer JSON object to be passed in the body).
Query Parameters:

• db - The name of the collection the object is in
• id - The id of the object you're modifying
• a - The name of the attribute you're modifying

__/delete/object

Deletes an object from a collection by id.
Query Parameters:

• db - The name of the collection you're deleting from
• id - The id of the object you're deleting

__/delete/attribute

Deletes an attribute from an object by id.
Query Parameters:

• db - The name of the collection you're deleting from
• id - The id of the object you're deleting
• a - The name of the attribute you're deleting

Copyright (c) 2022, Kristofer Ter-Gabrielyan. All Rights Reserved. Permission to modify and redistribute is granted under the terms of the Apache 2.0.