Skip to main content

​
Introduction

The Adoptme API is a RESTful service for managing pet adoptions, built with Express.js and MongoDB. This API allows you to manage users, pets, adoptions, and authentication sessions.

​
Base URLs

http://localhost:8080
The default development port is 8080, but can be configured via the PORT environment variable.

​
Authentication

The API uses cookie-based JWT authentication for protected endpoints.

​
How it works:

  1. Register or Login via /api/sessions/register or /api/sessions/login
  2. Receive a JWT token stored in a cookie named coderCookie
  3. The cookie is automatically sent with subsequent requests
  4. Token expires after 1 hour

​
Authentication Flow

// 1. Login
POST /api/sessions/login
Body: { "email": "[email protected]", "password": "mypassword" }

// Response sets cookie: coderCookie=<jwt_token>
// Cookie maxAge: 3600000ms (1 hour)

// 2. Access protected endpoints
GET /api/sessions/current
// Cookie is automatically included
The JWT secret is currently hardcoded as tokenSecretJWT in the source code. In production, this should be moved to environment variables.

​
Request Format

All requests must use JSON format with the appropriate Content-Type header. 
curl -X POST http://localhost:8080/api/sessions/login \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"password123"}'

​
Response Format

All API responses follow a consistent JSON structure:

​
Success Response

{
  "status": "success",
  "payload": { /* response data */ }
}

​
Error Response

{
  "status": "error",
  "error": "Error message description"
}

​
HTTP Status Codes

The API uses standard HTTP status codes:
CodeDescriptionCommon Usage
200OKSuccessful GET, PUT, DELETE requests
201CreatedSuccessful POST requests (resource created)
400Bad RequestMissing required fields, validation errors
404Not FoundResource doesn’t exist
500Internal Server ErrorServer-side errors

​
Error Handling

All controllers implement try-catch blocks with consistent error responses: 
try {
  // Controller logic
  res.send({status:"success", payload: data})
} catch (error) {
  res.status(500).send("Ha ocurrido un error en la petición, por favor ver detalle: ", error)
}

​
Common Error Patterns

​
Rate Limiting

Currently, there is no rate limiting implemented in the API. This should be added for production use.

​
API Resources

The API provides the following resource endpoints:

​
Users

Manage user accounts, profiles, and pet ownership.

​
Pets

Manage pets available for adoption, including image uploads.

​
Adoptions

Create and manage adoption records linking users to pets.

​
Sessions

Authentication endpoints for registration, login, and session management.

​
Mocks

Generate mock data for testing purposes.

​
Interactive API Documentation

The API includes Swagger UI documentation at: 
http://localhost:8080/docs
The Swagger documentation is generated from OpenAPI 3.0.0 specifications defined in src/docs/documentacion.yaml.

​
Swagger Configuration

const options = {
  definition: {
    openapi: "3.0.0",
    info: {
      title: "Adoptme",
      version: "1.0.0",
      description: "Documentación proyecto Adoptme"
    }
  },
  apis: ["./src/docs/*.yaml"]
}

​
Database

The API uses MongoDB with Mongoose ODM:
  • Default Connection: mongodb://127.0.0.1:27017
  • Database Name: adoptme
  • Configurable via: MONGO_URL and DB_NAME environment variables

​
Collections

  • Users - User accounts and authentication
  • Pets - Pet records and adoption status
  • Adoptions - Adoption records linking users to pets

​
Quick Start Example

# 1. Register a new user
curl -X POST http://localhost:8080/api/sessions/register \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "John",
    "last_name": "Doe",
    "email": "[email protected]",
    "password": "securepassword"
  }'

# 2. Login
curl -X POST http://localhost:8080/api/sessions/login \
  -H "Content-Type: application/json" \
  -c cookies.txt \
  -d '{"email":"[email protected]","password":"securepassword"}'

# 3. Get current user (using saved cookies)
curl -X GET http://localhost:8080/api/sessions/current \
  -b cookies.txt

# 4. List all pets
curl -X GET http://localhost:8080/api/pets

# 5. Create an adoption (user adopts pet)
curl -X POST http://localhost:8080/api/adoptions/<user_id>/<pet_id> \
  -b cookies.txt

​
Next Steps

Users API

Manage user accounts and profiles

Pets API

Manage pets and image uploads

Adoptions API

Create and track adoptions

Sessions API

Authentication and session management

Build docs developers (and LLMs) love

Get started for freeTalk to us