Example Requests

This document provides a comprehensive guide to interacting with the IT Ticketing Service API using standard HTTP requests. The examples provided are sourced from the example-requests.http file located in the project root, which can be used directly with compatible IDE extensions for rapid testing and development.

For a complete definition of all available endpoints, data models, and response codes, please refer to the official API Reference for Tickets.

HTTP File Usage

The example-requests.http file is a plain text file containing a series of HTTP requests formatted for execution by common developer tools. This allows developers to test the API endpoints without leaving their code editor.

Using with an IDE

• VS Code: Install the popular REST Client extension. Open the example-requests.http file, and a "Send Request" link will appear above each request.
• IntelliJ IDEA (Ultimate): The IDE has a built-in HTTP Client. Simply open the example-requests.http file, and you will see run icons in the gutter next to each request.

Using this file is highly recommended for local development and debugging. For instructions on setting up the application locally, see the Local Setup Guide.

Create Ticket Examples

Creating a ticket is the primary entry point for new support issues. This is done via a POST request to the /api/tickets endpoint. The backend uses Spring Boot's validation starter to enforce rules on the incoming data. Upon successful creation, the application publishes a CREATED event to the ticket.exchange in RabbitMQ.

Minimal Required Fields

The API allows for ticket creation without an immediate assignment. In this case, the assignedTo field can be set to null.

### Create a new ticket
POST http://localhost:8080/api/tickets
Content-Type: application/json

{
  "title": "Laptop won't start",
  "description": "My laptop won't turn on after the latest Windows update. The power light blinks once but nothing appears on screen.",
  "status": "OPEN",
  "priority": "HIGH",
  "requesterEmail": "john.doe@example.com",
  "assignedTo": null
}

• title: A brief, mandatory summary of the issue.
• description: A detailed, mandatory explanation of the problem.
• status: The initial state of the ticket. Must be one of the predefined values. See the API Reference for a full list.
• priority: The urgency of the ticket. Must be one of the predefined values.
• requesterEmail: A valid email address for the person reporting the issue.
• assignedTo: The email or group name assigned to handle the ticket.

The valid priority values are:

• LOW
• MEDIUM
• HIGH
• CRITICAL

Basic Ticket Creation (All Fields)

This example shows a request with all fields populated, including assigning the ticket to a specific support group upon creation.

### Create another ticket
POST http://localhost:8080/api/tickets
Content-Type: application/json

{
  "title": "Unable to access shared drive",
  "description": "Getting 'Access Denied' error when trying to open the Finance shared drive",
  "status": "OPEN",
  "priority": "MEDIUM",
  "requesterEmail": "jane.smith@example.com",
  "assignedTo": "support@example.com"
}

Query Examples

The API provides several ways to retrieve ticket data using GET requests. These endpoints are powered by Spring Data JPA, which translates the API calls into efficient SQL queries against the MySQL database.

Get All Tickets

Returns a JSON array of all tickets in the system. Use with caution in a production environment with a large number of tickets, as it can lead to performance issues. Pagination is a likely future enhancement.

### Get all tickets
GET http://localhost:8080/api/tickets

Filter by Status

You can filter the list of tickets by providing a status query parameter. This is useful for building dashboards, such as a view of all currently open tickets.

### Get tickets by status
GET http://localhost:8080/api/tickets?status=OPEN

The valid status values are:

• OPEN
• IN_PROGRESS
• WAITING_ON_CUSTOMER
• RESOLVED
• CLOSED

Filter by Requester Email

To find all tickets submitted by a specific user, use the requesterEmail query parameter.

### Get tickets by requester email
GET http://localhost:8080/api/tickets?requesterEmail=john.doe@example.com

Get Specific Ticket by ID

To retrieve a single ticket, append its unique ID to the URL path. The ID is the primary key generated by the database upon creation.

### Get ticket by ID (replace {id} with actual ID)
GET http://localhost:8080/api/tickets/1

Note: You must replace {id} with the actual numeric ID of the ticket you wish to retrieve. A request to a non-existent ID will result in a 404 Not Found response.

Update Examples

Updates are performed using the PUT method on a specific ticket's resource URL. The PUT method requires the entire ticket object to be sent in the request body. Sending a partial object may result in data loss for the omitted fields, as it's a full resource replacement, not a patch.

Upon a successful update, the application publishes an UPDATED event to RabbitMQ.

Status and Assignment Update

This example demonstrates updating a ticket's status from OPEN to IN_PROGRESS and assigning it to a technician. The description is also updated to include troubleshooting steps already taken.

### Update a ticket (replace {id} with actual ID)
PUT http://localhost:8080/api/tickets/1
Content-Type: application/json

{
  "title": "Laptop won't start",
  "description": "My laptop won't turn on after the latest Windows update. The power light blinks once but nothing appears on screen. Tried holding power button for 30 seconds.",
  "status": "IN_PROGRESS",
  "priority": "HIGH",
  "requesterEmail": "john.doe@example.com",
  "assignedTo": "techsupport@example.com"
}

Gotcha: Because this is a PUT request, you must provide values for all fields, even those that are not changing. If you omit a field like requesterEmail, the ORM (Spring Data JPA) may attempt to set it to null in the database, which could fail if the column has a NOT NULL constraint.

Resolving a Ticket

This example demonstrates marking a ticket as resolved, typically after the issue has been fixed. The description is updated to document the resolution steps.

### Resolve a ticket
PUT http://localhost:8080/api/tickets/1
Content-Type: application/json

{
  "title": "Laptop won't start",
  "description": "My laptop won't turn on after the latest Windows update. Resolution: Performed hard reset and BIOS update.",
  "status": "RESOLVED",
  "priority": "HIGH",
  "requesterEmail": "john.doe@example.com",
  "assignedTo": "techsupport@example.com"
}

Delete Examples

Tickets can be permanently removed from the system using a DELETE request.

Removing a Ticket by ID

This is a destructive and irreversible operation. A successful deletion will typically return a 204 No Content or 200 OK response.

### Delete a ticket (replace {id} with actual ID)
DELETE http://localhost:8080/api/tickets/1

Warning: There is no "soft delete" mechanism implemented by default. Once a ticket is deleted via this endpoint, the record is removed from the database. Exercise caution when using this endpoint.

Actuator Endpoints

Spring Boot Actuator provides production-ready monitoring and management features. The following endpoints are useful for health checks and application information.

Health Check

Returns the health status of the application. This endpoint is commonly used by load balancers, orchestration systems, and monitoring tools to verify that the application is running properly.

### Health check
GET http://localhost:8080/actuator/health

A successful response typically returns a 200 OK status with a JSON body indicating the application's health status.

Application Info

Returns general information about the application, such as version, description, and other metadata configured in the application.properties or application.yml file.

### Application info
GET http://localhost:8080/actuator/info