SWAPI (Star Wars API) - Node.js Implementation

A full-stack Star Wars API application built with Node.js, NestJS, React, and TypeScript. This project provides a comprehensive API for managing Star Wars universe data including films, people, planets, species, starships, and vehicles.

🚀 Features

• RESTful API with full CRUD operations for Star Wars entities
• JWT Authentication with role-based access control
• React Frontend with modern UI components
• PostgreSQL Database with TypeORM
• Swagger Documentation for API exploration
• Docker Support for easy deployment
• Comprehensive Testing with Jest
• Multi-language Support (English, Portuguese)

🏗️ Architecture

This is a monorepo containing:

• Server: NestJS backend API (/server)
• Client: React frontend application (/client)
• Docker: Containerization configuration (/docker)

📋 Prerequisites

• Node.js >= 22.14.0
• npm >= 9.0.0
• Docker and Docker Compose (for containerized deployment)
• PostgreSQL (for local development)

🛠️ Installation & Setup

Local Development

1. Clone the repository

   git clone <repository-url>
   cd swapi_njs

2. Install dependencies

   npm install

3. Set up the database

   # Start PostgreSQL with Docker
   npm run docker:db:up

4. Start the application

   # Start both server and client concurrently
   npm start
   
   # Or start them separately
   npm run start:server  # Backend on http://localhost:8080
   npm run start:client  # Frontend on http://localhost:9000

Docker Deployment

1. Build and run with Docker Compose

   # Start the full application stack
   npm run app:up
   
   # Or manually with docker-compose
   docker-compose -f docker/app.yml up --build

2. Access the application

   • API: http://localhost:8080
   • Frontend: http://localhost:8080 (served by backend)
   • Swagger Documentation: http://localhost:8080/api/v2/api-docs

🔧 Development Scripts

Root Level Commands

npm start              # Start both server and client
npm run build          # Build both server and client
npm test               # Run all tests
npm run test:server    # Run server tests only
npm run test:client    # Run client tests only
npm run test:server:e2e # Run end-to-end tests

Server Commands

cd server
npm start              # Start in development mode
npm run start:prod     # Start in production mode
npm run build          # Build the application
npm test               # Run unit tests
npm run test:e2e       # Run end-to-end tests
npm run lint           # Run ESLint
npm run lint:fix       # Fix ESLint issues

Client Commands

cd client
npm start              # Start development server
npm run build          # Build for production
npm test               # Run tests
npm run lint           # Run ESLint

📚 API Endpoints

The API provides comprehensive CRUD operations for Star Wars entities. All endpoints require JWT authentication.

Authentication

• POST /api/authenticate - Login and get JWT token

Core Entities

Films (/api/films)

• GET /api/films - List all films (paginated)
• GET /api/films/:id - Get film by ID
• POST /api/films - Create new film
• PUT /api/films - Update film
• PUT /api/films/:id - Update film by ID
• DELETE /api/films/:id - Delete film

People (/api/people)

• GET /api/people - List all people (paginated)
• GET /api/people/:id - Get person by ID
• POST /api/people - Create new person
• PUT /api/people - Update person
• PUT /api/people/:id - Update person by ID
• DELETE /api/people/:id - Delete person

Planets (/api/planets)

• GET /api/planets - List all planets (paginated)
• GET /api/planets/:id - Get planet by ID
• POST /api/planets - Create new planet
• PUT /api/planets - Update planet
• PUT /api/planets/:id - Update planet by ID
• DELETE /api/planets/:id - Delete planet

Species (/api/species)

• GET /api/species - List all species (paginated)
• GET /api/species/:id - Get species by ID
• POST /api/species - Create new species
• PUT /api/species - Update species
• PUT /api/species/:id - Update species by ID
• DELETE /api/species/:id - Delete species

Starships (/api/starships)

• GET /api/starships - List all starships (paginated)
• GET /api/starships/:id - Get starship by ID
• POST /api/starships - Create new starship
• PUT /api/starships - Update starship
• PUT /api/starships/:id - Update starship by ID
• DELETE /api/starships/:id - Delete starship

Vehicles (/api/vehicles)

• GET /api/vehicles - List all vehicles (paginated)
• GET /api/vehicles/:id - Get vehicle by ID
• POST /api/vehicles - Create new vehicle
• PUT /api/vehicles - Update vehicle
• PUT /api/vehicles/:id - Update vehicle by ID
• DELETE /api/vehicles/:id - Delete vehicle

Query Parameters

All list endpoints support pagination and sorting:

• page - Page number (default: 0)
• size - Page size (default: 20)
• sort - Sort field and direction (e.g., name,ASC or id,DESC)

🔐 Authentication

The API uses JWT (JSON Web Token) authentication:

1. Login: Send POST request to /api/authenticate with username/password
2. Token: Include the returned JWT token in the Authorization header as Bearer <token>
3. Expiration: Tokens are valid for 24 hours by default

Example Authentication Flow

# Login
curl -X POST http://localhost:8080/api/authenticate \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "admin"}'

# Use token in subsequent requests
curl -X GET http://localhost:8080/api/films \
  -H "Authorization: Bearer <your-jwt-token>"

🗄️ Database

PostgreSQL Configuration

• Host: localhost
• Port: 5432
• Database: swapi_api
• Username: swapi_api
• Password: (trust authentication for development)

Database Migrations

cd server
npm run typeorm:migration:run    # Run pending migrations
npm run typeorm:schema:sync      # Sync schema

🧪 Testing

Running Tests

# All tests
npm test

# Server tests only
npm run test:server

# Client tests only
npm run test:client

# End-to-end tests
npm run test:server:e2e

# Test coverage
npm run test:server -- --coverage

Test Structure

• Unit Tests: Located in *.spec.ts files
• E2E Tests: Located in /server/e2e/ directory
• Frontend Tests: Located in /client/src/ with Jest and React Testing Library

📖 API Documentation

Interactive API documentation is available via Swagger UI:

• Swagger UI: http://localhost:8080/api/v2/api-docs
• OpenAPI Spec: Available at the same endpoint

🐳 Docker

Services

• Application: Node.js app with React frontend
• PostgreSQL: Database service
• Health Checks: Built-in health monitoring

Docker Commands

# Start all services
npm run app:up

# Start only database
npm run docker:db:up

# Stop database
npm run docker:db:down

# View logs
docker-compose -f docker/app.yml logs -f

🌍 Environment Configuration

The application supports multiple environments:

• Development (BACKEND_ENV=dev)
• Test (BACKEND_ENV=test)
• Production (BACKEND_ENV=prod)

Configuration files:

• server/src/config/application.yml - Base configuration
• server/src/config/application-{env}.yml - Environment-specific overrides

🔧 Configuration

Key Configuration Properties

• Server Port: 8080
• JWT Secret: Base64 encoded secret (configured in application.yml)
• Token Validity: 24 hours (86400 seconds)
• Database: PostgreSQL with TypeORM
• CORS: Enabled for development

Environment Variables

• BACKEND_ENV - Environment (dev/test/prod)
• NODE_SERVER_PORT - Server port (default: 8080)

🚀 Deployment

Production Deployment

1. Build the application

   npm run build

2. Set production environment

   export BACKEND_ENV=prod

3. Start with Docker

   docker-compose -f docker/app.yml up -d

Manual Production Setup

1. Install Node.js dependencies
2. Build both server and client
3. Configure PostgreSQL database
4. Set environment variables
5. Start the server: npm run start:prod

📁 Project Structure

swapi_njs/
├── client/                 # React frontend
│   ├── src/
│   │   ├── app/           # Main application code
│   │   ├── entities/      # Entity-specific components
│   │   ├── modules/       # Feature modules
│   │   └── shared/        # Shared components
│   └── webpack/           # Webpack configuration
├── server/                 # NestJS backend
│   ├── src/
│   │   ├── domain/        # Database entities
│   │   ├── module/       # Feature modules
│   │   ├── service/      # Business logic
│   │   ├── web/rest/     # REST controllers
│   │   └── security/     # Authentication & authorization
│   └── e2e/              # End-to-end tests
├── docker/                # Docker configurations
└── package.json           # Root package configuration

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the UNLICENSED License.

🆘 Support

For support and questions:

• Check the Swagger documentation at /api/v2/api-docs
• Review the test files for usage examples
• Check the Docker logs for troubleshooting

🔄 Version History

• v0.0.1 - Initial release with basic CRUD operations for all Star Wars entities
• v0.0.0 - Development version

---

Built with ❤️ using NestJS, React, TypeScript, and PostgreSQL