GitHub REST API Endpoints in gsygithubappcompose: Complete Implementation Guide

The gsygithubappcompose Android app centralizes all GitHub REST API interactions in a single Retrofit interface called GitHubApiService, defining over 30 endpoints across authentication, repositories, issues, and search using Retrofit annotations.

The open-source gsygithubappcompose project demonstrates modern Android networking by consolidating every GitHub API request into one maintainable service layer. Located in core/network/src/main/java/com/shuyu/gsygithubappcompose/core/network/api/GitHubApiService.kt, this interface exposes how the app consumes GitHub's REST API v3. All endpoints reference the base URL "https://api.github.com/" defined in NetworkConfig.kt, with each method annotated using Retrofit's HTTP verb markers to map directly to GitHub's official routes.

Authentication and OAuth Endpoints

The app handles GitHub authentication through dedicated OAuth and user management endpoints. These methods manage access tokens and user profile retrieval.

@POST("https://github.com/login/oauth/access_token") exchanges the temporary OAuth code for a permanent access token. This endpoint at lines 42-48 of GitHubApiService.kt accepts client_id, client_secret, and code parameters.

@GET("user") retrieves the authenticated user's profile data, while @PATCH("user") updates profile information such as name, email, or bio. These endpoints appear at lines 53-56 and 61-64 respectively.

// Exchange OAuth code for token
@POST("https://github.com/login/oauth/access_token")
suspend fun getAccessToken(
    @Query("client_id") clientId: String,
    @Query("client_secret") clientSecret: String,
    @Query("code") code: String
): TokenEntity

User Data and Social Graph Endpoints

User-related operations cover profile retrieval, activity streams, and social interactions like following users.

@GET("users/{username}") fetches public profile data for any GitHub user. For activity tracking, @GET("users/{username}/received_events") retrieves events the user receives (lines 77-83), while @GET("users/{username}/events") fetches their public activity (lines 89-94).

The app manages social relationships through multiple endpoints:

• @GET("user/followers") and @GET("users/{username}/followers") list followers
• @GET("user/following/{username}") checks if the authenticated user follows a specific account
• @PUT("user/following/{username}") and @DELETE("user/following/{username}") follow or unfollow users (lines 92-99)

Organization membership is queried via @GET("orgs/{org}/members") (lines 99-104) and @GET("users/{username}/orgs") (lines 69-74).

Repository Operations

Repository endpoints constitute the largest category, enabling browsing, starring, forking, and content retrieval.

@GET("users/{username}/repos") lists repositories for a specific user with pagination support (lines 133-139). For detailed views, @GET("repos/{owner}/{repo}") fetches repository metadata including stars, forks, and language statistics (lines 144-148).

The app tracks repository activity through @GET("networks/{owner}/{repo}/events") (lines 153-158) and manages forks via @GET("repos/{owner}/{repo}/forks") and @POST("repos/{owner}/{repo}/forks") (lines 164-169 and 536-542).

Star and watch operations use paired endpoints:

• @GET("user/starred/{owner}/{repo}"), @PUT("user/starred/{owner}/{repo}"), @DELETE("user/starred/{owner}/{repo}") (lines 95-115)
• @GET("user/subscriptions/{owner}/{repo}"), @PUT("user/subscriptions/{owner}/{repo}"), @DELETE("user/subscriptions/{owner}/{repo}") (lines 120-140)

Code browsing endpoints include @GET("repos/{owner}/{repo}/commits") and @GET("repos/{owner}/{repo}/commits/{sha}") for commit history (lines 197-210), @GET("repos/{owner}/{repo}/branches") (lines 445-452), and @GET("repos/{owner}/{repo}/contents/{path}") for file listings. The README is fetched via @GET("repos/{owner}/{repo}/readme") (lines 671-678) with an HTML accept header for rendered content.

Issue and Comment Management

The app provides full CRUD capabilities for GitHub issues and their comments.

@GET("repos/{owner}/{repo}/issues") lists repository issues with filtering support (lines 220-229), while @GET("repos/{owner}/{repo}/issues/{issue_number}") retrieves specific issue details (lines 80-86). Creating and modifying issues uses @POST("repos/{owner}/{repo}/issues") and @PATCH("repos/{owner}/{repo}/issues/{issue_number}") (lines 332-338 and 302-308).

Comment operations include:

• @GET("repos/{owner}/{repo}/issues/{issue_number}/comments") to list comments
• @POST to create comments
• @PATCH("repos/{owner}/{repo}/issues/comments/{comment_id}") to edit
• @DELETE("repos/{owner}/{repo}/issues/comments/{comment_id}") to remove

Issue state management uses @PUT("repos/{owner}/{repo}/issues/{issue_number}/lock") and @DELETE variants to lock or unlock conversations (lines 113-119).

Search and Notification Endpoints

GitHub's search API is exposed through three primary endpoints:

• @GET("search/repositories") (lines 110-117)
• @GET("search/users") (lines 122-127)
• @GET("search/issues") (lines 43-48)

Notification management uses @GET("notifications") to fetch unread items (lines 78-85). Marking notifications as read employs @PATCH("notifications/threads/{thread_id}") for individual threads and @PUT("notifications") to mark all as read (lines 90-98).

Custom Trending API Integration

Beyond GitHub's official API, the app integrates a third-party trending service: @GET("https://guoshuyu.cn/github/trend/list") fetches trending repositories with an api-token header (lines 605-610). This endpoint provides curated trending data not available in GitHub's standard REST API.

How Endpoints Are Defined

Every endpoint in GitHubApiService.kt follows Retrofit's annotation pattern. The interface declares suspend functions that Retrofit transforms into HTTP requests. Parameters bind to URLs using @Path for route variables, @Query for URL parameters, @Header for authentication tokens, and @Body for JSON payloads.

The base configuration resides in NetworkConfig.kt:

object NetworkConfig {
    const val BASE_URL = "https://api.github.com/"
    const val PAGE_SIZE = 30
}

When calling endpoints, the app typically passes authentication via the Authorization header:

// Initialize the API service
val api = Retrofit.Builder()
    .baseUrl(NetworkConfig.BASE_URL)
    .addConverterFactory(GsonConverterFactory.create())
    .build()
    .create(GitHubApiService::class.java)

// Example: Fetch authenticated user
suspend fun loadUser(token: String) {
    val user = api.getAuthenticatedUser("token $token")
    println("Logged in as: ${user.login}")
}

// Example: Create an issue
suspend fun reportBug(owner: String, repo: String, title: String, token: String) {
    val issue = api.createIssue(
        owner = owner,
        repo = repo,
        body = mapOf("title" to title, "body" to "Bug description")
    )
}

All functions return either data models (like User, Repository, or Issue) or Retrofit Response objects when the app requires raw HTTP handling.

Summary

• Centralized Architecture: All GitHub REST API endpoints live in GitHubApiService.kt, creating a single source of truth for network operations.
• Comprehensive Coverage: The interface defines 30+ endpoints spanning OAuth, user profiles, repositories, issues, search, and notifications.
• Retrofit Implementation: Endpoints use standard HTTP annotations (@GET, @POST, @PUT, @DELETE, @PATCH) with suspend functions for coroutine support.
• Authentication Pattern: Most endpoints accept a token parameter injected via @Header using the format "token {access_token}".
• Custom Extensions: Beyond GitHub's official API, the app consumes a custom trending API at guoshuyu.cn for repository discovery.

Frequently Asked Questions

How does gsygithubappcompose handle GitHub API authentication?

The app implements OAuth 2.0 flow using @POST("https://github.com/login/oauth/access_token") to exchange codes for tokens. Subsequent authenticated requests pass the token via @Header annotations using the format "token $accessToken", as seen in methods like getAuthenticatedUser() and createIssue().

What is the base URL for GitHub API calls in this app?

All GitHub REST API calls use "https://api.github.com/" defined as BASE_URL in NetworkConfig.kt. The only exception is the OAuth token exchange endpoint, which uses the full absolute URL https://github.com/login/oauth/access_token, and the custom trending API at https://guoshuyu.cn/github/trend/list.

Does the app use pagination for GitHub API requests?

Yes, paginated endpoints like @GET("users/{username}/repos") and @GET("notifications") accept @Query("page") and @Query("per_page") parameters. The default page size is defined in NetworkConfig.kt as 30 items per request, consistent with GitHub's standard pagination.

How are repository contents and files fetched?

The app uses @GET("repos/{owner}/{repo}/contents/{path}") to fetch both directory listings and file contents. For rendered README files, it calls @GET("repos/{owner}/{repo}/readme") with a custom @Headers("Accept: application/vnd.github.html") annotation to receive HTML formatted content rather than raw markdown.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}