Tickets API

This document provides detailed technical documentation for the Tickets API, which is responsible for managing support tickets within the system. It is intended for developers who will be maintaining and extending this service.

The API is a standard RESTful service built with Spring Boot. For a general overview of the project's architecture and technology stack, please refer to the main technical stack documentation. For a quick guide on running the application, see the Quick Start Guide.

Create Ticket

This endpoint creates a new support ticket.

POST /api/tickets

The creation process is transactional and triggers an asynchronous event upon successful persistence.

Implementation Details

The TicketController handles the incoming request, delegating the core logic to the TicketService.

// src/main/java/com/slalom/demo/ticketing/controller/TicketController.java

@PostMapping
public ResponseEntity<TicketResponse> createTicket(@Valid @RequestBody TicketRequest request) {
    log.info("REST: Creating new ticket");
    TicketResponse response = ticketService.createTicket(request);
    return new ResponseEntity<>(response, HttpStatus.CREATED);
}

The TicketService performs the following actions:

1. Builds a Ticket entity from the incoming TicketRequest DTO.
2. Persists the new Ticket entity to the MySQL database using Spring Data JPA's ticketRepository.save().
3. Publishes a TicketEvent with eventType: "CREATED" to a RabbitMQ message queue. This allows other services to react to ticket creation asynchronously.
4. Maps the persisted Ticket entity to a TicketResponse DTO and returns it.

// src/main/java/com/slalom/demo/ticketing/service/TicketService.java

@Transactional
public TicketResponse createTicket(TicketRequest request) {
    log.info("Creating new ticket: {}", request.getTitle());

    Ticket ticket = Ticket.builder()
            .title(request.getTitle())
            // ... other fields
            .build();

    Ticket savedTicket = ticketRepository.save(ticket);
    log.info("Ticket created with ID: {}", savedTicket.getId());

    // Publish ticket created event
    publishTicketEvent(savedTicket, "CREATED");

    return toResponse(savedTicket);
}

Request Body

The request body must be a JSON object conforming to the TicketRequest structure. The @Valid annotation triggers server-side validation based on constraints defined in the DTO.

For detailed information on the fields, validation rules, and data types, refer to the Data Models documentation.

Example Request:

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.",
  "status": "OPEN",
  "priority": "HIGH",
  "requesterEmail": "john.doe@slalom.com",
  "assignedTo": null
}

Response

• Success: 201 Created with the TicketResponse object in the body, including the server-generated id and timestamps.
• Bad Request: 400 Bad Request if the request body fails validation. See the Error Handling Guide for the error response format.

---

Get All Tickets

This endpoint retrieves a list of tickets. It supports optional filtering by status or requester email.

GET /api/tickets

Implementation Details

The controller method accepts two optional RequestParam parameters: status and requesterEmail.

Important: The current implementation in TicketController can only handle one filter parameter at a time. If both status and requesterEmail are provided, the status filter will take precedence and requesterEmail will be ignored. This is a known limitation that could be improved by using a more advanced query mechanism like JPA Specifications or Querydsl.

// src/main/java/com/slalom/demo/ticketing/controller/TicketController.java

@GetMapping
public ResponseEntity<List<TicketResponse>> getAllTickets(
        @RequestParam(required = false) TicketStatus status,
        @RequestParam(required = false) String requesterEmail) {

    log.info("REST: Fetching tickets with filters - status: {}, requesterEmail: {}", status, requesterEmail);

    List<TicketResponse> tickets;
    if (status != null) {
        tickets = ticketService.getTicketsByStatus(status);
    } else if (requesterEmail != null) {
        tickets = ticketService.getTicketsByRequester(requesterEmail);
    } else {
        tickets = ticketService.getAllTickets();
    }

    return ResponseEntity.ok(tickets);
}

The TicketService contains dedicated, read-only transactional methods that call the corresponding TicketRepository finders.

Query Parameters

Parameter	Type	Description
status	String	(Optional) Filters tickets by their status. Must match one of the TicketStatus enum values (e.g., OPEN, IN_PROGRESS).
requesterEmail	String	(Optional) Filters tickets by the requester's email address.

Example Requests

Get all tickets:

GET http://localhost:8080/api/tickets

Get tickets by status:

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

Get tickets by requester:

GET http://localhost:8080/api/tickets?requesterEmail=john.doe@slalom.com

Response

• Success: 200 OK with a JSON array of TicketResponse objects. The array will be empty if no tickets match the criteria.

---

Get Ticket by ID

This endpoint retrieves a single ticket by its unique identifier.

GET /api/tickets/{id}

Implementation Details

The id is extracted from the URL path using @PathVariable. The TicketService uses ticketRepository.findById(id) to fetch the entity.

If no ticket is found for the given id, the service throws a RuntimeException. This exception is expected to be caught by a global exception handler, which translates it into a 404 Not Found HTTP response.

// src/main/java/com/slalom/demo/ticketing/service/TicketService.java

@Transactional(readOnly = true)
public TicketResponse getTicket(Long id) {
    log.info("Fetching ticket with ID: {}", id);

    Ticket ticket = ticketRepository.findById(id)
            .orElseThrow(() -> new RuntimeException("Ticket not found with id: " + id));

    return toResponse(ticket);
}

Response

• Success: 200 OK with the corresponding TicketResponse object in the body.
• Not Found: 404 Not Found if no ticket with the specified id exists. See the Error Handling Guide.

Example Request

GET http://localhost:8080/api/tickets/1

---

Update Ticket

This endpoint updates an existing ticket. It performs a full replacement of all mutable fields provided in the request body.

PUT /api/tickets/{id}

Implementation Details

The update process is transactional and involves several key steps within the TicketService:

1. Fetch the existing Ticket entity by id. If not found, a RuntimeException is thrown.
2. Update the entity's properties with values from the TicketRequest DTO.
3. Business Logic: A specific rule is applied to the resolvedAt timestamp. It is set to the current time only if the status is being changed to RESOLVED or CLOSED and the resolvedAt field is currently null. This prevents the resolved timestamp from being overwritten on subsequent updates.
4. The updated entity is saved back to the database.
5. An asynchronous TicketEvent with eventType: "UPDATED" is published to RabbitMQ.
6. The updated entity is mapped to a TicketResponse and returned.

// src/main/java/com/slalom/demo/ticketing/service/TicketService.java

@Transactional
public TicketResponse updateTicket(Long id, TicketRequest request) {
    // ... find ticket or throw exception ...

    ticket.setTitle(request.getTitle());
    // ... update other fields ...

    // Set resolved timestamp if status changed to RESOLVED or CLOSED
    if ((request.getStatus() == TicketStatus.RESOLVED || request.getStatus() == TicketStatus.CLOSED)
            && ticket.getResolvedAt() == null) {
        ticket.setResolvedAt(LocalDateTime.now());
    }

    Ticket updatedTicket = ticketRepository.save(ticket);
    
    // Publish ticket updated event
    publishTicketEvent(updatedTicket, "UPDATED");

    return toResponse(updatedTicket);
}

Request Body

The request body must be a valid TicketRequest JSON object. For details, see the Data Models documentation.

Example Request (Updating status):

PUT http://localhost:8080/api/tickets/1
Content-Type: application/json

{
  "title": "Laptop won't start",
  "description": "My laptop won't turn on... Tried holding power button for 30 seconds.",
  "status": "IN_PROGRESS",
  "priority": "HIGH",
  "requesterEmail": "john.doe@slalom.com",
  "assignedTo": "tech.support@slalom.com"
}

Response

• Success: 200 OK with the updated TicketResponse object in the body.
• Not Found: 404 Not Found if the id does not exist.
• Bad Request: 400 Bad Request if the request body fails validation.

---

Delete Ticket

This endpoint permanently deletes a ticket from the system.

DELETE /api/tickets/{id}

Implementation Details

The TicketService first verifies the ticket's existence using ticketRepository.existsById(id). This is done to provide a consistent "not found" error, as deleteById does not throw an exception if the entity doesn't exist. If the ticket exists, ticketRepository.deleteById(id) is called within the transaction.

// src/main/java/com/slalom/demo/ticketing/service/TicketService.java

@Transactional
public void deleteTicket(Long id) {
    log.info("Deleting ticket with ID: {}", id);

    if (!ticketRepository.existsById(id)) {
        throw new RuntimeException("Ticket not found with id: " + id);
    }

    ticketRepository.deleteById(id);
    log.info("Ticket deleted: {}", id);
}

The controller method returns a 204 No Content status, which is standard practice for successful DELETE operations that do not return a body.

// src/main/java/com/slalom/demo/ticketing/controller/TicketController.java

@DeleteMapping("/{id}")
public ResponseEntity<Void> deleteTicket(@PathVariable Long id) {
    log.info("REST: Deleting ticket with ID: {}", id);
    ticketService.deleteTicket(id);
    return ResponseEntity.noContent().build();
}

Response

• Success: 204 No Content with an empty body.
• Not Found: 404 Not Found if no ticket with the specified id exists. See the Error Handling Guide.

Example Request

DELETE http://localhost:8080/api/tickets/1