resumeformatter/frontend/api_spec.md

Profile Linker API Specification

This document outlines the API endpoints required for the Profile Linker application. The API is responsible for managing a list of people's profiles.

Base URL

The API endpoints are relative to a base URL, e.g., https://api.example.com.

Authentication

All API endpoints could be protected by an authentication mechanism (e.g., OAuth 2.0, API Key in header), which is not detailed in this specification. For this example, we assume endpoints are publicly accessible.

Data Models

Person Object

Represents a single person's profile.

Field	Type	Description	Example
id	string	Unique identifier for the person	"a1b2c3d4-e5f6-7890-1234-567890abcdef"
firstName	string	The person's first name	"Jane"
lastName	string	The person's last name	"Doe"
linkedinUrl	string	Full URL to the person's LinkedIn profile	"https://www.linkedin.com/in/janedoe"

---

Endpoints

1. Get All People

Retrieves a list of all people in the database.

• URL: /api/people
• Method: GET
• Success Response:
  • Code: 200 OK
  • Content: An array of Person objects.

  [
    {
      "id": "1",
      "firstName": "Ada",
      "lastName": "Lovelace",
      "linkedinUrl": "https://www.linkedin.com/in/ada-lovelace"
    },
    {
      "id": "2",
      "firstName": "Grace",
      "lastName": "Hopper",
      "linkedinUrl": "https://www.linkedin.com/in/grace-hopper"
    }
  ]
  

• Error Response:
  • Code: 500 Internal Server Error
  • Content:

  {
    "error": "An unexpected error occurred."
  }
  

---

2. Add a New Person

Creates a new person record in the database.

• URL: /api/people
• Method: POST
• Request Body: A JSON object containing the new person's details (excluding the id).

  {
    "firstName": "Margaret",
    "lastName": "Hamilton",
    "linkedinUrl": "https://www.linkedin.com/in/margaret-hamilton"
  }
  

• Success Response:
  • Code: 201 Created
  • Content: The newly created Person object, including its server-generated id.

  {
    "id": "3",
    "firstName": "Margaret",
    "lastName": "Hamilton",
    "linkedinUrl": "https://www.linkedin.com/in/margaret-hamilton"
  }
  

• Error Responses:
  • Code: 400 Bad Request (e.g., for missing fields or invalid data)
  • Content:

  {
    "error": "Validation failed.",
    "details": {
      "firstName": "First name is required.",
      "linkedinUrl": "A valid URL is required."
    }
  }
  

  • Code: 500 Internal Server Error
  • Content:

  {
    "error": "Failed to create the person."
  }