111 lines
3.0 KiB
Markdown
111 lines
3.0 KiB
Markdown
|
|
# 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.
|
|
```json
|
|
[
|
|
{
|
|
"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:**
|
|
```json
|
|
{
|
|
"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`).
|
|
```json
|
|
{
|
|
"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`.
|
|
```json
|
|
{
|
|
"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:**
|
|
```json
|
|
{
|
|
"error": "Validation failed.",
|
|
"details": {
|
|
"firstName": "First name is required.",
|
|
"linkedinUrl": "A valid URL is required."
|
|
}
|
|
}
|
|
```
|
|
- **Code:** `500 Internal Server Error`
|
|
- **Content:**
|
|
```json
|
|
{
|
|
"error": "Failed to create the person."
|
|
}
|
|
```
|