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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "surname": "Johnson-Smith",
  "occupation": "Professor",
  "residence": {
    "darwin": true,
    "katherine": true,
    "home_at_death": "Katherine"
  }
}

Response:

{
  "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:

{
  "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:

{
  "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:

php artisan test --filter=PersonApiTest