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

Akash Bhuiyan — Mon, 12 Jan 2026 15:52:56 +0000

🚀 Build EmbedQA Backend: Professional API Testing Platform

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:

Robust: Handle edge cases, errors gracefully
Scalable: Support thousands of concurrent requests
Maintainable: Clean architecture, SOLID principles
Testable: Comprehensive unit and integration tests
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

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

Database Setup (Alternative)

If you prefer installing PostgreSQL locally:

# Create database and user
psql postgres

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

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

📁 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

🎁 Good First Issues

Perfect entry points for new contributors:

🟢 Beginner-Friendly

Add request timeout configuration
- Make HTTP request timeout configurable
- Skills needed: Java, Spring Boot configuration
- Files: ApiExecutorServiceImpl.java, application.yml
Improve error messages
- Return more descriptive error messages in API responses
- Skills needed: Java, exception handling
- Files: GlobalExceptionHandler.java
Add request/response size limits
- Implement size validation for large payloads
- Skills needed: Java, Spring Boot validation
- Files: ApiExecutorServiceImpl.java

🟡 Intermediate

Implement request history pagination
- Add pagination support for history endpoint
- Skills needed: Spring Data JPA, pagination
- Files: HistoryService.java, HistoryController.java
Add request statistics
- Track average response times, success rates
- Skills needed: JPA queries, aggregation
- Files: HistoryService.java, create StatisticsService.java
Support multipart file uploads
- Handle file uploads in request bodies
- Skills needed: Spring multipart handling
- Files: ApiExecutorServiceImpl.java
WebSocket support
- Add WebSocket testing capabilities
- Skills needed: Spring WebSocket
- Files: Create new WebSocket module

🔴 Advanced

GraphQL support
- Add GraphQL query execution
- Skills needed: GraphQL, HTTP clients
- Files: Create new GraphQL module
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
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

Browse issues and find one that interests you
Comment to claim the issue (we'll assign it to you)
Fork the repository
Create a branch

   git checkout -b feature/your-feature-name

Make your changes with clear commits
Write tests for your changes
Run tests to ensure nothing breaks

   ./mvnw test

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();
}

📚 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"
  }
}

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

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

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

🌟 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

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
);

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}

📖 Resources

Need to brush up on skills?

💬 Join the Community

Questions or ideas? Let's talk!

🐛 Issues: GitHub Issues
💡 Discussions: GitHub Discussions
🔧 Frontend: embedqa-ui repository

🎉 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?

⭐ Star the repository
🍴 Fork it
📖 Read our Contributing Guide
📋 Check Good First Issues
💬 Introduce yourself in Discussions

👨‍💻 About the Maintainer

Akash Bhuiyan - Creator and maintainer of EmbedQA

GitHub: @AkashBhuiyan

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

DEV Community: Akash Bhuiyan