Skip to content

API Documentation Guide

This guide provides instructions for creating and maintaining REST API documentation for the TQPro platform.

Document Structure

Each API specification file should follow this standard structure:

# [Module Name] API Specification

## Overview
[Brief description of the API module]

**Base Path:** `/path`

**Content Types:**
- Request: `application/json`
- Response: `application/json`

## Response Format
[Standard response wrapper description]

## Endpoints
[Endpoint documentation]

## Data Models
[Entity definitions]

Overview Section

Start with a clear overview describing the API module's purpose:

## Overview
The Booking API provides endpoints for managing travel bookings, including
creation, retrieval, updates, and cancellations.

**Base Path:** `/booking`

**Content Types:**
- Request: `application/json`
- Response: `application/json`

Response Format Section

All TQPro APIs return responses wrapped in TlinqApiResponse. Document this once at the top:

## Response Format
All endpoints return a `TlinqApiResponse` object:
```json
{
  "apiStatus": {
    "errorCode": "OK",
    "errorMessage": "Success"
  },
  "apiData": { ... }
}

Date Format: All dates are returned in ISO 8601 format (yyyy-MM-dd'T'HH:mm:ss) 

### Error Response Format

Document error responses when applicable:

```markdown
**Error Response:**
```json
{
  "apiStatus": {
    "errorCode": "BOOKING_NOT_FOUND",
    "errorMessage": "Booking with ID 12345 not found"
  },
  "apiData": null
}

---

## Endpoint Documentation

### Endpoint Header

Use a level 3 heading with HTTP method and path:

```markdown
### POST /booking/create
Creates a new booking.

Request Body Table

Document request parameters in a table:

**Request Body:**
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| customerId | integer | Yes | Customer ID for the booking |
| productId | integer | Yes | Product being booked |
| travelDate | string | Yes | Travel date (yyyy-MM-dd) |
| adults | integer | Yes | Number of adult travelers |
| children | integer | No | Number of child travelers (default: 0) |
| notes | string | No | Special requests or notes |

Query Parameters

For GET endpoints with query parameters:

**Query Parameters:**
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| id | integer | Yes | Booking ID to retrieve |
| session | string | No | User session token |

Request Example

Provide a realistic JSON request example:

**Request Example:**
```json
{
  "customerId": 1001,
  "productId": 5001,
  "travelDate": "2025-08-15",
  "adults": 2,
  "children": 1,
  "notes": "Vegetarian meals preferred"
}

### Response Structure

Show the complete response including the wrapper:

```markdown
**Response Structure:**
```json
{
  "apiStatus": { "errorCode": "OK", "errorMessage": "Success" },
  "apiData": {
    "bookingId": 10001,
    "bookingReference": "TQ-2025-10001",
    "customerId": 1001,
    "customerName": "John Smith",
    "productId": 5001,
    "productName": "Desert Safari Adventure",
    "travelDate": "2025-08-15",
    "adults": 2,
    "children": 1,
    "status": "CONFIRMED",
    "totalAmount": 450.00,
    "currency": "AED",
    "createdAt": "2025-06-15T10:30:00",
    "notes": "Vegetarian meals preferred"
  }
}

---

## Response Patterns

### Single Entity Response

For endpoints returning a single entity:

```json
{
  "apiStatus": { "errorCode": "OK", "errorMessage": "Success" },
  "apiData": {
    "entityId": 1001,
    "fieldName": "value",
    ...
  }
}

List Response

For endpoints returning collections:

{
  "apiStatus": { "errorCode": "OK", "errorMessage": "Success" },
  "apiData": [
    {
      "entityId": 1001,
      "fieldName": "value"
    },
    {
      "entityId": 1002,
      "fieldName": "value"
    }
  ]
}

Nested Entity Response

For entities with child collections:

{
  "apiStatus": { "errorCode": "OK", "errorMessage": "Success" },
  "apiData": {
    "parentId": 1001,
    "parentName": "Parent Entity",
    "children": [
      {
        "childId": 2001,
        "childName": "Child 1"
      },
      {
        "childId": 2002,
        "childName": "Child 2"
      }
    ]
  }
}

Empty/Null Response

For operations with no return data:

{
  "apiStatus": { "errorCode": "OK", "errorMessage": "Success" },
  "apiData": null
}

Data Models Section

Document all entities used by the API at the end of the file:

## Data Models

### CBooking
| Field | Type | Description |
|-------|------|-------------|
| bookingId | integer | Unique booking identifier |
| bookingReference | string | Human-readable booking reference |
| customerId | integer | Customer ID |
| customerName | string | Customer full name |
| productId | integer | Product ID |
| productName | string | Product name |
| travelDate | date | Scheduled travel date |
| adults | integer | Number of adult travelers |
| children | integer | Number of child travelers |
| infants | integer | Number of infant travelers |
| status | string | Booking status (PENDING, CONFIRMED, CANCELLED) |
| totalAmount | decimal | Total booking amount |
| currency | string | Currency code (ISO 4217) |
| createdAt | datetime | Creation timestamp |
| updatedAt | datetime | Last update timestamp |

Enum Values

Document enum fields with allowed values:

**Status Values:**
| Value | Description |
|-------|-------------|
| PENDING | Booking created but not confirmed |
| CONFIRMED | Booking confirmed and paid |
| CANCELLED | Booking cancelled |
| COMPLETED | Travel completed |

Standard Error Codes

Document module-specific error codes:

## Error Codes

| Code | Description |
|------|-------------|
| OK | Operation successful |
| BOOKING_NOT_FOUND | Booking ID does not exist |
| CUSTOMER_NOT_FOUND | Customer ID does not exist |
| PRODUCT_UNAVAILABLE | Product not available for selected date |
| INVALID_DATE | Travel date is in the past or invalid format |
| CAPACITY_EXCEEDED | Not enough availability for requested travelers |

Best Practices

Naming Conventions

  1. Endpoint paths: Use lowercase with hyphens for multi-word paths
  2. Good: /cruise/price-template/list

  3. Avoid: /cruise/priceTemplate/list

  4. Field names: Use camelCase for JSON fields

  5. Good: customerId, travelDate, createdAt

  6. Avoid: customer_id, travel_date

  7. Entity class names: Use C prefix for canonical entities

  8. Example: CBooking, CCustomer, CProduct

Date and Time Formats

  • Date only: yyyy-MM-dd (e.g., 2025-08-15)
  • DateTime: yyyy-MM-dd'T'HH:mm:ss (e.g., 2025-08-15T10:30:00)
  • Always document the expected format in parameter descriptions

Currency and Money

  • Use decimal type for monetary amounts
  • Always include a separate currency field with ISO 4217 code
  • Example: "totalAmount": 450.00, "currency": "AED"

IDs and References

  • Use integer for internal database IDs
  • Use string for human-readable reference codes
  • Example: "bookingId": 10001, "bookingReference": "TQ-2025-10001"

File Naming Convention

API specification files should follow this naming pattern:

API-Spec-<ModuleName>.md

Examples: - API-Spec-Booking.md - API-Spec-Customer.md - API-Spec-TripMaker.md

Checklist for New API Documentation

When creating a new API specification file:

  • [ ] Add Overview section with base path and content types
  • [ ] Add Response Format section with TlinqApiResponse structure
  • [ ] Add Date Format note (ISO 8601)
  • [ ] Document each endpoint with:
  • [ ] HTTP method and path
  • [ ] Brief description
  • [ ] Request body/query parameters table
  • [ ] JSON request example
  • [ ] JSON response structure
  • [ ] Add Error Codes section if module has specific errors
  • [ ] Add Data Models section with all entities
  • [ ] Include enum value tables where applicable
  • [ ] Use realistic sample data in examples
  • [ ] Update API-Specification.md index to include new module

Example: Complete Endpoint Documentation

### POST /booking/create
Creates a new booking for a customer.

**Request Body:**
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| customerId | integer | Yes | Customer ID for the booking |
| productId | integer | Yes | Product being booked |
| travelDate | string | Yes | Travel date (yyyy-MM-dd) |
| adults | integer | Yes | Number of adult travelers |
| children | integer | No | Number of child travelers (default: 0) |
| pickupLocation | string | No | Pickup location for transfers |
| notes | string | No | Special requests or notes |

**Request Example:**
```json
{
  "customerId": 1001,
  "productId": 5001,
  "travelDate": "2025-08-15",
  "adults": 2,
  "children": 1,
  "pickupLocation": "Dubai Marina Hotel",
  "notes": "Vegetarian meals preferred"
}

Response Structure: 

{
  "apiStatus": { "errorCode": "OK", "errorMessage": "Success" },
  "apiData": {
    "bookingId": 10001,
    "bookingReference": "TQ-2025-10001",
    "customerId": 1001,
    "customerName": "John Smith",
    "productId": 5001,
    "productName": "Desert Safari Adventure",
    "travelDate": "2025-08-15",
    "adults": 2,
    "children": 1,
    "infants": 0,
    "status": "CONFIRMED",
    "pickupLocation": "Dubai Marina Hotel",
    "pickupTime": "14:30",
    "totalAmount": 450.00,
    "currency": "AED",
    "createdAt": "2025-06-15T10:30:00",
    "notes": "Vegetarian meals preferred"
  }
}

Error Codes: | Code | Description | |------|-------------| | CUSTOMER_NOT_FOUND | Customer ID does not exist | | PRODUCT_UNAVAILABLE | Product not available for selected date | | INVALID_DATE | Travel date is in the past | ```

Reference

For examples of well-documented APIs, see: - API-Spec-Booking.md - Booking management - API-Spec-Cruise.md - Cruise operations with complex nested entities - API-Spec-TripMaker.md - Trip planning with multiple related entities