Family Tree API Documentation

📋 Table of Contents

Overview
Authentication
Users API
Persons API
Connections API
Images & Media
Code Examples

📖 Overview

The Family Tree API provides comprehensive endpoints for managing family tree data, including persons, relationships, images, and authentication. The API supports both MySQL database storage and JSON file fallback.

Base URL

http://localhost:3008/api

Response Format

All responses are in JSON format. Successful responses include the requested data, while errors include an error field with a descriptive message.

Authentication

Most endpoints require authentication via JWT token in the Authorization header: Authorization: Bearer <token>

🔐 Authentication

POST /auth/register

Request Body

Field	Type	Required	Description
full_name	string	Yes	Full name (First M Last)
password	string	Yes	User password (min 6 characters)
email	string	Yes	Unique email address

Response (201)

{
  "id": "uuid",
  "username": "John William Doe",
  "email": "john@example.com",
  "created_at": "2024-01-01T00:00:00.000Z"
}

POST /auth/login

Authenticate user and get JWT token

Request Body

Field	Type	Required	Description
email	string	Yes	Email address
password	string	Yes	Password

Response (200)

{
  "token": "jwt_token_here",
  "user": {
    "id": "uuid",
    "username": "John William Doe",
    "email": "john@example.com"
  }
}

👤 Users API

GET /users

Get all users (admin only)

Response (200)

[
  {
    "id": "uuid",
    "username": "johndoe",
    "email": "john@example.com",
    "can_write": false,
    "created_at": "2024-01-01T00:00:00.000Z"
  }
]

GET /me

Get current user details

Response (200)

{
  "user": {
    "id": "uuid",
    "username": "johndoe",
    "email": "john@example.com",
    "can_write": false
  }
}

PUT /users/:id

Update user details (admin only)

Path Parameters

Parameter	Type	Description
id	string	User UUID

Request Body

Field	Type	Description
can_write	boolean	Write permissions

DELETE /users/:id

Delete user (admin only, cannot delete admin)

POST /auth/change-password

Change user password

Request Body

Field	Type	Required	Description
currentPassword	string	Yes	Current password
newPassword	string	Yes	New password

👥 Persons API

GET /persons

Get all persons in the family tree

Response (200)

[
  {
    "id": "uuid",
    "first": "John",
    "middle": "William",
    "last": "Doe",
    "birth": {
      "date": "01/15/1980",
      "place": "New York, NY"
    },
    "death": null,
    "burial": null,
    "residence": {
      "address": "123 Main St",
      "city": "Anytown",
      "state": "CA",
      "zip": "12345"
    },
    "img": ["image1.jpg", "image2.jpg"],
    "hasMarried": true
  }
]

GET /persons/:id

Get detailed information for a specific person

Path Parameters

Parameter	Type	Description
id	string	Person UUID

POST /persons

Create a new person

Request Body (Form Data)

Field	Type	Description
first	string	First name
middle	string	Middle name
last	string	Last name
birth_date	string	Birth date (MM/DD/YYYY)
birth_place	string	Birth place
death_date	string	Death date (MM/DD/YYYY)
death_place	string	Death place
burial_date	string	Burial date (MM/DD/YYYY)
burial_place	string	Burial place
residence_address	string	Residence address
residence_city	string	Residence city
residence_state	string	Residence state
residence_zip	string	Residence ZIP code
avatar	file	Profile avatar image
images	file[]	Additional images (up to 20)

PUT /persons/:id

Update an existing person

Same parameters as POST, all fields optional for partial updates

DELETE /persons/:id

Delete a person and all associated data

DELETE /persons/:id/image

Delete a specific image from a person

Query Parameters

Parameter	Type	Description
imagePath	string	Path to the image file to delete

GET /persons/person/:id

Get basic person information (legacy endpoint)

GET /persons/parents/:id

Get all parents of a person

Path Parameters

Parameter	Type	Description
id	string	Person UUID

Response (200)

[
  {
    "id": "parent-uuid",
    "first": "John",
    "middle": "William",
    "last": "Doe",
    "name": "John William Doe",
    "birth": {
      "date": "01/15/1950",
      "place": "New York, NY"
    },
    "death": null,
    "created_at": "2024-01-01T00:00:00.000Z"
  }
]

GET /persons/children/:id

Get all children of a person

Path Parameters

Parameter	Type	Description
id	string	Person UUID

Response (200)

[
  {
    "id": "child-uuid",
    "first": "Jane",
    "middle": null,
    "last": "Doe",
    "name": "Jane Doe",
    "birth": {
      "date": "01/15/1980",
      "place": "New York, NY"
    },
    "death": null,
    "created_at": "2024-01-01T00:00:00.000Z"
  }
]

GET /persons/grandchildren/:id

Get all grandchildren of a person

GET /persons/grandparents/:id

Get all grandparents of a person

GET /persons/tree/:id

Get complete family tree starting from a person

Response (200)

{
  "id": "uuid",
  "first": "John",
  "last": "Doe",
  "birth": { "date": "01/15/1980" },
  "children": [
    {
      "id": "child-uuid",
      "first": "Jane",
      "last": "Doe",
      "birth": { "date": "01/15/2005" },
      "children": []
    }
  ],
  "partners": [],
  "siblings": [],
  "parents": []
}

🔗 Connections API

GET /connections

Get all connections or connections for a specific person

Query Parameters

Parameter	Type	Description
personId	string	Optional: Get connections for specific person

Response (200)

[
  {
    "id": "uuid",
    "from_person_id": "person1-uuid",
    "to_person_id": "person2-uuid",
    "connection_type": "partner",
    "created_at": "2024-01-01T00:00:00.000Z"
  }
]

POST /connections

Create a new connection between persons

Request Body

Field	Type	Required	Description
fromId	string	Yes	Source person ID
toId	string	Yes	Target person ID
type	string	Yes	Connection type (partner, parent, child, etc.)

DELETE /connections/:id

Delete a connection

Path Parameters

Parameter	Type	Description
id	string	Connection UUID

🖼️ Images & Media

Image Upload

Images are automatically processed when creating or updating persons:

Avatar: Main profile image, resized to multiple sizes
Images: Additional photos, up to 20 per person
Processing: Images are stored in /public/assets/img/ with original and small versions

Image Access

Uploaded images are accessible at:

http://localhost:3008/assets/img/original/filename.jpg
http://localhost:3008/assets/img/small/filename.jpg

Supported Formats

JPG, PNG, GIF, WebP (automatically converted to JPG for consistency)

💻 Code Examples

JavaScript (Frontend)

// Login
const login = async (username, password) => {
  const response = await fetch('/api/auth/login', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ username, password })
  });
  const data = await response.json();
  localStorage.setItem('token', data.token);
  return data;
};

// Get all persons
const getPersons = async () => {
  const token = localStorage.getItem('token');
  const response = await fetch('/api/persons', {
    headers: { 'Authorization': `Bearer ${token}` }
  });
  return await response.json();
};

// Create new person
const createPerson = async (personData) => {
  const token = localStorage.getItem('token');
  const formData = new FormData();

  // Add text fields
  Object.keys(personData).forEach(key => {
    if (personData[key]) formData.append(key, personData[key]);
  });

  // Add images
  if (personData.avatar) formData.append('avatar', personData.avatar);
  if (personData.images) {
    personData.images.forEach(img => formData.append('images', img));
  }

  const response = await fetch('/api/persons', {
    method: 'POST',
    headers: { 'Authorization': `Bearer ${token}` },
    body: formData
  });
  return await response.json();
};

cURL Examples

# Login
curl -X POST http://localhost:3008/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"johndoe","password":"password123"}'

# Get all persons
curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  http://localhost:3008/api/persons

# Create person
curl -X POST http://localhost:3008/api/persons \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -F "first=John" \
  -F "last=Doe" \
  -F "birth_date=01/15/1980" \
  -F "avatar=@profile.jpg"

Python (Requests)

import requests

# Login
response = requests.post('http://localhost:3008/api/auth/login', json={
    'username': 'johndoe',
    'password': 'password123'
})
token = response.json()['token']

# Get persons
headers = {'Authorization': f'Bearer {token}'}
persons = requests.get('http://localhost:3008/api/persons', headers=headers).json()

# Create person
files = {'avatar': open('profile.jpg', 'rb')}
data = {
    'first': 'John',
    'last': 'Doe',
    'birth_date': '01/15/1980'
}
response = requests.post('http://localhost:3008/api/persons',
                        headers=headers, data=data, files=files)

📊 Status Codes

200 - OK 201 - Created 400 - Bad Request 401 - Unauthorized 404 - Not Found 409 - Conflict 500 - Internal Server Error