Skip to content

README.md

Latest commit

 

History

History
314 lines (243 loc) · 9.12 KB

README.md

File metadata and controls

314 lines (243 loc) · 9.12 KB

MochaJSON

Maven Central Build Status MIT License Java Kotlin GitHub Sponsors

Production-ready HTTP + JSON client for Java 21+ and Kotlin

A pure, stateless library that eliminates boilerplate while providing automatic JSON parsing, virtual threads support, and production-safe defaults.

Quick Start

// Installation
implementation("io.github.mochaapi:MochaJSON:1.0.0")

// Usage - that's it!
Map<String, Object> data = Api.get("https://api.example.com/users/1")
    .execute()
    .toMap();

Why MochaJSON?

Problem Statement:

  • Tired of OkHttp + Gson boilerplate?
  • Need simple HTTP requests without framework overhead?
  • Want production-ready stability guarantees?

Solution:

  • One import, zero configuration
  • Automatic JSON parsing
  • Production-safe defaults
  • API stability guarantees

Key Features

  • ✅ Zero Boilerplate - One line API calls
  • ✅ Production Ready - Stability guarantees for 1.x.x
  • ✅ Pure Library - No lifecycle management
  • ✅ Java 21+ & Kotlin - Full support for both
  • ✅ Virtual Threads - Built-in async support
  • ✅ Type Safe - Automatic POJO mapping
  • ✅ Interceptors - Request/Response hooks
  • ✅ Retry Logic - Exponential backoff
  • ✅ Security - URL validation, localhost control
  • ✅ Lightweight - Minimal dependencies

Installation

Gradle (Kotlin DSL):

dependencies {
    implementation("io.github.mochaapi:MochaJSON:1.0.0")
}

Gradle (Groovy):

dependencies {
    implementation 'io.github.mochaapi:MochaJSON:1.0.0'
}

Maven:

<dependency>
    <groupId>io.github.mochaapi</groupId>
    <artifactId>MochaJSON</artifactId>
    <version>1.0.0</version>
</dependency>

Getting Started

Java Example:

import io.mochaapi.client.*;

public class QuickStart {
    public static void main(String[] args) {
        // Simple GET request
        Map<String, Object> user = Api.get("https://jsonplaceholder.typicode.com/users/1")
                           .execute()
            .toMap();
        
        System.out.println("Name: " + user.get("name"));
        
        // POST request with body
        ApiResponse response = Api.post("https://jsonplaceholder.typicode.com/posts")
            .body(Map.of("title", "Hello", "body", "World", "userId", 1))
            .execute();
        
        System.out.println("Status: " + response.code());
    }
}

Kotlin Example:

import io.mochaapi.client.*

fun main() {
    // Simple GET request
    val user = Api.get("https://jsonplaceholder.typicode.com/users/1")
        .execute()
        .toMap()
    
    println("Name: ${user["name"]}")
    
    // POST with data class
    data class Post(val title: String, val body: String, val userId: Int)
    
    val response = Api.post("https://jsonplaceholder.typicode.com/posts")
        .body(Post("Hello", "World", 1))
        .execute()
    
    println("Status: ${response.code()}")
}

Chainable JSON Access:

import io.mochaapi.client.*;

// Clean nested JSON access without casting
String city = Api.get("https://api.example.com/user/123")
    .execute()
    .toJsonMap()
    .get("data").get("location").get("city").toString();

Core Capabilities

Production-Ready Features:

Stateless Design

// No initialization required
// No shutdown needed
// Each client is independent
ApiClient client1 = new ApiClient.Builder().build();
ApiClient client2 = new ApiClient.Builder().build();
// Use them independently - no conflicts!

Type-Safe POJOs

public class User {
    public int id;
    public String name;
    public String email;
}

User user = Api.get("https://api.example.com/users/1")
    .execute()
    .to(User.class);

Async Operations

// CompletableFuture
CompletableFuture<ApiResponse> future = Api.get(url).executeAsync();

// Callbacks
Api.get(url).executeAsync(response -> {
    System.out.println("Got: " + response.code());
    });

Advanced Configuration

ApiClient client = new ApiClient.Builder()
    .connectTimeout(Duration.ofSeconds(10))
    .readTimeout(Duration.ofSeconds(30))
    .enableRetry()  // 3 attempts with exponential backoff
    .allowLocalhost(true)  // For development
    .requestInterceptor(req -> {
        req.header("Authorization", "Bearer " + token);
        return req;
    })
    .build();

Documentation

💖 Sponsor This Project

MochaJSON is open source and free to use. If it helps your project, consider sponsoring to support ongoing development and maintenance.

Why Sponsor?

  • ✅ Ensure long-term maintenance and updates
  • ✅ Priority support for issues and feature requests
  • ✅ Influence roadmap and feature priorities
  • ✅ Recognition in README and documentation
  • ✅ Support open source software

Become a Sponsor on GitHub Sponsors

Other Ways to Support:

  • ⭐ Star the repository
  • 🐛 Report bugs and suggest features
  • 📝 Contribute code or documentation
  • 💬 Share on social media
  • 📢 Write a blog post or tutorial

🏢 Corporate Sponsorship

For enterprise support, custom features, or bulk licensing, contact us at:

Comparison with Alternatives

Feature MochaJSON OkHttp + Gson Retrofit
Setup Lines 1 20+ 30+
Dependencies 1 3+ 4+
JSON Parsing Automatic Manual Converter setup
Kotlin Support Native Limited Requires setup
Virtual Threads ✅ Built-in ❌ Manual ❌ Manual
Stateless ✅ Yes ⚠️ Shared ⚠️ Shared
Retry Logic ✅ Built-in ❌ Manual ❌ Manual
API Stability ✅ Guaranteed ⚠️ Breaking changes ⚠️ Breaking changes

Requirements

  • Java: 21+ (LTS recommended)
  • Kotlin: 1.9.22+ (optional, for Kotlin projects)
  • Dependencies: Minimal
    • Jackson 2.17.2 (JSON for Java)
    • Kotlinx Serialization 1.7.2 (JSON for Kotlin)
    • SLF4J 2.0.9 (optional logging)

API Stability Guarantee

MochaJSON v1.0.0 provides strict API stability guarantees:

✅ No breaking changes in 1.x.x releases ✅ Semantic versioning strictly followed ✅ Deprecation warnings 6+ months before removal ✅ Long-term support commitment

Community & Contributing

Get Involved:

Code of Conduct: We follow the Contributor Covenant to ensure a welcoming community.

License

MochaJSON is released under the MIT License.

MIT License - Free to use, modify, and distribute
✅ Commercial use allowed
✅ Modification allowed
✅ Distribution allowed
✅ Private use allowed

Acknowledgments

Built With:

  • Java 21 Virtual Threads
  • Jackson for JSON processing
  • Kotlinx Serialization for Kotlin
  • Love for clean, simple APIs

Inspired By:

  • The need for simpler HTTP clients
  • Community feedback and requests
  • Production use cases and requirements

Contact & Support

Need Help?

Follow Updates:

  • 🌟 Star on GitHub
  • 👀 Watch repository for releases
  • 📢 Follow @MochaAPI (if available)

Made with ❤️ by the MochaAPI Team

Star ⭐ this repository if you find it useful!

Star History

Star History Chart