GitAPI

GitAPI is a small backend REST application built with Spring Boot.
It acts as a thin integration layer over the GitHub REST API and exposes a clean endpoint for retrieving a user's non-fork repositories with their branches and latest commit SHA.

The project now also includes a lightweight demo page, so a visitor opening the live app no longer lands on raw JSON without context.

This project is intentionally simple, but structured to look closer to a production-style backend than a basic demo:

• REST-style endpoint design
• clear service responsibility
• explicit exception handling
• integration-oriented error mapping
• controller test with MockMvc
• lightweight portfolio-ready demo page on top of the API

Features

• Fetch GitHub repositories for a given user
• Exclude forked repositories from the response
• Return repository branches in a flattened response
• Return the latest commit SHA for each branch
• Handle invalid input and GitHub API errors with meaningful HTTP responses
• Provide a simple HTML demo page for live presentation
• Provide a readable HTML result view with a link to raw JSON

What This Application Does

This application accepts a GitHub username and returns a flat list of that user's non-fork repositories and their branches.

For each branch, it returns:

• owner login
• repository name
• branch name
• latest commit SHA

In practice, this means the application:

• calls the GitHub API for a user's repositories
• filters out repositories that are forks
• calls the GitHub API again for branches of each remaining repository
• maps the result into a simple backend-friendly JSON response

For live demo purposes, the root page also explains:

• what the project does
• what username to enter
• what result the visitor will receive
• how to call the REST endpoint directly

What You Can Do With It

After starting the application, you can:

• open http://localhost:8080/ to use the demo page
• open http://localhost:8080/demo/results?username=octocat to see the readable HTML result view
• open http://localhost:8080/api to verify that the API is running
• call GET /users/{username}/repositories for any public GitHub user
• test success and error scenarios directly from the browser, curl, or Postman

Example:

curl http://localhost:8080/users/octocat/repositories

Tech Stack

• Java 17
• Spring Boot 3
• Spring Web
• Maven
• Lombok
• JUnit 5
• MockMvc

Demo Flow

Demo Landing Page

GET /

Shows a lightweight HTML page with:

• project description
• username input
• example usernames
• explanation of the REST endpoint

Demo Result Page

GET /demo/results?username={username}

Shows:

• selected GitHub username
• repositories grouped with their branches
• latest commit SHA per branch
• link to the raw JSON returned by the REST API

API

Get User Repositories

GET /users/{username}/repositories

Returns a flattened list of all non-fork repositories for the given GitHub user and their branches.

Path Variable

• username - GitHub username

Example Request

GET /users/octocat/repositories
Accept: application/json

API Info Endpoint

GET /api

Returns a short status payload describing the application and example endpoint usage.

Example Success Response

[
  {
    "name": "octocat",
    "repositoryName": "hello-world",
    "branchName": "main",
    "sha": "7fd1a60b01f91b314f59951e1f18e4f1d2d8c9ff"
  },
  {
    "name": "octocat",
    "repositoryName": "hello-world",
    "branchName": "develop",
    "sha": "3c8f1bfa2e9a7e807fd77d2c6b7b9910d6f20abc"
  }
]

Example Error Responses

400 Bad Request

{
  "status": 400,
  "message": "Username must not be blank",
  "path": "/users/%20/repositories",
  "timestamp": "2026-04-04T10:15:30Z"
}

404 Not Found

{
  "status": 404,
  "message": "GitHub user 'missing-user' was not found",
  "path": "/users/missing-user/repositories",
  "timestamp": "2026-04-04T10:15:30Z"
}

502 Bad Gateway

{
  "status": 502,
  "message": "Failed to fetch data from GitHub API",
  "path": "/users/octocat/repositories",
  "timestamp": "2026-04-04T10:15:30Z"
}

Project Structure

src/main/java/pl/rutkowski/gitapi
├── GitApiApplication.java
├── DemoPageController.java
├── GitHubRestController.java
├── GitHubService.java
├── GitHubUserDetails.java
└── exception
    ├── ControllerExceptionHandler.java
    ├── ErrorMessage.java
    ├── GitHubIntegrationException.java
    ├── GitHubUserNotFoundException.java
    └── InvalidUsernameException.java

Static demo assets:

src/main/resources/static
├── app.js
├── demo-results.html
├── index.html
└── styles.css

How It Works

1. The demo page or API client sends a username.
2. The controller accepts GET /users/{username}/repositories.
3. The service validates the input.
4. The application calls the GitHub API to fetch repositories for the user.
5. Forked repositories are filtered out.
6. For each remaining repository, the application fetches branches.
7. The response is flattened into a simple list containing:
   • owner login
   • repository name
   • branch name
   • commit SHA
8. The demo result page groups that flat API response into a more readable browser view.

Running the Application

./mvnw spring-boot:run

Application URL:

http://localhost:8080

Useful URLs:

• Demo page: http://localhost:8080/
• Demo result example: http://localhost:8080/demo/results?username=octocat
• API info: http://localhost:8080/api
• Raw REST endpoint: http://localhost:8080/users/octocat/repositories

Running Tests

./mvnw test