integrate-github-api
Overview and Credit
This project uses GitHub's v4 API, which is based on GraphQL, to expose a REST API that's with the following functionality:
- GET /v1/<github_organization_name>/repositories
- Get the names of <github_organization_name>'s public repositories
- PUT /v1/<github_organization_name>/repositories/to_file
- Write the names of <github_organization_name>'s public repositories to a compressed JSON file on the server
Repository structure and some functions, like catchAsyncRequest, are inherited from YouTube series: https://www.youtube.com/playlist?list=PLcCp4mjO-z9_HmJ5rSonmiEGfP-kyRMlI
Single Command Run
Create a file called .env
in the directory from which you'll run the Docker container with contents:
THIRD_PARTY_TOKEN=<your_github_personal_access_token>
Then run:
docker run --rm -p '3000:3000' --env-file .env mattddean/integrate_github_api:latest
You should now be able to issue REST requests to http://localhost:3000 and receive responses from the Node.js application running in the container you just started.
Then, to get a shell into this running container to verify that the /tmp/knock_interview.json.gz file was successfully created, run:
docker ps # note the Container ID associated with the mattddean/integrate_github_api:latest image
docker exec -it <container_id> bash
To stop the image, run:
docker ps # note the Container ID associated with the mattddean/integrate_github_api:latest image
docker stop <container_id>
Docker will automatically download the image from Docker Hub
Note that because the app is running in Docker, it will write the /tmp/knock_interview.json.gz to the container's filesystem, not to the host filesystem
Stopping this container
In another shell, run:
docker ps # take note of the relevant Container ID
docker stop <container_id>
Replace
<container_id>
with the relevant Container ID you found when runningdocker ps
GraphQL Rationale
Using GitHub's GraphQL API rather than their REST one gives me two benefits:
- I can demonstrate my ability to use / adapt to GraphQL
- Best chance of avoiding deprecation
- GitHub's GraphQL API is their newest API. In fact, they call it "V4" of their API rather than just a GraphQL version of V3. If further development is needed on this integration project, we're most likely to have access to GitHub's newest features if we use their newest API.
Update to latest Docker Image
docker pull mattddean/integrate_github_api:latest
Set up development environment
Host Machine Dependencies
- Docker
Setting up your dev environment for the first time
You'll only need to perform these tasks once for a new host machine.
Create a <repo_root>/api/.env file with the following contents:
THIRD_PARTY_TOKEN=<your_github_personal_access_token>
This is needed in order to authenticate on GitHub's v4 GraphQL API. See this page for instructions on creating a GitHub Personal Access Token: https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token
Install npm dependencies:
docker-compose run backend bash
# in the shell that opens...
npm install
exit
Starting your dev environment
Run the following command to start your dev environment:
CURRENT_USER_ID=$(id -u) CURRENT_GROUP_ID=$(id -g) docker-compose up backend
Docker will connect the container's port 3000 to your host's port 3000
You should now be able to issue API requests on your host machine to localhost:3000
Get a shell in your Docker dev environment
With the backend container "up", run the following in another shell:
docker-compose exec backend bash
Run tests
In your Docker dev environment's shell, run:
npm run test
Building for Production
The app can be pushed to your Docker Hub registry as a container with the following commands:
cd api
docker build -t <your_docker_hub_username>/integrate_github_api:latest .
docker login
docker push <your_docker_hub_username>/integrate_github_api:latest
Replace
<your_docker_hub_username>
with your Docker Hub Username.
TODO
- Distinguish between an error in connecting to the third party and an error reported from the third party
- Handle In-Memory cache warning from Apollo that is reported when running tests