DEV Community

Akash Bhuiyan
Akash Bhuiyan

Posted on

Building EmbedQA: An Open Source API Testing Tool with Spring Boot 🚀

#springboot #java #opensource #api

🚀 Build EmbedQA Backend: Professional API Testing Platform

EmbedQA GitHub Repository

Hey backend developers! 👋

Are you passionate about Java, Spring Boot, and building robust APIs? Want to contribute to an open-source project that helps developers worldwide test their APIs better? Join us in building EmbedQA - a modern, open-source API testing platform (think Postman alternative)!

🎯 What is EmbedQA?

EmbedQA is a full-stack API testing platform designed to give developers a powerful, free alternative to commercial API testing tools. The backend is the heart of this platform, handling everything from executing HTTP requests to managing collections, environments, and request history.

What We're Building:

  • 🔧 HTTP request execution engine with full protocol support
  • 📦 Collections management for organizing API endpoints
  • 🌍 Environment variables system for different deployment stages
  • 📝 Request history with analytics
  • 🔐 Multiple authentication mechanisms
  • 🚀 High-performance, scalable REST API

🛠️ Tech Stack

We're using industry-standard, modern Java technologies:

Technology Version Purpose
Java 21 Latest LTS with modern features
Spring Boot 3.5.7 Robust, production-ready framework
Spring Data JPA - Simplified database operations
PostgreSQL 16 Reliable, powerful relational database
Apache HttpClient 5.3 HTTP request execution
Maven 3.9+ Dependency management
Docker - Easy database setup & deployment

Why This Stack?

  • Java 21: Modern syntax, Records, Pattern Matching, Virtual Threads
  • Spring Boot 3.5: Production-proven, extensive ecosystem
  • PostgreSQL: Advanced features, JSON support, excellent performance
  • Apache HttpClient 5: Industry-standard HTTP client library

🎯 Project Goals

We're building EmbedQA backend to be:

  1. Robust: Handle edge cases, errors gracefully
  2. Scalable: Support thousands of concurrent requests
  3. Maintainable: Clean architecture, SOLID principles
  4. Testable: Comprehensive unit and integration tests
  5. Well-documented: Clear API docs with Swagger/OpenAPI

🚀 Getting Started

Ready to contribute? Here's how to get the backend running locally:

Prerequisites

  • Java 21 (JDK)
  • Maven 3.9+
  • PostgreSQL 16 (we recommend Docker)
  • Your favorite IDE (IntelliJ IDEA, Eclipse, VS Code)

Quick Setup 

# 1. Fork and clone the repository
git clone https://github.com/YOUR_USERNAME/embedqa.git
cd embedqa

# 2. Start PostgreSQL with Docker (easiest way)
cd docker-compose/db
docker-compose up -d
cd ../..

# 3. Run the application
./mvnw spring-boot:run
Enter fullscreen mode Exit fullscreen mode

The API will be available at http://localhost:8085 🎉

Database Setup (Alternative)

If you prefer installing PostgreSQL locally:

# Create database and user
psql postgres
Enter fullscreen mode Exit fullscreen mode 
CREATE DATABASE embedqa;
CREATE USER embedqa_user WITH ENCRYPTED PASSWORD 'embedqa_pass';
GRANT ALL PRIVILEGES ON DATABASE embedqa TO embedqa_user;
\c embedqa
GRANT ALL ON SCHEMA public TO embedqa_user;
\q
Enter fullscreen mode Exit fullscreen mode

Verify Installation 

# Check if the API is running
curl http://localhost:8085/api/v1/collections

# View API documentation
open http://localhost:8085/swagger-ui.html
Enter fullscreen mode Exit fullscreen mode

📁 Project Architecture

We follow clean architecture principles with clear separation of concerns:

src/main/java/com/akash/embedqa/
├── EmbedqaApplication.java         # Main application entry point
├── config/                         # Configuration classes
│   ├── HttpClientConfig.java       # Apache HttpClient setup
│   └── WebConfig.java              # CORS, interceptors
├── controller/                     # REST API endpoints
│   ├── ApiExecutorController.java  # Execute HTTP requests
│   ├── CollectionController.java   # Collections CRUD
│   ├── EnvironmentController.java  # Environments CRUD
│   ├── RequestController.java      # Saved requests CRUD
│   └── HistoryController.java      # Request history
├── service/                        # Business logic layer
│   ├── ApiExecutorService.java     # HTTP execution logic
│   ├── CollectionService.java      # Collections management
│   ├── EnvironmentService.java     # Environment management
│   ├── RequestService.java         # Request management
│   └── HistoryService.java         # History tracking
├── repository/                     # Data access layer
│   ├── ApiCollectionRepository.java
│   ├── ApiRequestRepository.java
│   ├── ApiResponseRepository.java
│   ├── EnvironmentRepository.java
│   ├── EnvironmentVariableRepository.java
│   └── RequestHistoryRepository.java
├── model/                          # Domain models
│   ├── entities/                   # JPA entities
│   │   ├── ApiCollection.java
│   │   ├── ApiRequest.java
│   │   ├── ApiResponse.java
│   │   ├── Environment.java
│   │   ├── EnvironmentVariable.java
│   │   └── RequestHistory.java
│   └── dtos/                       # Data Transfer Objects
│       ├── request/                # Request DTOs
│       └── response/               # Response DTOs
├── enums/                          # Enumerations
│   ├── HttpMethod.java             # HTTP methods
│   ├── BodyType.java               # Request body types
│   └── AuthType.java               # Authentication types
├── exception/                      # Exception handling
│   ├── GlobalExceptionHandler.java # Centralized error handling
│   ├── ApiExecutionException.java
│   └── ResourceNotFoundException.java
├── converter/                      # Type converters
│   ├── AuthConfigConverter.java    # JPA converters
│   └── EnvironmentVariablesConverter.java
└── utils/                          # Utility classes
    └── HashMapConverter.java
Enter fullscreen mode Exit fullscreen mode

🎁 Good First Issues

Perfect entry points for new contributors:

🟢 Beginner-Friendly

  1. Add request timeout configuration

    • Make HTTP request timeout configurable
    • Skills needed: Java, Spring Boot configuration
    • Files: ApiExecutorServiceImpl.java, application.yml

  2. Improve error messages

    • Return more descriptive error messages in API responses
    • Skills needed: Java, exception handling
    • Files: GlobalExceptionHandler.java

  3. Add request/response size limits

    • Implement size validation for large payloads
    • Skills needed: Java, Spring Boot validation
    • Files: ApiExecutorServiceImpl.java

🟡 Intermediate

  1. Implement request history pagination

    • Add pagination support for history endpoint
    • Skills needed: Spring Data JPA, pagination
    • Files: HistoryService.java, HistoryController.java

  2. Add request statistics

    • Track average response times, success rates
    • Skills needed: JPA queries, aggregation
    • Files: HistoryService.java, create StatisticsService.java

  3. Support multipart file uploads

    • Handle file uploads in request bodies
    • Skills needed: Spring multipart handling
    • Files: ApiExecutorServiceImpl.java

  4. WebSocket support

    • Add WebSocket testing capabilities
    • Skills needed: Spring WebSocket
    • Files: Create new WebSocket module

🔴 Advanced

  1. GraphQL support

    • Add GraphQL query execution
    • Skills needed: GraphQL, HTTP clients
    • Files: Create new GraphQL module

  2. Request chaining engine

    • Extract values from one response to use in next request
    • Skills needed: Complex logic, JSON parsing
    • Files: ApiExecutorService.java, create chaining logic

  3. Mock server

    • Built-in mock API server for testing
    • Skills needed: Advanced Spring, dynamic routing
    • Files: Create new mock server module

🤝 Contribution Guidelines

We make contributing easy and rewarding!

How to Contribute

  1. Browse issues and find one that interests you
  2. Comment to claim the issue (we'll assign it to you)
  3. Fork the repository
  4. Create a branch 
   git checkout -b feature/your-feature-name
Enter fullscreen mode Exit fullscreen mode
  1. Make your changes with clear commits
  2. Write tests for your changes
  3. Run tests to ensure nothing breaks 
   ./mvnw test
Enter fullscreen mode Exit fullscreen mode
  1. Submit a PR with a detailed description

Code Style Guidelines

  • Follow Java naming conventions (camelCase, PascalCase)
  • Use meaningful variable/method names
  • Write Javadoc for public methods
  • Keep methods short and focused (< 30 lines ideally)
  • Follow SOLID principles
  • Use Spring best practices (constructor injection, etc.)
  • Write unit tests for services, integration tests for controllers

Testing Requirements 

// Example service test
@Test
void shouldExecuteGetRequest() {
    // Given
    ExecuteRequestDTO request = createTestRequest();

    // When
    ApiResponseDTO response = apiExecutorService.execute(request);

    // Then
    assertThat(response.getStatusCode()).isEqualTo(200);
    assertThat(response.getBody()).isNotNull();
}
Enter fullscreen mode Exit fullscreen mode

📚 API Endpoints Overview

Execute API Request 

POST /api/v1/execute
Content-Type: application/json

{
  "method": "GET",
  "url": "https://api.example.com/users",
  "headers": [
    {"key": "Authorization", "value": "Bearer token", "enabled": true}
  ],
  "queryParams": [
    {"key": "page", "value": "1", "enabled": true}
  ],
  "body": null,
  "bodyType": "NONE",
  "authType": "BEARER_TOKEN",
  "authConfig": {
    "token": "your-token-here"
  }
}
Enter fullscreen mode Exit fullscreen mode

Collections Management 

GET    /api/v1/collections          # List all collections
GET    /api/v1/collections/{id}     # Get collection by ID
POST   /api/v1/collections          # Create collection
PUT    /api/v1/collections/{id}     # Update collection
DELETE /api/v1/collections/{id}     # Delete collection
Enter fullscreen mode Exit fullscreen mode

Environment Management 

GET    /api/v1/environments         # List all environments
POST   /api/v1/environments         # Create environment
PUT    /api/v1/environments/{id}    # Update environment
DELETE /api/v1/environments/{id}    # Delete environment
Enter fullscreen mode Exit fullscreen mode

Request History 

GET    /api/v1/history              # Get request history
GET    /api/v1/history/{id}         # Get history item details
DELETE /api/v1/history/{id}         # Delete history item
GET    /api/v1/history/stats        # Get usage statistics
Enter fullscreen mode Exit fullscreen mode

🌟 Why Contribute to EmbedQA Backend?

For Your Career

  • Build production-grade Spring Boot applications
  • Learn clean architecture and best practices
  • Work with modern Java 21 features
  • Gain experience with real-world scenarios

For Learning

  • Master Spring Boot 3.x ecosystem
  • Practice RESTful API design
  • Learn database optimization with JPA
  • Understand HTTP protocol deeply
  • Write professional-grade tests

For the Community

  • Help developers worldwide test APIs efficiently
  • Build a free alternative to expensive tools
  • Contribute to open-source Java ecosystem
  • Mentor other developers

🧪 Development Workflow

Running Tests 

# Run all tests
./mvnw test

# Run specific test class
./mvnw test -Dtest=ApiExecutorServiceTest

# Run with coverage
./mvnw test jacoco:report
Enter fullscreen mode Exit fullscreen mode

Database Migrations

We use Flyway for database migrations:

-- Example migration: V1__Create_collections_table.sql
CREATE TABLE collections (
    id BIGSERIAL PRIMARY KEY,
    name VARCHAR(255) NOT NULL,
    description TEXT,
    created_at TIMESTAMP NOT NULL,
    updated_at TIMESTAMP
);
Enter fullscreen mode Exit fullscreen mode

Configuration Profiles 

# application-dev.yml (Development)
spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/embedqa
    username: embedqa_user
    password: embedqa_pass

# application-prod.yml (Production)
spring:
  datasource:
    url: ${DATABASE_URL}
    username: ${DATABASE_USERNAME}
    password: ${DATABASE_PASSWORD}
Enter fullscreen mode Exit fullscreen mode

📖 Resources

Need to brush up on skills?

💬 Join the Community

Questions or ideas? Let's talk!

🎉 What We've Built So Far

  • ✅ HTTP request execution engine (all methods)
  • ✅ Authentication support (Bearer, Basic, API Key)
  • ✅ Collections CRUD operations
  • ✅ Environment management
  • ✅ Request history tracking
  • ✅ PostgreSQL database schema
  • ✅ Comprehensive error handling
  • ✅ Docker development environment

Coming Soon:

  • 🔜 Request chaining
  • 🔜 WebSocket support
  • 🔜 GraphQL support
  • 🔜 Mock server
  • 🔜 Advanced analytics

🚀 Ready to Start?

  1. ⭐ Star the repository
  2. 🍴 Fork it
  3. 📖 Read our Contributing Guide
  4. 📋 Check Good First Issues
  5. 💬 Introduce yourself in Discussions

👨‍💻 About the Maintainer

Akash Bhuiyan - Creator and maintainer of EmbedQA

Let's build the future of API testing together! Whether you're a Java veteran or learning Spring Boot, there's a place for you on the EmbedQA team. We value every contribution, from documentation improvements to major features. 🎉

Have questions? Drop a comment below or open a discussion on GitHub!

🔖 Tags

#java #springboot #opensource #backend #postgresql #rest #api #hacktoberfest

java #springboot #opensource #api #webdev #programming #tutorial

Top comments (0)