How to use CatwalkAPI

CatwalkAPI Usage Guide

The CatwalkAPI provides a simple and powerful way for addons to make authenticated HTTP requests to external endpoints using the same Bearer authorization that CatWalk uses for its REST API.

Quick Start

1. Import and Setup

import dev.ua.ikeepcalm.catwalk.api.CatwalkAPI;
import dev.ua.ikeepcalm.catwalk.api.ApiResponse;
import dev.ua.ikeepcalm.catwalk.hub.webserver.services.CatWalkWebserverService;

public class MyAddon {
    
    public MyAddon(CatWalkWebserverService webserverService) {
        // Initialize CatwalkAPI with the current Bearer token
        CatwalkAPI.setBearerToken(webserverService.getAuthKey());
    }
}

2. Making HTTP Requests

Simple GET Request

ApiResponse response = CatwalkAPI.sendGet("https://api.example.com/data");

if (response.isSuccess()) {
    String data = response.getBody();
    System.out.println("Received: " + data);
} else {
    System.out.println("Error: " + response.getStatusCode());
}

POST Request with JSON Body

String jsonPayload = "{\"message\":\"Hello World\",\"timestamp\":\"" + System.currentTimeMillis() + "\"}";
ApiResponse response = CatwalkAPI.sendPost("https://api.example.com/messages", jsonPayload);

if (response.isSuccess()) {
    System.out.println("Message sent successfully");
} else {
    System.out.println("Failed to send message: " + response.getStatusCode());
}

Custom Headers

Map<String, String> headers = Map.of(
    "X-Custom-Header", "my-value",
    "Content-Type", "application/json"
);

ApiResponse response = CatwalkAPI.sendGet("https://api.example.com/data", headers);

3. Asynchronous Requests

CompletableFuture<ApiResponse> future = CatwalkAPI.sendGetAsync("https://api.example.com/data");

future.thenAccept(response -> {
    if (response.isSuccess()) {
        System.out.println("Async response received: " + response.getBody());
    }
}).exceptionally(throwable -> {
    System.err.println("Async request failed: " + throwable.getMessage());
    return null;
});

API Methods

Synchronous Methods

• CatwalkAPI.sendGet(String url)
• CatwalkAPI.sendGet(String url, Map<String, String> headers)
• CatwalkAPI.sendPost(String url, String body)
• CatwalkAPI.sendPost(String url, String body, Map<String, String> headers)
• CatwalkAPI.sendPut(String url, String body)
• CatwalkAPI.sendPut(String url, String body, Map<String, String> headers)
• CatwalkAPI.sendDelete(String url)
• CatwalkAPI.sendDelete(String url, Map<String, String> headers)
• CatwalkAPI.sendRequest(String url, String method, String body, Map<String, String> headers)

Asynchronous Methods

• CatwalkAPI.sendGetAsync(String url)
• CatwalkAPI.sendPostAsync(String url, String body)
• CatwalkAPI.sendRequestAsync(String url, String method, String body, Map<String, String> headers)

Token Management

• CatwalkAPI.setBearerToken(String token) - Set the Bearer token
• CatwalkAPI.getBearerToken() - Get the current Bearer token

ApiResponse Class

The ApiResponse class provides comprehensive response information:

ApiResponse response = CatwalkAPI.sendGet("https://api.example.com/data");

// Status code
int statusCode = response.getStatusCode();

// Response body
String body = response.getBody();

// Headers
Map<String, List<String>> allHeaders = response.getHeaders();
String contentType = response.getHeader("Content-Type");

// Convenience methods
boolean success = response.isSuccess();       // 2xx status codes
boolean clientError = response.isClientError(); // 4xx status codes
boolean serverError = response.isServerError(); // 5xx status codes

Complete Example: CatWalk Addon

package com.example.myaddon;

import dev.ua.ikeepcalm.catwalk.api.CatwalkAPI;
import dev.ua.ikeepcalm.catwalk.api.ApiResponse;
import dev.ua.ikeepcalm.catwalk.bridge.annotations.BridgeEventHandler;
import dev.ua.ikeepcalm.catwalk.hub.webserver.services.CatWalkWebserverService;
import io.javalin.http.Context;
import io.javalin.openapi.HttpMethod;
import io.javalin.openapi.OpenApi;

public class MyAddonCatwalk {
    
    public MyAddonCatwalk(CatWalkWebserverService webserverService) {
        // Initialize CatwalkAPI with the server's Bearer token
        CatwalkAPI.setBearerToken(webserverService.getAuthKey());
    }
    
    @OpenApi(
        path = "/myaddon/send-notification",
        methods = HttpMethod.POST,
        summary = "Send notification to external service",
        tags = {"MyAddon"}
    )
    @BridgeEventHandler(
        description = "Send notification to external webhook",
        requiresAuth = true
    )
    public void sendNotification(Context ctx) {
        try {
            // Get notification data from request
            String message = ctx.body();
            
            // Send to external webhook
            ApiResponse response = CatwalkAPI.sendPost(
                "https://hooks.slack.com/services/your/webhook/url",
                "{\"text\":\"" + message + "\"}"
            );
            
            if (response.isSuccess()) {
                ctx.json(Map.of("status", "sent", "statusCode", response.getStatusCode()));
            } else {
                ctx.status(502).json(Map.of(
                    "error", "Failed to send notification", 
                    "statusCode", response.getStatusCode(),
                    "response", response.getBody()
                ));
            }
            
        } catch (Exception e) {
            ctx.status(500).json(Map.of("error", e.getMessage()));
        }
    }
}

Integration with CatWalkWebserverService

When your addon is registered with the CatWalkWebserverService, you can access the current Bearer token:

public class MyAddonCatwalk {
    
    private final CatWalkWebserverService webserverService;
    
    public MyAddonCatwalk(CatWalkWebserverService webserverService) {
        this.webserverService = webserverService;
        
        // Set the Bearer token for all API requests
        CatwalkAPI.setBearerToken(webserverService.getAuthKey());
        
        // Register this addon with the webserver
        webserverService.registerHandlers(this);
    }
}

Error Handling

The CatwalkAPI handles various error conditions gracefully:

• Invalid URLs: Returns ApiResponse with status code -1 and error message
• Network errors: Returns ApiResponse with status code -1 and error message
• Timeouts: Requests timeout after 60 seconds by default
• Interrupted requests: Returns appropriate error response

ApiResponse response = CatwalkAPI.sendGet("https://invalid-url");

if (response.getStatusCode() == -1) {
    System.out.println("Request failed: " + response.getBody());
} else if (!response.isSuccess()) {
    System.out.println("HTTP error " + response.getStatusCode() + ": " + response.getBody());
}

Security Notes

• The Bearer token is automatically included in all requests made through CatwalkAPI
• The token is the same one used for CatWalk's REST API authentication
• Tokens are managed globally per addon instance
• Always validate external API responses before processing them
• Be cautious when making requests to untrusted endpoints

Performance Considerations

• The HTTP client uses connection pooling for better performance
• Asynchronous methods are recommended for non-blocking operations
• Connection timeout is set to 30 seconds, request timeout to 60 seconds
• The HTTP client is shared across all requests for efficiency