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:

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:

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:

     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:

     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:

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

4. Global Metrics

   • Endpoint: /joobq/metrics

   • Method: GET

   • Description: Fetches comprehensive metrics for the entire system.

   • Example Request:

     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.

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

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

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.