Skip to main content

Getting Started with MochaJSON

Welcome to MochaJSON v1.0.0! This guide will help you get up and running with the library in just a few minutes, including the stateless library design with no lifecycle management.

Installation​

Gradle​

Add the dependency to your build.gradle.kts file:

dependencies {
    implementation("io.github.mochaapi:MochaJSON:1.0.0")
    
    // Optional: For logging support
    implementation("org.slf4j:slf4j-api:2.0.9")
}

Or if you're using Groovy syntax:

dependencies {
    implementation 'io.github.mochaapi:MochaJSON:1.0.0'
    
    // Optional: For logging support
    implementation 'org.slf4j:slf4j-api:2.0.9'
}

Maven​

Add the dependency to your pom.xml:

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

<!-- Optional: For logging support -->
<dependency>
    <groupId>org.slf4j</groupId>
    <artifactId>slf4j-api</artifactId>
    <version>2.0.9</version>
</dependency>

Your First API Call​

Let's make a simple GET request and parse the JSON response. MochaJSON v1.0.0 is completely stateless - no setup or shutdown required!

Java​

import io.mochaapi.client.*;
import java.time.Duration;
import java.util.Map;
import java.util.concurrent.CompletableFuture;

public class Main {
    public static void main(String[] args) {
        try {
            // Basic usage - Production-safe by default
            Map<String, Object> user = Api.get("https://jsonplaceholder.typicode.com/users/1")
                .execute()
                .toMap();
            
            System.out.println("User Name: " + user.get("name"));
            System.out.println("User Email: " + user.get("email"));
            
            // Advanced usage with v1.0.0 stateless design
            ApiClient client = new ApiClient.Builder()
                .connectTimeout(Duration.ofSeconds(10))
                .readTimeout(Duration.ofSeconds(30))
                .enableRetry()                    // Simple retry with 3 attempts
                .allowLocalhost(true)             // Development-friendly security
                .enableLogging()
                .build();
            
            // Async request with CompletableFuture
            CompletableFuture<ApiResponse> future = client.get("https://jsonplaceholder.typicode.com/posts/1")
                .executeAsync();
            
            ApiResponse response = future.get();
            Map<String, Object> post = response.toMap();
            System.out.println("Post Title: " + post.get("title"));
            
        } catch (ApiException e) {
            System.err.println("API Error: " + e.getMessage());
        } catch (JsonException e) {
            System.err.println("JSON Error: " + e.getMessage());
        } catch (Exception e) {
            System.err.println("Error: " + e.getMessage());
        }
    }
}

Kotlin​

import io.mochaapi.client.*
import java.time.Duration
import java.util.concurrent.CompletableFuture

fun main() {
    try {
        // Basic usage - Production-safe by default
        val user = Api.get("https://jsonplaceholder.typicode.com/users/1")
            .execute()
            .toMap()
        
        println("User Name: ${user["name"]}")
        println("User Email: ${user["email"]}")
        
        // Advanced usage with v1.0.0 stateless design
        val client = ApiClient.Builder()
            .connectTimeout(Duration.ofSeconds(10))
            .readTimeout(Duration.ofSeconds(30))
            .enableRetry()                    // Simple retry with 3 attempts
            .allowLocalhost(true)             // Development-friendly security
            .enableLogging()
            .build()
        
        // Async request
        val future = client.get("https://jsonplaceholder.typicode.com/posts/1")
            .executeAsync()
        
        val response = future.get()
        val post = response.toMap()
        println("Post Title: ${post["title"]}")
        
    } catch (e: ApiException) {
        println("API Error: ${e.message}")
    } catch (e: JsonException) {
        println("JSON Error: ${e.message}")
    } catch (e: Exception) {
        println("Error: ${e.message}")
    }
}

Sample Response​

The API call above returns JSON data that gets automatically parsed:

FieldTypeSample Value
idint1
nameString"Leanne Graham"
emailString"Sincere@april.biz"
usernameString"Bret"
phoneString"1-770-736-8031 x56442"
websiteString"hildegard.org"

Stateless Design Benefits​

MochaJSON v1.0.0 is designed as a pure library with no lifecycle management:

✅ What This Means​

  • No Setup Required - Just import and use
  • No Shutdown Needed - Library manages its own resources
  • No Global State - Each client is completely independent
  • Thread Safe - Multiple clients can be used concurrently
  • Predictable - No hidden side effects or state changes

🔄 Pure Library Design​

MochaJSON v1.0.0 - Pure Library:

// ✅ Just use it - no setup or cleanup
ApiClient client = new ApiClient.Builder()
    .allowLocalhost(true)
    .build();
// Use client - no shutdown needed

🚀 Multiple Independent Clients​

// Each client is completely independent
ApiClient githubClient = new ApiClient.Builder()
    .connectTimeout(Duration.ofSeconds(10))
    .build();

ApiClient internalClient = new ApiClient.Builder()
    .allowLocalhost(true)
    .connectTimeout(Duration.ofSeconds(5))
    .build();

// Use them simultaneously without conflicts
CompletableFuture<ApiResponse> future1 = githubClient.get(url1).executeAsync();
CompletableFuture<ApiResponse> future2 = internalClient.get(url2).executeAsync();

What's Next?​

Now that you have MochaJSON installed and working, explore these guides:

📖 Usage Examples​

🔧 Advanced Features​

✅ Best Practices​

📚 Reference​

Need Help?​