githubconnector

Welcome to the githubconnector application, it is responsible for grabbing information from github and mapping it to our customers expected object.

Build & Test

I am using gradle as my build tool.
Included in this repo is the gradle wrapper, so all the following commands are able to run without gradle as a local dependency.

To build the program:

./gradlew clean build

The build command also runs:

./gradlew detekt to enforce code formatting, syntax, and many other rules. Detekt Repo
./gradlew test to run all the tests, test output will be shown during the build and test tasks

Run & Hit

To run the application:

./gradlew clean bootRun

Example request:

curl "http://localhost:8080/github_connector/v1/users/octocat"

Example Response:

{
  "user_name": "octocat",
  "display_name": "The Octocat",
  "avatar": "https://avatars.githubusercontent.com/u/583231?v=4",
  "geo_location": "San Francisco",
  "email": null,
  "url": "https://github.com/octocat",
  "created_at": "2011-01-25 18:44:36",
  "repos": [
    {
      "name": "boysenberry-repo-1",
      "url": "https://github.com/octocat/boysenberry-repo-1"
    }
  ]
}

Architecture & Decisions

Application architecture is pretty simple with a controller endpoint, and a couple of services to handle the mapping logic / API call.
Retrofit is used to make the API call to github.
Jackson is responsible for the mapping of json<>models to avoid a bunch of by-hand json parsing.
The ObjectMapper we use turns off FAIL_ON_UNKNOWN_PROPERTIES. The github API call fails without it since we aren't using all the fields. I personally think this defaulting to true is not a great decision.
The ObjectMapper also uses the kotlinModule() to play nicely with kotlin.
When a user is not found in github, we return a 404 with an appropriate error message to our user. This happens before the repo call is made, so we don't end up making two bad API calls.

Technology

Kotlin / Spring Boot - I am quite comfortable in both, and are generally scalable technologies. They are both well-supported / maintained, and there are many docs on how to do things. It is easy to expand upon and there are countless libraries/plugins for additional technologies.
Retrofit - Used for easy API calls, because RestTemplate is not fun to use. It also has great coroutine support.
OkHttp - The underlying library for Retrofit, I pull in some extra OkHttp stuff for logging.
Kotest / mockk / kluent - Test frameworks and verification matching library.
Detekt - Static Analysis tool for good practices and consistent formatting.

Notes

I would talk with the client about receiving the created_at field in the standard ISO-8601 datetime format.
Additionally, the requested datetime format by the client doesn't have any time zone information. Since this is a bad pattern, I will be making the assumption they want UTC time. Unfortunately, their requested pattern has no way to tell them this.
I would also work with the client on consistent naming, they want to send in a username but in the response they would like a user_name. Normally username is a single word, so I'd advise them to use username.
I personally didn't run into any issues with the default github rate-limiting.
The initial build took me roughly 2 hours, including some debugging. I spent another 30 minutes writing some test cases, and a final 30 minutes doing some cleanup, documentation, and this writeup.

Future Improvements

Add a proper auth solution to avoid rate limiting. This could be done by adding parameters to our API call, which would be used to generate a github auth token. This token would then be sent along during the github API call.
Add externalized configuration for things like github api url, token information, api logging, etc.
Add proper functional tests where the Application Context starts, endpoints are hit, and results are expected. Maybe add a mock api call to github.
Add CI/CD for automated testing during PRs and simplified releases/deployments.
Add a bunch of stuff to the github API call to make it better:
- More robust error handling
- Retry logic
- Self rate limiting?
Containerize the application for easy deployments.
Use coroutines and/or webflux for improved non-blocking performance .

ahatzz11/githubconnector