EventosTec API - Technical Documentation

1. Overview

The EventosTec API is a robust backend for event management, designed to support operations for creating, querying, and detailing events, as well as managing associated discount coupons. The API also handles image uploads to AWS S3 and data persistence in a PostgreSQL database, with schema versioning via Flyway.

2. Technologies Used

The platform is built with the following technologies, identified from the pom.xml and the project structure:

• Language: Java 21
• Main Framework: Spring Boot 4.0.3
• Data Access: Spring Data JPA
• Web Server: Spring Web (with embedded Tomcat)
• Database: PostgreSQL
• Migrations: Flyway
• File Storage: AWS SDK for S3
• Utilities: Lombok
• Testing: Spring Boot Starter Test (JUnit 5, Mockito)
• In-Memory Database (Tests): H2 Database

3. Setup and Execution

Prerequisites

1. Java 21 installed.
2. Maven configured.
3. A running instance of PostgreSQL.
4. AWS credentials configured for S3 access.

Local Setup

1. Clone the repository.

2. Configure the src/main/resources/application.properties file with your database and AWS credentials:

   # Spring
   spring.application.name=api
   
   # PostgreSQL DataSource
   spring.datasource.url=jdbc:postgresql://YOUR_HOST:5432/YOUR_DATABASE
   spring.datasource.username=YOUR_USERNAME
   spring.datasource.password=YOUR_PASSWORD
   
   # Flyway
   spring.flyway.enabled=true
   spring.flyway.baseline-on-migrate=true # Useful for the first execution
   
   # AWS S3
   aws.region=YOUR_AWS_REGION # ex: us-east-2
   aws.bucketName=YOUR_S3_BUCKET_NAME
   

Execution

1. Navigate to the root of the project.

2. Execute the Maven command to start the application:

   mvn spring-boot:run
   

3. Flyway will automatically run the migrations on startup, creating the event, address, and coupon tables as defined in src/main/resources/db/migration.

4. API Endpoints

EventController

4.1. Create a New Event

• Endpoint: POST /api/event

• Description: Creates a new event. Data is sent as multipart/form-data to allow for image upload.

• Content-Type: multipart/form-data

• Parameters (form-data):

  • title (String, Required): Event title.
  • description (String, Optional): Detailed description.
  • date (Long, Required): Event date in timestamp format (milliseconds).
  • city (String, Required): City where the event will take place.
  • state (String, Required): State or province abbreviation.
  • remote (Boolean, Required): true if the event is online.
  • eventUrl (String, Required): URL to the event page.
  • image (File, Optional): Image file for the event.

• Response Example (200 OK):

  {
      "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
      "title": "Technology Conference",
      "description": "An event about the latest AI trends.",
      "imgUrl": "https://eventostec-imagens.s3.us-east-2.amazonaws.com/image.png",
      "eventUrl": "https://example.com/event",
      "remote": false,
      "date": 1711152000000,
      "address": {
          "id": "f1e2d3c4-b5a6-7890-1234-567890fedcba",
          "city": "São Paulo",
          "uf": "SP",
          "event": "a1b2c3d4-e5f6-7890-1234-567890abcdef"
      }
  }
  

4.2. List Upcoming Events

• Endpoint: GET /api/event

• Description: Returns a paginated list of events that have not yet occurred.

• Parameters (Query):

  • page (int, Optional, default=0): Page number.
  • size (int, Optional, default=10): Number of events per page.

• Response Example (200 OK):

  [
      {
          "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
          "title": "Technology Conference",
          "description": "An event about the latest AI trends.",
          "date": 1711152000000,
          "city": "São Paulo",
          "state": "SP",
          "remote": false,
          "eventUrl": "https://example.com/event",
          "imageUrl": "https://eventostec-imagens.s3.us-east-2.amazonaws.com/image.png"
      }
  ]
  

4.3. Filter Events

• Endpoint: GET /api/event/filter

• Description: Returns a paginated list of events based on multiple filters.

• Parameters (Query):

  • page (int, Optional, default=0): Page number.
  • size (int, Optional, default=10): Number of events per page.
  • title (String, Optional): Filter by title (partial search).
  • city (String, Optional): Filter by city (partial search).
  • uf (String, Optional): Filter by state abbreviation (partial search).
  • startDate (Date, Optional, format YYYY-MM-DD): Start date of the search period.
  • endDate (Date, Optional, format YYYY-MM-DD): End date of the search period.

• Response Example (200 OK): (Similar to endpoint GET /api/event)

4.4. Get Event Details

• Endpoint: GET /api/event/{eventId}

• Description: Returns the full details of a specific event, including associated discount coupons.

• Parameters (Path):

  • eventId (UUID, Required): Event ID.

• Response Example (200 OK):

  {
      "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
      "title": "Technology Conference",
      "description": "An event about the latest AI trends.",
      "date": 1711152000000,
      "city": "São Paulo",
      "uf": "SP",
      "imgUrl": "https://eventostec-imagens.s3.us-east-2.amazonaws.com/image.png",
      "eventUrl": "https://example.com/event",
      "coupons": [
          {
              "code": "PROMO10",
              "discount": 10,
              "validUntil": 1711065600000
          }
      ]
  }
  

CouponController

4.5. Add Coupon to an Event

• Endpoint: POST /api/coupon/event/{eventId}

• Description: Adds a new discount coupon to an existing event.

• Parameters (Path):

  • eventId (UUID, Required): ID of the event to which the coupon will be associated.

• Request Payload Example (application/json):

  {
      "code": "PROMO20",
      "discount": 20,
      "valid": 1712880000000
  }
  

• Response Example (200 OK):

  {
      "id": "b2c3d4e5-f6a7-8901-2345-67890abcdef1",
      "code": "PROMO20",
      "discount": 20,
      "valid": 1712880000000,
      "event": {
          "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
          "title": "Technology Conference"
      }
  }
  

5. Database Structure

The API uses three main entities out of which relationships are built:

• Event: The central entity. Contains all information about an event, such as title, date, URL, and whether it is remote.

  • Relationship: Has a One-to-One relationship with Address. An event has one address.

• Address: Stores the location information of an in-person event (city and state).

  • Relationship: Has a One-to-One relationship with Event. An address belongs to a single event.

• Coupon: Represents a discount coupon, with a code, discount percentage, and expiration date.

  • Relationship: Has a Many-to-One relationship with Event. Many coupons can belong to a single event.