migrants-nt-sec/API-DOCS.md

# Person API Documentation

This document provides information about the Person API endpoints and how to use them with Postman.

## API Endpoints

The API follows RESTful conventions and provides the following endpoints:

| Method | Endpoint           | Description                                     |
|--------|--------------------|-------------------------------------------------|
| GET    | /api/persons       | List all persons (with optional search)         |
| POST   | /api/persons       | Create a new person with related entities       |
| GET    | /api/persons/{id}  | Get a specific person with related entities     |
| PUT    | /api/persons/{id}  | Update a person and its related entities        |
| DELETE | /api/persons/{id}  | Delete a person and its related entities        |

## Setup in Postman

1. Create a new Postman collection called "Person API"
2. Set the base URL to your server location (e.g., `http://localhost:8000`)
3. Create requests for each of the endpoints listed above

## Authentication

The API uses Laravel Sanctum for authentication. To set up authentication in Postman:

1. Create a login request if your app includes authentication
2. Save the token from the response
3. For subsequent requests, include the token in the Authorization header:
   - Type: Bearer Token
   - Token: [your-token]

## Request Examples

### List Persons (GET /api/persons)

**Query Parameters:**
- `search`: Optional search term to filter by full_name, surname, or occupation
- `page`: Page number for pagination

**Example Response:**
```json
{
  "success": true,
  "data": {
    "data": [
      {
        "person_id": 1,
        "surname": "Smith",
        "christian_name": "John",
        "full_name": "John Smith",
        "occupation": "Engineer",
        "migration": { ... },
        "naturalization": { ... },
        "residence": { ... },
        "family": { ... },
        "internment": { ... }
      }
    ],
    "meta": {
      "total": 50,
      "count": 10,
      "per_page": 10,
      "current_page": 1,
      "last_page": 5
    },
    "links": {
      "first": "http://localhost:8000/api/persons?page=1",
      "last": "http://localhost:8000/api/persons?page=5",
      "prev": null,
      "next": "http://localhost:8000/api/persons?page=2"
    }
  },
  "message": "Persons retrieved successfully"
}
```

### Create Person (POST /api/persons)

**Headers:**
- Content-Type: application/json

**Request Body Example:**
```json
{
  "surname": "Johnson",
  "christian_name": "Emily",
  "full_name": "Emily Johnson",
  "date_of_birth": "1965-03-15",
  "place_of_birth": "Sydney",
  "occupation": "Teacher",
  "migration": {
    "date_of_arrival_aus": "1980-05-20",
    "date_of_arrival_nt": "1980-06-01",
    "arrival_period": "1980-1990",
    "data_source": "Government Records"
  },
  "naturalization": {
    "date_of_naturalisation": "1990-07-12",
    "no_of_cert": "NAT12345",
    "issued_at": "Darwin"
  },
  "residence": {
    "darwin": true,
    "katherine": false,
    "tennant_creek": false,
    "alice_springs": false,
    "home_at_death": "Darwin"
  },
  "family": {
    "names_of_parents": "Robert Johnson, Mary Johnson",
    "names_of_children": "Sarah, Michael, Thomas"
  },
  "internment": {
    "corps_issued": "Australian Army",
    "interned_in": "Darwin",
    "sent_to": "Melbourne",
    "internee_occupation": "Soldier",
    "internee_address": "123 Main St, Darwin",
    "cav": "CAV12345"
  }
}
```

**Response:**
```json
{
  "success": true,
  "data": {
    "person_id": 2,
    "surname": "Johnson",
    "christian_name": "Emily",
    "full_name": "Emily Johnson",
    "date_of_birth": "1965-03-15",
    "place_of_birth": "Sydney",
    "occupation": "Teacher",
    "migration": { ... },
    "naturalization": { ... },
    "residence": { ... },
    "family": { ... },
    "internment": { ... }
  },
  "message": "Person created successfully"
}
```

### Get Person (GET /api/persons/{id})

**Response:**
```json
{
  "success": true,
  "data": {
    "person_id": 2,
    "surname": "Johnson",
    "christian_name": "Emily",
    "full_name": "Emily Johnson",
    "date_of_birth": "1965-03-15",
    "place_of_birth": "Sydney",
    "occupation": "Teacher",
    "migration": { ... },
    "naturalization": { ... },
    "residence": { ... },
    "family": { ... },
    "internment": { ... }
  },
  "message": "Person retrieved successfully"
}
```

### Update Person (PUT /api/persons/{id})

**Headers:**
- Content-Type: application/json

**Request Body Example:**
```json
{
  "surname": "Johnson-Smith",
  "occupation": "Professor",
  "residence": {
    "darwin": true,
    "katherine": true,
    "home_at_death": "Katherine"
  }
}
```

**Response:**
```json
{
  "success": true,
  "data": {
    "person_id": 2,
    "surname": "Johnson-Smith",
    "christian_name": "Emily",
    "full_name": "Emily Johnson",
    "occupation": "Professor",
    "migration": { ... },
    "naturalization": { ... },
    "residence": {
      "residence_id": 2,
      "darwin": true,
      "katherine": true,
      "tennant_creek": false,
      "alice_springs": false,
      "home_at_death": "Katherine"
    },
    "family": { ... },
    "internment": { ... }
  },
  "message": "Person updated successfully"
}
```

### Delete Person (DELETE /api/persons/{id})

**Response:**
```json
{
  "success": true,
  "message": "Person deleted successfully"
}
```

## Error Handling

All API responses include a `success` flag that indicates whether the request was successful. In case of an error, the response will include a descriptive message:

```json
{
  "success": false,
  "message": "Failed to retrieve person",
  "error": "Person not found"
}
```

## Testing the API

The API includes comprehensive test coverage. You can run the tests using:

```bash
php artisan test --filter=PersonApiTest
```