Skip to content

CLAUDE.md

Latest commit

 

History

History
236 lines (169 loc) · 7.97 KB

CLAUDE.md

File metadata and controls

236 lines (169 loc) · 7.97 KB
Raw

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is the Rootly Java SDK - an auto-generated Java client library for the Rootly API v1. The codebase is generated using OpenAPI Generator 7.13.0 from the Rootly OpenAPI specification.

Key characteristics:

  • Auto-generated code using the okhttp-gson library template
  • Java 1.8+ compatibility
  • Uses OkHttp for HTTP client operations
  • Uses Gson for JSON serialization/deserialization
  • Follows JSON:API specification (application/vnd.api+json media type)

Build System

The project supports both Maven and Gradle:

Gradle Commands (Primary)

# Run tests
./gradlew test

# Build the project
./gradlew build

# Clean build
./gradlew clean build

# Format code (auto-format with Google Java Format)
./gradlew spotlessApply

# Check code formatting
./gradlew spotlessCheck

# Publish to local Maven repository
./gradlew publishToMavenLocal

Maven Commands

# Install to local repository
mvn clean install

# Run tests
mvn test

# Build without tests
mvn clean package -DskipTests

# Format code
mvn spotless:apply

# Check code formatting
mvn spotless:check

Code Generation

The SDK is auto-generated from the Rootly OpenAPI specification. To regenerate the code:

# Using Docker (recommended - default)
make build

# Using local openapi-generator (requires Java + openapi-generator installed)
make build-local

Docker-based generation (default):

  • Uses openapitools/openapi-generator-cli:v7.13.0 Docker image
  • No local Java installation required
  • Ensures consistent builds across all environments
  • Automatically downloads the OpenAPI spec and generates code

The generation process:

  1. Fetches the OpenAPI spec from https://rootly-heroku.s3.amazonaws.com/swagger/v1/swagger.json
  2. Generates Java code using OpenAPI Generator v7.13.0
  3. Removes problematic Object.validateJsonElement calls via sed

Protected files: These files are protected from regeneration via .openapi-generator-ignore:

  • build.gradle - Custom Gradle configuration
  • pom.xml - Custom Maven configuration
  • LICENSE - MIT license
  • README.md - User-friendly documentation
  • CLAUDE.md - This file
  • PUBLISHING.md - Publishing documentation
  • CHANGELOG.md - Version history
  • .github/dependabot.yml - Dependency management

Architecture

Package Structure

  • com.rootly.client - Core client infrastructure

    • ApiClient - Main HTTP client wrapper (OkHttp-based)
    • Configuration - Global configuration singleton
    • JSON - Gson-based JSON serialization/deserialization
    • auth/ - Authentication implementations (Bearer, Basic, API Key)

  • com.rootly.client.api - Generated API endpoint classes

    • Each API class corresponds to a resource (e.g., IncidentsApi, AlertsApi)
    • All API classes follow the same pattern with synchronous and async methods

  • com.rootly.client.model - Generated data models

    • POJOs with Gson annotations
    • Represents JSON:API request/response structures

Authentication

The SDK uses Bearer token authentication. Set up authentication:

ApiClient client = Configuration.getDefaultApiClient();
client.setBasePath("https://api.rootly.com");
HttpBearerAuth bearerAuth = (HttpBearerAuth) client.getAuthentication("bearerAuth");
bearerAuth.setBearerToken("YOUR-API-KEY");

API Usage Pattern

All API endpoints follow a consistent pattern:

// Initialize API client
IncidentsApi apiInstance = new IncidentsApi(client);

// Make API calls
IncidentList result = apiInstance.listIncidents(pageSize, pageNumber, ...filters);

JSON:API Specification

The Rootly API follows JSON:API specification:

  • Content-Type: application/vnd.api+json
  • Structured responses with data, attributes, relationships
  • Pagination via page[number] and page[size] query parameters
  • Rate limiting: ~3000 requests per 60-second sliding window per API key

Code Formatting

The project uses Spotless with Google Java Format (AOSP style):

  • Automatic import ordering
  • Unused import removal
  • Reflows long strings
  • Apply formatting before committing changes

Testing

  • Tests use JUnit 5 (Jupiter)
  • Test framework: Mockito for mocking
  • Tests are auto-generated but can be extended
  • Run individual test class: ./gradlew test --tests "com.rootly.client.model.IncidentTest"

CI/CD

GitHub Actions workflows:

  • test.yml - Runs tests on all branches using JDK 17
  • maven.yml - Maven-based build pipeline
  • publish.yml - Publishes artifacts to Maven Central and GitHub Packages, then publishes the most recent Release Drafter draft under the pushed tag (triggered on tag push)

Publishing & Releases

See PUBLISHING.md for detailed instructions on publishing releases to Maven Central and GitHub Packages.

Release Process

The release process uses Makefile targets to automate version bumping and tagging:

# Check current version
make version

# Bump version (updates pom.xml and build.gradle, creates tag)
make bump-patch   # 0.0.1 -> 0.0.2
make bump-minor   # 0.0.1 -> 0.1.0
make bump-major   # 0.0.1 -> 1.0.0

# Push the tag to trigger automated workflows
make push-tag

Review the Release Drafter draft and its OpenAPI diff before tagging. Label merged pull requests breaking for major versions and enhancement for minor versions. The tag publishes the most recent draft regardless of its current tag, renames it to the pushed tag, and prepends the annotated tag message under “Highlights”. For custom highlights, use an annotated tag such as git tag -a vX.Y.Z -m "<highlights>".

Automated workflow (triggered by make push-tag):

  1. make bump-patch (or minor/major) - Updates version in both pom.xml and build.gradle, commits, and creates tag locally
  2. make push-tag - Pushes the tag to GitHub, which automatically triggers publish.yml:
    • Runs tests
    • Signs artifacts with GPG
    • Publishes to Maven Central
    • Publishes to GitHub Packages
    • Publishes the most recent Release Drafter draft, renamed to the pushed tag, with the annotated tag message under “Highlights”; or creates a release with GitHub-generated notes if no draft exists (only if all publishing succeeds)

One-command releases:

# These combine bump + push-tag (fully automated!)
make release-patch   # Bump patch and push tag → triggers publish + release
make release-minor   # Bump minor and push tag → triggers publish + release
make release-major   # Bump major and push tag → triggers publish + release

What happens automatically:

  • Runs all tests
  • Signs artifacts with GPG
  • Deploys to Maven Central Portal (auto-publishes)
  • Deploys to GitHub Packages
  • Publishes the most recent Release Drafter draft, renamed to the pushed tag, with the annotated tag message under “Highlights”; or creates a release with GitHub-generated notes if no draft exists
  • Available in Maven Central within 30 minutes

No manual steps needed! Just run make release-patch and everything is automated.

Version Management

Version is tracked in two files (automatically updated by Makefile):

  • pom.xml - Line 7: <version>0.0.1</version>
  • build.gradle - Line 7: version = '0.0.1'

Git tags follow semver format: v0.0.1, v0.1.0, v1.0.0

Important Notes

  1. Do not manually edit generated files in src/main/java/com/rootly/client/{api,model}/ unless absolutely necessary. Changes should be made to the OpenAPI spec and regenerated.

  2. Custom code should go in:

    • Extensions or wrappers around the generated API classes
    • Custom exception handling
    • Utility classes outside the generated packages

  3. Rate Limiting: The API has rate limits (3000 requests/60s). Implement retry logic with exponential backoff for production use.

  4. Base URL: Default is https://api.rootly.com but can be configured via ApiClient.setBasePath().

  5. Dependencies: All HTTP operations use OkHttp 4.12.0. Do not mix with other HTTP clients.