A JSON-over-HTTP API that retrieves 10 most active GitHub Java frameworks, in terms of the number of stargazers. Stats include star count and total number of contributors.

Clients may optionally provide their GitHub credentials, which unlocks additional features:

• star a repo
• unstar a repo
• see whether they have starred a repo

You will need:

• JDK 1.8+
• Docker
• To support Java annotation processing in your IDE:
  • IntelliJ IDEA: install "Lombok Plugin"
  • Eclipse: read this

Gradle does not need to be install locally if you use the included ./gradlew wrapper. Windows users should replace ./gradlew with gradlew.bat in the following instructions.

./gradlew test

Build and run directly from sources:

./gradlew run

Build and run a Docker image:

./gradlew docker --info

docker run --rm -p 8080:8080 ogrigas/superstars

• LOCAL_PORT (default is 8080)
• GITHUB_URL (default is https://api.github.com)
• SUPERSTAR_LIMIT (default is 10)
• HTTP_LOGGING: "BASIC", "HEADERS", "BODY" or "NONE" (default is "BASIC")

Get OpenAPI specification:

curl http://localhost:8080/apidocs.yml

Fetch most popular Java frameworks:

curl -i http://localhost:8080/java-superstars

Sort by number of contributors, in ascending order:

curl -i "http://localhost:8080/java-superstars?sortBy=contributorCount&direction=ascending"

Provide GitHub Basic credentials to include starredByMe flag in response:

curl -i -u "username:password" http://localhost:8080/java-superstars

Alternatively, you may authenticate with GitHub token:

curl -i -H "Authorization: token {TOKEN}" http://localhost:8080/java-superstars

Star a repo:

curl -i -u "username:password" -X PUT http://localhost:8080/java-superstars/{owner}/{repo}/star

Unstar a repo:

curl -i -u "username:password" -X DELETE http://localhost:8080/java-superstars/{owner}/{repo}/star

• Use Karma-style git commit messages
• Embrace immutability and prefer pure functions, except at system boundary
• Use Lombok annotations in Java data-classes to reduce boilerplate
• Use Groovy and Spock for writing readable BDD-style tests
• Every runtime dependency brings incidental complexity, so add them only if you find yourself reinventing the wheel
  • keep an eye on gradle dependencies --configuration runtime
  • so far I avoided the need for Guava, Apache Commons, or heavyweight frameworks

If you don't provide credentials, you will quickly hit GitHub rate limit of max 60 requests per hour. The number of queries could be dramatically reduced by using GraphQL for joins, e.g. repos<->contributors. Unfortunately, GitHub does not allow anonymous use of GraphQL API as of this writing.