# API Server

The `JoobQ::APIServer` and `APIHandler` classes enable you to integrate the JoobQ job management functionality with an HTTP server, providing a REST API for enqueuing jobs, retrieving job statuses, and monitoring queues. This section details how to set up and use the JoobQ API server and handlers to manage your job queues via HTTP requests.

### APIServer

The `APIServer` class is responsible for setting up and starting the HTTP server that hosts the JoobQ REST API. It allows clients to interact with JoobQ using simple HTTP endpoints.

#### Starting the API Server

To start the API server, call the `start` method:

```crystal
JoobQ::APIServer.start
```

This will bind the server to the address `0.0.0.0` and port `8080`, making it accessible for HTTP requests on your local network.

#### Example Usage

Here's how to start the API server:

```crystal
require "joobq"

JoobQ::APIServer.start
```

Once started, the server listens for incoming requests, allowing clients to interact with the JoobQ system.

### APIHandler

The `APIHandler` class provides the core functionality for handling different API endpoints related to job queues. It defines routes for enqueuing jobs, fetching job details, and retrieving metrics.

#### Key Features of `APIHandler`

* **Job Enqueuing**: Allows clients to enqueue new jobs into specified queues via an HTTP POST request.
* **Job Registry**: Provides an endpoint to retrieve the current registry of jobs.
* **Queue Metrics**: Offers metrics and statistics about the queues, such as queue length, job processing times, and worker status.

#### Setting Up the APIHandler

The `APIHandler` is used to define routes and their handlers for the JoobQ HTTP server. It is mounted onto the `HTTP::Server` to manage incoming requests.

#### Available Endpoints

1. **Enqueue a Job**
   * **Endpoint**: `/joobq/jobs`
   * **Method**: `POST`
   * **Description**: Enqueues a new job into a specified queue.
   * **Example Request**:

     ```sh
     curl -X POST -H "Content-Type: application/json" \
      -d '{"queue": "example_queue", "param": "value"}' \
     http://localhost:8080/joobq/jobs
     ```
2. **Job Registry**
   * **Endpoint**: `/joobq/jobs/registry`
   * **Method**: `GET`
   * **Description**: Retrieves the status and details of all jobs in the registry.
   * **Example Request**:

     ```sh
     curl http://localhost:8080/joobq/jobs/registry
     ```
3. **Queue Metrics**
   * **Endpoint**: `/joobq/queues`
   * **Method**: `GET`
   * **Description**: Retrieves metrics about the queues, such as the number of jobs, processing times, and error rates.
   * **Example Request**:

     ```sh
     curl http://localhost:8080/joobq/queues
     ```
4. **Global Metrics**
   * **Endpoint**: `/joobq/metrics`
   * **Method**: `GET`
   * **Description**: Fetches comprehensive metrics for the entire system.
   * **Example Request**:

     ```sh
     curl http://localhost:8080/joobq/metrics
     ```

### Example Usage of HTTP Server with APIHandler

To use the `APIHandler`, create an HTTP server with the handler mounted. This allows you to set up REST endpoints for interacting with JoobQ.

```crystal
require "http/server"
require "joobq"

module MyApp
  class Server
    def start
      server = HTTP::Server.new([JoobQ::APIHandler.new])
      address = "0.0.0.0"
      port = 8080
      puts "Listening on http://#{address}:#{port}"
      server.bind_tcp(address, port)
      server.listen
    end
  end
end

MyApp::Server.new.start
```

This example shows how to set up a server that listens on port `8080` and provides all the routes defined in the `APIHandler` class.

### Enqueueing Jobs via the API

To enqueue a job, send an HTTP POST request to the `/joobq/jobs` endpoint. The request body should contain the queue name and job parameters in JSON format.

#### Example Enqueue Request

```sh
curl -X POST -H "Content-Type: application/json" \
 -d '{"queue": "example_queue", "param": "value"}' \
http://localhost:8080/joobq/jobs
```

This request enqueues a new job to the `example_queue` with the parameter `"param": "value"`.

### Retrieving Queue Metrics

To fetch metrics about the job queues, you can send an HTTP GET request to `/joobq/queues`.

#### Example Metrics Request

```sh
curl http://localhost:8080/joobq/queues
```

This returns metrics such as queue size, worker activity, job throughput, and more, allowing you to monitor and manage the performance of your job queues.

### Best Practices for Using the API Server

* **Secure Access**: Ensure the API server is only accessible to trusted clients, especially when enqueuing jobs or retrieving sensitive metrics.
* **Use Proper HTTP Status Codes**: The server provides appropriate status codes for each request. Use these status codes to handle errors properly on the client side.
* **Logging**: Make use of the logging provided by `APIServer` and `APIHandler` to track activity and troubleshoot any issues.
* **Error Handling**: Implement proper error handling for API requests. If a request fails, the API server will provide an appropriate error message, which should be logged and monitored.

***

The `JoobQ::APIServer` and `APIHandler` classes provide a simple way to manage job queues via HTTP requests, making it easy to integrate job scheduling and monitoring into your application. Use these features to expose JoobQ's job management capabilities and interact with it through RESTful APIs.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.joobq.io/guides/api-server.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.