Build your backend fast, no strings attached | Adapt the server's API and workflow to your project | Multiplatform, Simple, well-documented and easy to use |
---|---|---|
jServ is an open source project designed to help backend developers get a server, database, and API up and running as soon as possible. |
jServ has a flexible data structure that allows you to customize the database and it's functionality, with or without modifying the code. |
jServ's driving force is it's use of JSON in it's data structure, allowing for a practical and effortless experience. |
To set up jServ, download the latest release, and unzip it into a folder, and run the executable. You will have a
config.json
file.
There will also be a directory called Databases
, with an example.json
given to get started. To add a collection to the program, simply add a json file of any name, and add []
to the first line, and the program will read it.
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.