API Overview

This document provides a comprehensive technical overview of the IT Ticketing Service's RESTful API. It is intended for developers responsible for maintaining, extending, or integrating with this service. The API facilitates full CRUD (Create, Read, Update, Delete) operations on IT support tickets.

The API is built using Spring Boot 3.2.4 and its spring-boot-starter-web module, which leverages an embedded Tomcat server by default.

Base URL

All API endpoints are relative to a base URL, which is determined by the server's host, port, and the application's context path.

Default Endpoint Base Path

By default, the application runs on port 8080. The primary API resources are located under the /api path. The main resource collection for this service is tickets.

• API Base Path: /api/tickets
• Actuator Base Path: /actuator

A complete URL for accessing the tickets collection on a local development machine would be: http://localhost:8080/api/tickets

The base path is defined in the main controller for the ticket resource:

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

@RestController
@RequestMapping("/api/tickets") // Defines the base path for all methods in this controller
@RequiredArgsConstructor
@Slf4j
public class TicketController {
    // ... controller methods
}

Port Configuration

The default server port is 8080. This can be overridden by setting the server.port property in the src/main/resources/application.properties file or by providing an environment variable.

# src/main/resources/application.properties
# Example: Change the port to 9090
server.port=9090

REST Conventions

The API adheres to standard RESTful design principles for resource management, including conventional use of HTTP methods and resource-based URL structures.

HTTP Methods Usage

The API uses standard HTTP methods to represent CRUD operations. This provides semantic meaning to requests and allows HTTP-compliant clients and caches to function correctly.

| Method | URI Example | Action - | POST | /api/tickets | Creates a new ticket. Returns 201 CREATED with the new ticket object in the body. - | GET | /api/tickets | Retrieves a collection of tickets. Supports filtering via query parameters. Returns 200 OK. - | GET | /api/tickets/{id} | Retrieves a single ticket by its unique identifier. Returns 200 OK. If not found, a ResourceNotFoundException is thrown, resulting in a 404 NOT FOUND response. - | PUT | /api/tickets/{id} | Updates an existing ticket. This method expects a full representation of the resource for replacement (idempotent). Returns 200 OK with the updated ticket object. - | DELETE | /api/tickets/{id} | Deletes a ticket by its unique identifier. Returns 204 NO CONTENT on successful deletion. -

For a detailed list of all endpoints, their parameters, and example responses, please see the Ticket Endpoints API Reference.

Resource Naming

The API follows the convention of using plural nouns for resource collections.

• Collection URI: /api/tickets refers to the collection of all tickets.
• Individual Resource URI: /api/tickets/{id} refers to a specific ticket, where {id} is the unique identifier.

URL Structure and Filtering

The GET /api/tickets endpoint supports filtering via query parameters.

// 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) {
    // ...
}

• Filter by Status: GET /api/tickets?status=OPEN
• Filter by Requester Email: GET /api/tickets?requesterEmail=john.doe@slalom.com

Developer Note: The current controller implementation for getAllTickets processes these filters in an if-else if chain. This means that only one filter can be applied at a time. If both status and requesterEmail are provided in the query string, only the status filter will be applied. This is a known limitation that may be addressed in a future version.

Content Types

The API exclusively uses the JSON format for request and response bodies.

JSON Request/Response Format

All POST and PUT requests that contain a body must include the Content-Type: application/json header. The server will respond with a 415 Unsupported Media Type status if this header is missing or incorrect.

All responses from the API that contain a body will be sent with a Content-Type: application/json header. Clients should be prepared to parse JSON.

Example POST Request:

### 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@slalom.com",
  "assignedTo": null
}

For detailed specifications of all request and response body structures, please refer to the Request/Response Formats documentation.

Headers Requirements

• Content-Type: application/json: Required for POST and PUT requests.
• Accept: application/json: Recommended for all requests. While the server will default to sending JSON, explicitly setting this header is a best practice for clients to indicate their expected response format.

API Versioning

Proper API versioning is critical for ensuring that changes to the API do not break existing client integrations.

Current API Version

The current version of the API does not use an explicit versioning scheme in the URL path (e.g., /api/v1/tickets). This means all clients are currently using the "latest" version of the API.

Future Versioning Strategy

To accommodate future breaking changes without impacting existing consumers, a versioning strategy must be adopted. The recommended approach is URL Path Versioning.

When a breaking change is necessary, a new version of the API will be introduced under a new versioned path.

• Current (v1): /api/tickets
• Future (v2): /api/v2/tickets

This strategy is clear, explicit, and easy for clients to implement and for routing rules to handle. Non-breaking changes will continue to be added to the current version.

Asynchronous Event Publishing

The API publishes events to RabbitMQ as a side effect of certain operations. This enables event-driven architectures and allows other systems to react to changes in ticket state.

RabbitMQ Events

The application publishes events to the ticket.exchange exchange with routing key ticket.routing.key when:

• A ticket is created (via POST /api/tickets) - Event type: CREATED
• A ticket is updated (via PUT /api/tickets/{id}) - Event type: UPDATED

Clients performing write operations should be aware that these events will be published asynchronously to any configured RabbitMQ broker.

Monitoring and Health Checks

The API includes Spring Boot Actuator endpoints for monitoring application health and metrics.

Health Check Endpoint

GET /actuator/health

This endpoint provides information about the health status of the application and its dependencies. It is useful for load balancers, monitoring systems, and automated health checks.

Response Example:

{
  "status": "UP"
}

Application Info Endpoint

GET /actuator/info

This endpoint exposes arbitrary application information configured in the application properties. It can be used to provide build information, version numbers, or other metadata about the running application.

Additional actuator endpoints may be available depending on the application configuration. Refer to the Spring Boot Actuator documentation for details on other monitoring capabilities.