JSON Query Language (JQL) is a query language designed for interacting with Antly’s backend services. JQL provides a flexible and powerful way to perform CRUD (Create, Read, Update, Delete) operations and other administrative tasks through JSON-based queries. It facilitates seamless communication between front-end applications and Antly’s backend system, allowing for efficient data manipulation and retrieval.

Key Features of JQL:

• JSON-Based Syntax: JQL queries are constructed using JSON, making them easy to read and integrate with modern web technologies.
• CRUD Operations: JQL supports all essential operations required for data management, including creating, reading, updating, and deleting resources.
• Advanced Querying: Beyond basic CRUD, JQL offers capabilities for complex querying, including filtering, pagination, and aggregation, to handle sophisticated data retrieval scenarios.
• Event Handling: JQL integrates with Antly’s event system, enabling the management of events and triggers directly through queries.
• Error Handling: Built-in error handling mechanisms ensure that users receive meaningful feedback in case of issues, facilitating easier debugging and troubleshooting.

How JQL Works:

JQL operates by sending JSON-formatted requests to Antly’s backend endpoints. Each query specifies the desired operation and includes relevant parameters and data. The backend processes these queries and returns the appropriate response, which can include data results, status messages, or error information.

Use Cases:

• Data Management: Perform CRUD operations to manage data within Antly’s system, such as creating new tasks, updating existing records, or deleting outdated entries.
• Reporting: Use JQL to retrieve and aggregate data for generating reports or dashboards.
• Automation: Leverage JQL to interact with automated workflows and event triggers, streamlining repetitive tasks and business processes.

JQL is designed to be intuitive and easy to use, with a focus on providing a robust and reliable interface for interacting with Antly’s backend. Whether you are a developer, administrator, or power user, JQL offers the tools needed to efficiently manage and interact with your data.

Understanding the core concepts of JQL is essential for effectively using it to interact with Antly's backend. Below is an overview of the fundamental components and how they work:

Authentication Class

The authenticationClass specifies the method of authentication used for the JQL query. The available types include:

• jwt: JWT token authentication.
• session: HTTP-only cookie-based authentication.
• public: API access without authentication.
• oauth: OAuth 2.0 access.
• Others: Additional authentication methods may be supported, to be explained in detail as needed.

Intent

Intent refers to the specific action being performed in the JQL query. The key intents include:

• create: Adds a new resource to the system.
• update: Modifies an existing resource.
• retrieve: Retrieves a list of resources based on specified criteria.
• retrieveOne: Retrieves a single resource identified by a unique identifier.
• deleteOne: Deletes a specific resource based on its unique identifier.

Namespace

The namespace identifies the module or section of the system the action is directed towards. For example, "fleet.Vehicle" specifies the vehicle module within the fleet namespace.

Schema

Schema denotes the type of data structure or proxy used for the operation:

• model: Refers to database models which represent data structures.
• controller: Refers to proxy functions that manage interactions with models.

Unique Object

A uniqueObject is used to specify a single instance of a resource for operations like update, retrieveOne, or deleteOne. It typically includes an ID that uniquely identifies the instance.

• Example: "uniqueObject": { "id": "<instance_id>" }

Data Structure

The data structure in JQL queries consists of various fields and objects that are manipulated or retrieved:

• Simple Fields: Direct fields that hold values (e.g., "gearbox": "<type: 'automatic'|'manual'>").
• Foreign Key Objects: Referenced objects that can be further destructured to retrieve nested data (e.g., "model_colour": { "id": null, "colour": null }).

Example Queries

1. Create

   {
     "__meta__": {
       "authenticationClass": "jwt",
       "intent": "create",
       "namespace": "fleet.Vehicle",
       "return": {
         "id": null
       },
       "schema": "model"
     },
     "gearbox": "<type: 'automatic'|'manual'>",
     "model_colour": "<type: Fleet_ModelColourType>",
     "purchase_type": "<type: 'lease'|'hp'|'pcp'|'personal_loan'|'cash'>",
     "vin": "<type: string>",
     "vrm": "<type: string>",
     "year": "<type: string>"
   }
   

2. Update

{
  "__meta__": {
    "authenticationClass": "jwt",
    "intent": "update",
    "namespace": "fleet.Vehicle",
    "return": {
      "id": null
    },
    "schema": "model"
  },
  "gearbox": "<type: 'automatic'|'manual'>",
  "model_colour": "<type: Fleet_ModelColourType>",
  "purchase_type": "<type: 'lease'|'hp'|'pcp'|'personal_loan'|'cash'>",
  "vin": "<type: string>",
  "vrm": "<type: string>",
  "year": "<type: string>"
}

1. Retrieve a List

{
  "__meta__": {
    "authenticationClass": "jwt",
    "filter": {
      "name": "<filter_term>"
    },
    "intent": "retrieve",
    "namespace": "fleet.Vehicle",
    "schema": "model"
  },
  "expenses": null,
  "gearbox": null,
  "model_colour": {
    "id": null,
    "colour": null
  },
  "purchase_type": null,
  "vin": null,
  "vrm": null,
  "year": null
}

1. Retrieve One

{
  "__meta__": {
    "authenticationClass": "jwt",
    "intent": "retrieveOne",
    "namespace": "fleet.Vehicle",
    "schema": "model",
    "uniqueObject": {
      "id": "<instance_id>"
    }
  },
  "expenses": null,
  "gearbox": null,
  "model_colour": null,
  "purchase_type": null,
  "vin": null,
  "vrm": null,
  "year": null
}

1. Delete One

{
  "__meta__": {
    "authenticationClass": "jwt",
    "intent": "deleteOne",
    "namespace": "fleet.Vehicle",
    "schema": "model",
    "uniqueObject": {
      "id": "<instance_id>"
    }
  }
}