{"id":13753003,"url":"https://github.com/jeroenr/api-gateway","last_synced_at":"2026-01-16T06:49:22.785Z","repository":{"id":137927956,"uuid":"66570761","full_name":"jeroenr/api-gateway","owner":"jeroenr","description":"Api Gateway for a microservices deployment","archived":false,"fork":false,"pushed_at":"2017-07-24T19:15:10.000Z","size":1179,"stargazers_count":30,"open_issues_count":0,"forks_count":3,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-11-16T05:32:29.975Z","etag":null,"topics":["api-gateway","api-service","docker","kubernetes","kubernetes-api","microservice","microservices","microservices-architecture","service-registry"],"latest_commit_sha":null,"homepage":null,"language":"Scala","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jeroenr.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2016-08-25T15:33:24.000Z","updated_at":"2023-12-30T18:35:10.000Z","dependencies_parsed_at":"2024-01-17T15:02:51.400Z","dependency_job_id":"707e0b64-f1e1-4287-a6b9-6021934e20ce","html_url":"https://github.com/jeroenr/api-gateway","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeroenr%2Fapi-gateway","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeroenr%2Fapi-gateway/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeroenr%2Fapi-gateway/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeroenr%2Fapi-gateway/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jeroenr","download_url":"https://codeload.github.com/jeroenr/api-gateway/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253321808,"owners_count":21890470,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-gateway","api-service","docker","kubernetes","kubernetes-api","microservice","microservices","microservices-architecture","service-registry"],"created_at":"2024-08-03T09:01:14.383Z","updated_at":"2026-01-16T06:49:22.749Z","avatar_url":"https://github.com/jeroenr.png","language":"Scala","funding_links":[],"categories":["service-registry"],"sub_categories":[],"readme":"Api Gateway [![Build Status](https://travis-ci.org/jeroenr/api-gateway.svg?branch=master)](https://travis-ci.org/jeroenr/api-gateway) [![License](https://img.shields.io/hexpm/l/plug.svg)](http://www.apache.org/licenses/LICENSE-2.0)\n=========================\nThe Api Gateway is the entry point of a microservice infrastructure (see [api gateway pattern](http://microservices.io/patterns/apigateway.html)). The main problem it solves is \"How do the clients of a Microservices-based application access the individual services?\". It handles the first layer of authentication and routes the incoming requests (like a reverse proxy) to the corresponding service, based on the mapping in its service registry.\n\n## Contributions\nThis is a young but very active project and absolutely needs your help. Good ways to contribute include:\n\n* Raising bugs and feature requests\n* Fixing bugs\n* Improving the performance\n* Adding to the documentation\n\n## Requirements\n- Sbt 0.13.*\n\n## Running\n```bash \n$ sbt run\n```\nBy default this will start the gateway interface on ```http://localhost:8080/api``` and the management interface on ```http://localhost:8081```\n\n## Configuration\nMost of the configurable options are available as environment variables. Below is a list with default values:\n* ```API_PREFIX=api```\n* ```AUTH_HOST=localhost```\n* ```AUTH_PORT=7070```\n* ```K8S_API_HOST=localhost```\n* ```K8S_API_PORT=8001```\n* ```K8S_API_TOKEN=```\n\nFor a Kubernetes configuration example see the [sample descriptor file](https://github.com/jeroenr/api-gateway/blob/master/k8s-descriptor.yaml).\n\n## Pulling the docker image\n```\n$ docker pull jeroenrosenberg/api-gateway\n```\n\n## Building a docker image\nThis project is using the [Docker plugin of the Sbt Native Packager](http://www.scala-sbt.org/sbt-native-packager/formats/docker.html) to generate a docker image using:\n```bash\n$ sbt docker:publishLocal\n```\nThen you can simply publish your docker image to your favorite docker repository. For instance for the Google Container Registry:\n```bash\n$ docker tag com.github.jeroenr/api-gateway eu.gcr.io/my-docker-registry/api-gateway\n$ gcloud docker push eu.gcr.io/my-docker-registry/api-gateway\n```\n\n## Deploying in Kubernetes\nSince the Api gateway currently relies on the Kubernetes API for service discovery the first thing we would need is an access token. The easiest way to do this would be through [service accounts](https://kubernetes.io/docs/admin/authentication/#service-account-tokens). After that you need descriptor files for the [Kubernetes deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) and service. Below is a quick walkthrough the steps. I assume you're familiar with Kubernetes' terminology and the [kubectl](https://kubernetes.io/docs/user-guide/kubectl-overview/) commandline tool.\n### Create service account\nThe steps below will create a service account and associated [secret](https://kubernetes.io/docs/concepts/configuration/secret/) to be used by the Api gateway [pod](https://kubernetes.io/docs/concepts/workloads/pods/pod/).\n```bash\n$ kubectl create serviceaccount my-service-account\nserviceaccount \"my-service-account\" created\n```\nGreat, now a new service account has been created and under the hood also an associated secret which we can retrieve by:\n```bash\n$ kubectl get serviceaccounts my-service-account -o yaml\napiVersion: v1\nkind: ServiceAccount\nmetadata:\n  # ...\nsecrets:\n- name: my-service-account-token-1yvwg\n```\nAs you can see in our example the generated secret is called \"my-service-account-token-1yvwg\". Depending on where you pull your docker image from you might also need to create another secret with credentials for the docker registry to be used as an image pull secret. \n\nNow we can setup our K8s deployment and service descriptor. Here's an [example config](https://github.com/jeroenr/api-gateway/blob/master/k8s-descriptor.yaml). Important to configure is:\n* The container image path (e.g. eu.gcr.io/my-docker-registry/api-gateway)\n* The image pull secret for the container registry (e.g. my-docker-registry-secret)\n* The secretKeyRef.name for the ```K8S_API_TOKEN``` env variable (e.g. my-service-account-token-1yvwg)\n* The AUTH_HOST and AUTH_PORT env variables to point to your backing authentication service\n\nAs a final step we can now create the k8s deployment and service: \n```bash\n$ kubectl apply -f k8s-descriptor.yaml\ndeployment \"api-gateway\" created\nservice \"api-gateway-svc\" created\n```\nCool, now we're running the Api gateway in Kubernetes!\n\n## Deploying on other platforms\nCurrently the Api gateway relies on the services endpoint from the Kubernetes API to poll for service updates (see [Automatic Service discovery section](#automatic-service-discovery)). If you want to deploy the Api gateway on a different platform you would have to:\n* Mock this endpoint and manually update the service registry (see (#manually-updating-the-service-registry). You could also rely on something like Consul and write a sync script.  \n* Make a PR to add a flag in the configuration to disable automatic service discovery\n* Make a PR to support different pluggable service discovery modules\n* The k8s namespaces to watch for service updates. This can be configured through JVM params (e.g. ```-Dintegration.kubernetes.namespaces.0=my-env``` to only handle service updates on the 'my-env' namespace)\n\n## Features\n\n### Authentication\nAs mentioned the Api gateway is the first layer of the authentication flow. If a request is made to a secured route (i.e. a route which maps to a service with the flag \"secured\" set) it will request a [JWT](https://jwt.io/) access token from an authentication service (e.g. https://github.com/cupenya/auth-service which retrieves a user claim based on a reference token in a domain cookie and generates a JWT token for this claim). If a valid JWT token is returned the call is forwarded to the corresponding service and the JWT token is passed in the request header as an Oauth bearer token for further authorization to be done by the backing service. \n\nIf no valid JWT token is returned the error response will be forwarded to the caller. This could happen when for instance the user session has expired. The user could then \"login\" again using the \"/auth/login\" endpoint as follows:\n```bash\n$ curl -X POST \\\n  http://localhost:8080/auth/login \\\n  -H 'cache-control: no-cache' \\\n  -H 'content-type: application/json'\n  -d '{\n    \"username\": \"my-user\",\n    \"password\": \"my-pass\"\n}'\n```\nThis call is just forwarded to the authentication service.\n\nHere's a [Postman collection with all available Api calls](https://www.getpostman.com/collections/9b269b9f26bf0a3ce255)\n\n### Automatic Service discovery\nThe Api gateway supports service discovery through the Kubernetes API using the [k8s-svc-discovery module](https://github.com/jeroenr/k8s-svc-discovery). It's polling the ```/api/v1/services``` endpoint for service and updates the routing / mapping based on the service metadata.\n\n### Manually updating the service registry\nThere's also a dashboard Api which can be used to manually update the service registry. For instance to add a service:\n```bash\n$ curl -X POST \\\n  http://localhost:8081/services \\\n  -H 'cache-control: no-cache' \\\n  -H 'content-type: application/json'\n  -d '{\n\t\"name\": \"my-user-service\",\n\t\"host\": \"localhost\",\n\t\"resource\": \"users\",\n\t\"port\": 9090,\n\t\"secured\": false\n}'\n```\nThis will add a reverse proxy mapping from ```http://{api-gateway-host}:{api-gateway-port}/{api-gateway-prefix}/users``` to ```http://localhost:9090/users```. If no 'port' is specified it will default to 80. The flag 'secured' determines whether the Api gateway performs authentication checks and passes on the authentication info to the corresponding service. See [Authentication section](#authentication) for more information.\n\nHere's a [Postman collection with all available Api calls](https://www.getpostman.com/collections/9b269b9f26bf0a3ce255)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjeroenr%2Fapi-gateway","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjeroenr%2Fapi-gateway","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjeroenr%2Fapi-gateway/lists"}