simple-server

Spring Boot service that aggregates GitHub user profile and repository data into a single JSON response

running is detailed below in the To run section

Commentary

Project is a relatively basic Java API. We utilized the standard Java API (spring boot project) boilerplate.
The system is broken out into the standard pieces: controller, service, external, models, config, and exceptions.

Wanted to break it out as much as possible to demonstrate proper separation of responbilities. Although the project was pretty small, we could still demonstrate most pieces of an API system through here. Breaking it out as such also makes the system almost self documenting. It is also very extensible since there is a clean single responsbility principle being followed here. Only thing that was excluded (which I would usually use) is a "APIPaths" file that would usually contain all the urls. Since this was only 2 we didn't deem it necessary. As the endpoints increase it's an easy add.

Some design decisions such as the controller prechecks were informed from the researching github username constraints. Various sources provided information regarding this area. (https://github.com/shinnn/github-username-regex, google search, and other references on the github site). Prechecking here allows for the quick fail when we know the endpoint wont work.
Pagination was informed via Pagination page on the github API page 'https://docs.github.com/en/rest/using-the-rest-api/using-pagination-in-the-rest-api?apiVersion=2026-03-10#using-link-headers`
The api utilizes a link model so that needed to be considered.

We used caffeine as the caching method as it is a high performance and easy to use library (also one of the 9 that spring supports and it sounded the most interesting and hadnt used it so figured id give it a try).

Redirect responses (github API returning 301 and 307) were left out of scope due to the 2 APIs we were using not utilizing them. It was looked into since it is something Github does for other endpoints, but the endpoints in this example do not return those values.

To run

runs on java 25 by default
can change the version in the gradle.properties file

1. Clone and build

git clone https://github.com/thejdubs/simple-server.git
cd simple-server
./gradlew clean build

Windows:

git clone https://github.com/thejdubs/simple-server.git
cd simple-server
.\gradlew.bat clean build

2. Start the server

./gradlew bootRun

Windows:

.\gradlew.bat bootRun

The server listens on http://localhost:8080
can be changed in application.yml detailed below

3. Call the API

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

given test case

curl http://localhost:8080/api/users/obra

will test pagination working properly

curl http://localhost:8080/api/users/2f--3-2f23-

will test validation

should receive a JSON payload with user profile fields and a repos array beware if using powershell curl output might not be as expected

4. Run tests

./gradlew test

Windows:

.\gradlew.bat test

Common tasks

Task	Command
Run tests (Java 25, default)	./gradlew test
Run tests (Java 21)	./gradlew test -PjavaVersion=21
Run server	./gradlew bootRun
Run server (Java 21)	./gradlew bootRun -PjavaVersion=21
Build jar	./gradlew bootJar
Clean build	./gradlew clean build
Run one test class	./gradlew test --tests "com.simpleserver.mapper.UserProfileMapperTest"

Windows: replace ./gradlew with .\gradlew.bat.

Set the Java toolchain version with -PjavaVersion=25 (default) or -PjavaVersion=21. You can also set javaVersion=21 in gradle.properties.

Configuration

Defaults live in src/main/resources/application.yml:

Property	Default	Description
server.port	8080	HTTP port
github.api.base-url	https://api.github.com	GitHub API base URL
github.api.user-agent	simple-server/1.0	GitHub user agent header
spring.cache.caffeine.spec	maximumSize=500,expireAfterWrite=5m	Cache size and TTL

Override at runtime:

./gradlew bootRun --args='--server.port=9090'

Or with environment variables:

export SERVER_PORT=9090
./gradlew bootRun