endpoints.md

Portfolio API Documentation

This document provides detailed information about the Portfolio API endpoints, including request and response examples.

Table of Contents

• Authentication
  • Login
  • Register
  • Get Profile
• Projects
  • Get All Projects
  • Get Project by ID
  • Create Project
  • Update Project
  • Delete Project
• Contacts
  • Submit Contact Form
  • Get All Contacts
  • Get Contact by ID
  • Mark Contact as Read
  • Delete Contact
• Health Check
  • Get Health Status

Authentication

Login

Authenticates a user and returns a JWT token.

URL: /api/v1/auth/login

Method: POST

Authentication: None

Request Body:

{
  "email": "user@example.com",
  "password": "password123"
}

Success Response:

• Code: 200 OK
• Content:

{
  "status": "success",
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expires_at": "2023-12-31T23:59:59.999Z",
    "user": {
      "id": 1,
      "username": "user",
      "email": "user@example.com"
    }
  }
}

Error Response:

• Code: 400 Bad Request
• Content:

{
  "status": "error",
  "error": {
    "code": "AUTHENTICATION_ERROR",
    "message": "User not found"
  }
}

OR

• Code: 401 Unauthorized
• Content:

{
  "status": "error",
  "error": {
    "code": "AUTHENTICATION_ERROR",
    "message": "Password does not match"
  }
}

Register

Register a new user.

URL: /api/v1/auth/register

Method: POST

Authentication: None

Request Body:

{
  "username": "newuser",
  "email": "newuser@example.com",
  "password": "password123"
}

Success Response:

• Code: 200 OK
• Content:

{
  "status": "success",
  "data": {
    "id": 2,
    "username": "newuser",
    "email": "newuser@example.com",
    "created_at": "2023-01-01T12:00:00.000Z",
    "updated_at": "2023-01-01T12:00:00.000Z"
  }
}

Error Response:

• Code: 400 Bad Request
• Content:

{
  "status": "error",
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Email already exists"
  }
}

Get Profile

Returns the authenticated user's profile.

URL: /api/v1/auth/profile

Method: GET

Authentication: Required (Bearer Token)

Success Response:

• Code: 200 OK
• Content:

{
  "status": "success",
  "data": {
    "user": {
      "id": 1,
      "username": "user",
      "email": "user@example.com",
      "created_at": "2023-01-01T12:00:00.000Z",
      "updated_at": "2023-01-01T12:00:00.000Z"
    }
  }
}

Error Response:

• Code: 401 Unauthorized
• Content:

{
  "status": "error",
  "error": {
    "code": "AUTHENTICATION_ERROR",
    "message": "Unauthorized"
  }
}

Projects

Get All Projects

Returns a paginated list of projects.

URL: /api/v1/projects

Method: GET

Authentication: Required (Bearer Token)

Query Parameters:

• page (optional): Page number (default: 1)
• per_page (optional): Items per page (default: 10)
• search (optional): Search term
• is_featured (optional): Filter by featured projects (true/false)

Success Response:

• Code: 200 OK
• Content:

{
  "status": "success",
  "data": [
    {
      "id": 1,
      "title": "Project 1",
      "description": "Description of project 1",
      "is_featured": true,
      "created_at": "2023-01-01T12:00:00.000Z",
      "updated_at": "2023-01-01T12:00:00.000Z"
    },
    {
      "id": 2,
      "title": "Project 2",
      "description": "Description of project 2",
      "is_featured": false,
      "created_at": "2023-01-02T12:00:00.000Z",
      "updated_at": "2023-01-02T12:00:00.000Z"
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "limit": 10,
      "totalItems": 2,
      "totalPages": 1
    }
  }
}

Error Response:

• Code: 401 Unauthorized
• Content:

{
  "status": "error",
  "error": {
    "code": "AUTHENTICATION_ERROR",
    "message": "Unauthorized"
  }
}

Get Project by ID

Returns a specific project by ID.

URL: /api/v1/projects/:id

Method: GET

Authentication: Required (Bearer Token)

URL Parameters:

• id: Project ID

Success Response:

• Code: 200 OK
• Content:

{
  "status": "success",
  "data": {
    "id": 1,
    "title": "Project 1",
    "description": "Description of project 1",
    "is_featured": true,
    "created_at": "2023-01-01T12:00:00.000Z",
    "updated_at": "2023-01-01T12:00:00.000Z"
  }
}

Error Response:

• Code: 404 Not Found
• Content:

{
  "status": "error",
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Project not found"
  }
}

Create Project

Create a new project.

URL: /api/v1/projects

Method: POST

Authentication: Required (Bearer Token)

Request Body:

{
  "title": "New Project",
  "description": "Description of new project",
  "is_featured": false
}

Success Response:

• Code: 201 Created
• Content:

{
  "status": "success",
  "data": {
    "id": 3,
    "title": "New Project",
    "description": "Description of new project",
    "is_featured": false,
    "created_at": "2023-01-03T12:00:00.000Z",
    "updated_at": "2023-01-03T12:00:00.000Z"
  }
}

Error Response:

• Code: 422 Unprocessable Entity
• Content:

{
  "status": "error",
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": {
      "title": ["title must not be empty"]
    }
  }
}

Update Project

Updates an existing project.

URL: /api/v1/projects/:id

Method: PATCH

Authentication: Required (Bearer Token)

URL Parameters:

• id: Project ID

Request Body:

{
  "title": "Updated Project",
  "is_featured": true
}

Success Response:

• Code: 200 OK
• Content:

{
  "status": "success",
  "data": {
    "id": 1,
    "title": "Updated Project",
    "description": "Description of project 1",
    "is_featured": true,
    "created_at": "2023-01-01T12:00:00.000Z",
    "updated_at": "2023-01-03T12:00:00.000Z"
  }
}

Error Response:

• Code: 404 Not Found
• Content:

{
  "status": "error",
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Project not found"
  }
}

Delete Project

Delete a project.

URL: /api/v1/projects/:id

Method: DELETE

Authentication: Required (Bearer Token)

URL Parameters:

• id: Project ID

Success Response:

• Code: 200 OK
• Content:

{
  "status": "success",
  "data": {
    "message": "Project deleted successfully"
  }
}

Error Response:

• Code: 404 Not Found
• Content:

{
  "status": "error",
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Project not found"
  }
}

Contacts

The Contacts API allows users to submit contact forms and administrators to manage contact submissions.

Submit Contact Form

Submit a new contact form. This endpoint is public and does not require authentication.

URL: /api/v1/contacts

Method: POST

Authentication: None (Public endpoint)

Request Body:

{
  "name": "John Doe",
  "email": "john.doe@example.com",
  "message": "Hello, I would like to get in touch regarding a potential collaboration opportunity.",
  "subject": "Project Inquiry"
}

Field Validation:

• name: Required, string, 2-100 characters
• email: Required, valid email address
• message: Required, string, 10-1000 characters
• subject: Optional, string, max 200 characters

Success Response:

• Code: 201 Created
• Content:

{
  "status": "success",
  "data": {
    "id": 1,
    "name": "John Doe",
    "email": "john.doe@example.com",
    "message": "Hello, I would like to get in touch regarding a potential collaboration opportunity.",
    "subject": "Project Inquiry",
    "isRead": false,
    "readAt": null,
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T10:30:00.000Z"
  },
  "meta": {}
}

Error Response:

• Code: 422 Unprocessable Entity
• Content:

{
  "status": "error",
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": {
      "email": ["email must be an email"],
      "message": ["message must be longer than or equal to 10 characters"]
    }
  }
}

Get All Contacts

Returns a paginated list of all contact submissions. This endpoint requires authentication and is intended for administrators.

URL: /api/v1/contacts

Method: GET

Authentication: Required (Bearer Token)

Query Parameters:

• page (optional): Page number (default: 1)
• per_page (optional): Items per page (default: 10)
• search (optional): Search term (searches in name, email, and message)
• is_read (optional): Filter by read status (true/false)

Success Response:

• Code: 200 OK
• Content:

{
  "status": "success",
  "data": [
    {
      "id": 1,
      "name": "John Doe",
      "email": "john.doe@example.com",
      "message": "Hello, I would like to get in touch...",
      "subject": "Project Inquiry",
      "isRead": false,
      "readAt": null,
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z"
    },
    {
      "id": 2,
      "name": "Jane Smith",
      "email": "jane.smith@example.com",
      "message": "Interested in your services...",
      "subject": null,
      "isRead": true,
      "readAt": "2024-01-15T11:00:00.000Z",
      "createdAt": "2024-01-15T09:00:00.000Z",
      "updatedAt": "2024-01-15T11:00:00.000Z"
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "limit": 10,
      "totalItems": 2,
      "totalPages": 1
    }
  }
}

Error Response:

• Code: 401 Unauthorized
• Content:

{
  "status": "error",
  "error": {
    "code": "AUTHENTICATION_ERROR",
    "message": "Unauthorized"
  }
}

Get Contact by ID

Returns a specific contact submission by ID. This endpoint requires authentication and is intended for administrators.

URL: /api/v1/contacts/:id

Method: GET

Authentication: Required (Bearer Token)

URL Parameters:

• id: Contact ID (integer)

Success Response:

• Code: 200 OK
• Content:

{
  "status": "success",
  "data": {
    "id": 1,
    "name": "John Doe",
    "email": "john.doe@example.com",
    "message": "Hello, I would like to get in touch regarding a potential collaboration opportunity.",
    "subject": "Project Inquiry",
    "isRead": false,
    "readAt": null,
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T10:30:00.000Z"
  },
  "meta": {}
}

Error Response:

• Code: 404 Not Found
• Content:

{
  "status": "error",
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Contact with ID 1 not found"
  }
}

OR

• Code: 401 Unauthorized
• Content:

{
  "status": "error",
  "error": {
    "code": "AUTHENTICATION_ERROR",
    "message": "Unauthorized"
  }
}

Mark Contact as Read

Marks a contact submission as read. This endpoint requires authentication and is intended for administrators.

URL: /api/v1/contacts/:id/read

Method: PATCH

Authentication: Required (Bearer Token)

URL Parameters:

• id: Contact ID (integer)

Success Response:

• Code: 200 OK
• Content:

{
  "status": "success",
  "data": {
    "id": 1,
    "name": "John Doe",
    "email": "john.doe@example.com",
    "message": "Hello, I would like to get in touch...",
    "subject": "Project Inquiry",
    "isRead": true,
    "readAt": "2024-01-15T12:00:00.000Z",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T12:00:00.000Z"
  },
  "meta": {}
}

Error Response:

• Code: 404 Not Found
• Content:

{
  "status": "error",
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Contact with ID 1 not found"
  }
}

OR

• Code: 401 Unauthorized
• Content:

{
  "status": "error",
  "error": {
    "code": "AUTHENTICATION_ERROR",
    "message": "Unauthorized"
  }
}

Delete Contact

Deletes a contact submission. This endpoint requires authentication and is intended for administrators.

URL: /api/v1/contacts/:id

Method: DELETE

Authentication: Required (Bearer Token)

URL Parameters:

• id: Contact ID (integer)

Success Response:

• Code: 200 OK
• Content:

{
  "status": "success",
  "data": {
    "message": "Contact successfully deleted"
  },
  "meta": {}
}

Error Response:

• Code: 404 Not Found
• Content:

{
  "status": "error",
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Contact with ID 1 not found"
  }
}

OR

• Code: 401 Unauthorized
• Content:

{
  "status": "error",
  "error": {
    "code": "AUTHENTICATION_ERROR",
    "message": "Unauthorized"
  }
}

Health Check

Get Health Status

Returns the health status of the API.

URL: /health

Method: GET

Authentication: None

Success Response:

• Code: 200 OK
• Content:

{
  "status": "ok",
  "info": {
    "nestjs-docs": {
      "status": "up"
    },
    "storage": {
      "status": "up"
    }
  },
  "error": {},
  "details": {
    "nestjs-docs": {
      "status": "up"
    },
    "storage": {
      "status": "up"
    }
  }
}

Error Response:

• Code: 503 Service Unavailable
• Content:

{
  "status": "error",
  "info": {},
  "error": {
    "nestjs-docs": {
      "status": "down",
      "message": "Could not connect to https://docs.nestjs.com"
    }
  },
  "details": {
    "nestjs-docs": {
      "status": "down",
      "message": "Could not connect to https://docs.nestjs.com"
    },
    "storage": {
      "status": "up"
    }
  }
}