hangar-api

Overview

HangarClient is a Java API client designed for interacting with the Hangar platform.
It provides a comprehensive and intuitive interface for retrieving and managing Hangar projects, users, pages, statistics, API keys, and permissions.

Table of Contents

1. Setup
2. Authentication
3. Client Initialization
4. Project Operations
   • Retrieve All Projects
   • Retrieve Specific Project
   • Retrieve Project Members
   • Retrieve Watchers & Stargazers
   • Retrieve Project Stats
   • Page Retrieval
5. User Operations
   • Retrieve All Users
   • Retrieve Specific User
   • Retrieve User Starred & Watching
6. API Keys & Permissions
   • Retrieve API Keys
   • Check Permissions
   • Retrieve Permissions
7. Model Classes
8. Further Reading

Setup

Dependency

Add the Hangar API dependency to your Maven project:

<dependency>
  <groupId>com.github.TheSilentPro</groupId>
  <artifactId>hangar-api</artifactId>
  <version>REPLACE_WITH_LATEST</version>
</dependency>

<repository>
    <id>jitpack.io</id>
    <url>https://jitpack.io</url>
</repository>

Authentication

Many endpoints can be used without authentication, but it is recommended that you provide it anyway.
To force authentication, use HangarClient#authenticate();.
You only need to call it once, the client will automatically renew when it expires.

JWT Authentication

Use JWTAuthProvider for authentication with your API key:

JWTAuthProvider authProvider = new JWTAuthProvider("API_KEY");

Client Initialization

Initialize the client:

HangarClient client = HangarClient.builder()
    .auth(new JWTAuthProvider("<token>"))
    .build();

You can optionally use a custom HTTP client and set a custom User-Agent.

Client Information

Methods will return either a CompletableFuture<Response> or RequestBuilder.

The RequestBuilder allows you to further customize the request before sending it.

You need to use #execute() before getting the future.

The CompletableFuture<Response> will return the response directly. This is used when further customization is not applicable.

Note that calling #join() on CompletableFuture will make a blocking call.
For async use #whenComplete, thenAccept, etc...

Project Operations

Retrieve All Projects

client.retrieveProjects()
      .execute()
      .join()
      .getProjects()
      .forEach(this::printProjectInfo);

Retrieve Specific Project

Project project = client.retrieveProject("ProjectName")
                        .join()
                        .getProject();

Displays detailed project information such as avatar URL, category, timestamps, content, statistics, and more.

Retrieve Project Members

client.retrieveMembers("ProjectName")
      .limit(10)
      .execute()
      .join()
      .getMembers()
      .forEach(member -> {
          String name = member.getUser();
          UUID id = member.getUserId();
          String role = member.getRoles().stream()
                              .map(ProjectMemberRole::getTitle)
                              .findAny()
                              .orElse("N/A");
      });

Retrieve Watchers & Stargazers

// Watchers
client.retrieveWatchers("ProjectName")
      .join()
      .getUsers();

// Stargazers
client.retrieveStargazers("ProjectName")
      .join()
      .getUsers();

Retrieve Project Stats

client.retrieveStats("ProjectName", Instant.EPOCH, Instant.now())
      .join()
      .getStats()
      .forEach((platform, stats) -> {
          System.out.printf("%s: %d downloads, %d views\n", platform, stats.getDownloads(), stats.getViews());
      });

Page Retrieval

// Main page content
String mainContent = client.retrievePage("ProjectName")
                           .join()
                           .getContent();

// Specific page
String pageContent = client.retrievePage("ProjectName", "PageSlug")
                            .join()
                            .getContent();

User Operations

Retrieve All Users

UsersResponse users = client.retrieveUsers()
                             .execute()
                             .join();
users.getUsers().forEach(u -> System.out.println(u.getName()));

Retrieve Specific User

User user = client.retrieveUser("Username")
                  .join()
                  .getUser();

Retrieve User Starred & Watching

// Starred projects
client.retrieveUserStarred("Username")
      .execute()
      .join()
      .getProjects();

// Watching projects
client.retrieveUserWatching("Username")
      .execute()
      .join()
      .getProjects();

API Keys & Permissions

Retrieve API Keys

client.retrieveKeys()
      .join()
      .getKeys()
      .forEach(key -> System.out.println(key.getName()));

Check Permissions

client.hasPermissions()
      .fromProject("ProjectName")
      .withPermissions(Permission.EDIT_API_KEYS, Permission.VIEW_PUBLIC_INFO)
      .execute()
      .thenAccept(response -> {
          System.out.println("Allowed: " + response.getResult());
      })
      .join();

Retrieve Permissions

client.retrievePermissions()
      .fromProject("ProjectName")
      .execute()
      .thenAccept(response -> {
          System.out.println("Binary String: " + response.getPermissionBinString());
          response.getPermissions().forEach(p -> System.out.println("Allowed: " + p.name()));
      })
      .join();

Model Classes

Models are entities from hangar wrapped in java classes for ease of use.

• APIKey - Represents an API Key.
• Project - Represents a project.
• User - Represents a user.
• UserProject - Represents a user project. Unlike Project, this holds less information.
• ProjectMember - Represents a user with roles on a project.
• NameHistory - Represents name history data from a user.

Further Reading

• Hangar API GitHub Repository
• API Reference Documentation