# GitHub REST API Endpoints in gsygithubappcompose: Complete Implementation Guide

> Explore the GitHub REST API endpoints used in gsygithubappcompose. Discover how over 30 endpoints for auth, repos, issues, and search are implemented in this Android app guide.

- Repository: [Shuyu Guo/gsygithubappcompose](https://github.com/carguo/gsygithubappcompose)
- Tags: api-reference
- Published: 2026-02-26

---

**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`](https://github.com/carguo/gsygithubappcompose/blob/main/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`](https://github.com/carguo/gsygithubappcompose/blob/main/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`](https://github.com/carguo/gsygithubappcompose/blob/main/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.

```kotlin
// 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`](https://github.com/carguo/gsygithubappcompose/blob/main/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`](https://github.com/carguo/gsygithubappcompose/blob/main/NetworkConfig.kt):

```kotlin
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:

```kotlin
// 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`](https://github.com/carguo/gsygithubappcompose/blob/main/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`](https://github.com/carguo/gsygithubappcompose/blob/main/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`](https://github.com/carguo/gsygithubappcompose/blob/main/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.