is-it-christmas/specs/001-christmas-checker/contracts/api.md

API Contract: Christmas Checker

Date: 2025-11-11 Feature: Christmas Checker Website Branch: 001-christmas-checker Version: 1.0

Overview

This document defines the REST API contract for the Christmas Checker backend service. The API provides a single endpoint to check if today is Christmas Day.

Base URL: http://localhost:8080 (development), configurable for production

Protocol: HTTP/1.1

Authentication: None (public API)

Content-Type: application/json

Endpoints

GET /api/christmas

Check if today is Christmas (December 25th or 26th).

Description: Returns a boolean indicating whether the current date is Christmas (December 25th or 26th), along with the date that was checked.

Request

Method: GET

URL: /api/christmas

Headers:

• None required

Query Parameters: None

Request Body: None

Example Request:

GET /api/christmas HTTP/1.1
Host: localhost:8080

Response

Success Response:

Status Code: 200 OK

Headers:

• Content-Type: application/json
• Access-Control-Allow-Origin: * (CORS support)

Response Body Schema:

{
  "isChristmas": boolean,
  "date": "YYYY-MM-DD"
}

Fields:

• isChristmas (boolean, required): true if today is December 25th or 26th, false otherwise
• date (string, required): The current date in ISO 8601 format (YYYY-MM-DD)

Example Response (Not Christmas):

HTTP/1.1 200 OK
Content-Type: application/json
Access-Control-Allow-Origin: *

{
  "isChristmas": false,
  "date": "2025-11-11"
}

Example Response (Christmas - Dec 25):

HTTP/1.1 200 OK
Content-Type: application/json
Access-Control-Allow-Origin: *

{
  "isChristmas": true,
  "date": "2025-12-25"
}

Example Response (Christmas - Dec 26):

HTTP/1.1 200 OK
Content-Type: application/json
Access-Control-Allow-Origin: *

{
  "isChristmas": true,
  "date": "2025-12-26"
}

Error Responses

500 Internal Server Error:

Returned when the server cannot determine the current date or encounters an unexpected error.

Status Code: 500 Internal Server Error

Response Body:

{
  "error": "Unable to determine current date",
  "message": "string describing the error"
}

Example:

HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{
  "error": "Unable to determine current date",
  "message": "System clock unavailable"
}

405 Method Not Allowed:

Returned when using any HTTP method other than GET.

Status Code: 405 Method Not Allowed

Allowed Methods: GET

Example:

HTTP/1.1 405 Method Not Allowed
Allow: GET

CORS Policy

Access-Control-Allow-Origin: * (all origins allowed)

Rationale: This is a public API with no sensitive data. Allowing all origins enables the frontend to be hosted on any domain.

Preflight Requests (OPTIONS):

For CORS preflight requests, the server responds with:

HTTP/1.1 204 No Content
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, OPTIONS
Access-Control-Allow-Headers: Content-Type

Response Timing

Expected Response Time: < 100ms (typically < 10ms)

Rationale: Simple date comparison with no I/O operations or external dependencies.

Caching

Cache-Control: no-cache, no-store, must-revalidate

Rationale: The response changes daily at midnight, so aggressive caching would serve stale data. Clients should re-check the date on each page load.

Alternative Strategy: Could cache for up to 1 hour with:

Cache-Control: max-age=3600

But no-cache is safer to ensure users always see current date.

Rate Limiting

Rate Limit: None

Rationale: The endpoint is stateless and computationally trivial. No rate limiting needed for this simple use case.

API Versioning

Version: 1.0 (embedded in this document)

Versioning Strategy: For future changes:

• Non-breaking changes (e.g., adding optional fields): No version change needed
• Breaking changes (e.g., changing response schema): Introduce /v2/api/christmas endpoint

Current Commitment: No breaking changes planned. Schema is stable.

Client Usage Examples

JavaScript (Fetch API)

// Check if it's Christmas
async function checkChristmas() {
  try {
    const response = await fetch('http://localhost:8080/api/christmas');

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    const data = await response.json();

    if (data.isChristmas) {
      console.log("🎄 It's Christmas!");
      // Show snow animation
    } else {
      console.log("☹️  Not Christmas yet...");
      // Show sad smiley
    }

    console.log(`Checked date: ${data.date}`);
  } catch (error) {
    console.error('Failed to check Christmas status:', error);
    // Fall back to client-side date check
  }
}

checkChristmas();

cURL

# Check Christmas status
curl -X GET http://localhost:8080/api/christmas

# Pretty-print JSON response
curl -X GET http://localhost:8080/api/christmas | jq

Java (HttpClient)

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("http://localhost:8080/api/christmas"))
    .GET()
    .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

if (response.statusCode() == 200) {
    // Parse JSON response
    String json = response.body();
    // Use JSON library or manual parsing
}

Testing Contract

Contract Tests

The following tests should verify contract compliance:

1. Response Status: GET /api/christmas returns 200 OK
2. Response Content-Type: Header is application/json
3. Response Schema: Body contains isChristmas (boolean) and date (string)
4. Date Format: date field matches ISO 8601 format (YYYY-MM-DD)
5. Christmas Logic: On December 25th or 26th, isChristmas is true
6. Non-Christmas Logic: On any other date, isChristmas is false
7. CORS Headers: Response includes Access-Control-Allow-Origin: *
8. Method Not Allowed: POST/PUT/DELETE return 405 or appropriate error

Sample Contract Test (Pseudocode)

Test: ChristmasEndpointContract
  Given: Server is running
  When: GET /api/christmas
  Then:
    - Status code is 200
    - Content-Type is application/json
    - Response body has field "isChristmas" (boolean)
    - Response body has field "date" (string matching YYYY-MM-DD)
    - CORS header Access-Control-Allow-Origin is "*"

Test: ChristmasLogicOnChristmasDay
  Given: Server system date is December 25th or 26th
  When: GET /api/christmas
  Then:
    - Response isChristmas is true
    - Response date ends with "-12-25" or "-12-26"

Test: ChristmasLogicOnNonChristmasDay
  Given: Server system date is NOT December 25th or 26th
  When: GET /api/christmas
  Then:
    - Response isChristmas is false
    - Response date does NOT end with "-12-25" or "-12-26"

OpenAPI Specification (Swagger)

openapi: 3.0.3
info:
  title: Christmas Checker API
  description: Check if today is Christmas Day
  version: 1.0.0
servers:
  - url: http://localhost:8080
    description: Development server
paths:
  /api/christmas:
    get:
      summary: Check if today is Christmas
      description: Returns whether the current date is December 25th or 26th
      operationId: checkChristmas
      responses:
        '200':
          description: Successful response
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
                example: "*"
          content:
            application/json:
              schema:
                type: object
                required:
                  - isChristmas
                  - date
                properties:
                  isChristmas:
                    type: boolean
                    description: True if today is December 25th or 26th
                    example: false
                  date:
                    type: string
                    format: date
                    description: Current date in ISO 8601 format
                    example: "2025-11-11"
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: "Unable to determine current date"
                  message:
                    type: string
                    example: "System clock unavailable"

Change Log

Version	Date	Changes
1.0	2025-11-11	Initial API contract definition

Notes

• Client-Side Alternative: Frontend can check the date client-side using JavaScript Date() object, making this API endpoint optional for core functionality
• Timezone Handling: Server uses its local timezone. For production, consider UTC or accepting timezone parameter
• Future Enhancements: Could add query parameter ?tz=America/New_York to check Christmas in specific timezone