An easy way to orchestrate your APIs
Heimdall is an API orchestrator, providing a simple way to manipulate request/response and uncoupling it from your business domain, granting more flexibility and customization to your API.
- Gateway GET; POST; PUT; DELETE; PATH; HEAD
- Dashboards
- Analytics
- Interceptors
- Mock
- Logging
- Rating limit
- Security
- Customization with Java or Groovy
- Middlewares
- Security
- Authentication
- Authorization
Keep in mind that you are going to start 3 Spring Boot applications, 1 Database instance, and RabbitMq. Make sure you have 4 GB RAM available on your machine.
$ git clone --depth=1 https://github.com/getheimdall/heimdall.git heimdall
$ cd heimdall- Docker https://www.docker.com/
- Docker Compose https://docs.docker.com/compose/
If you would like to build images yourself (with some changes in the code, for example), you will have to clone all the repository and build the artifacts with Maven. Then, run:
$ docker-compose -f docker-compose.yml -f docker-compose.dev.yml updocker-compose.dev.yml inherits docker-compose.yml with the additional possibility to build images locally and expose all containers ports for convenient development.
Access Heimdall on: http://localhost:3000
- Nodejs https://nodejs.org/
- Maven https://maven.apache.org/
- Java 8 http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html
- PostgreSQL https://www.postgresql.org/
- Erlang http://www.erlang.org/downloads
- RabbitMQ https://www.rabbitmq.com/download.html
- Redis https://redis.io/download or https://github.com/MicrosoftArchive/redis/releases
Open your favorite Terminal and run these commands.
To start config:
$ cd /heimdall-config
$ mvn spring-boot:runTo start gateway (requires CONFIG already started):
$ cd /heimdall-gateway
$ mvn spring-boot:runThird, tab to start API (requires CONFIG already started):
$ cd /heimdall-api
$ mvn spring-boot:run[optional] To start front-end (requires API already started):
With Yarn:
$ cd /heimdall-frontend
$ yarn
$ yarn runWithout Yarn:
$ cd /heimdall-frontend
$ npm install
$ npm run start- http://localhost:8080 - Gateway
- http://localhost:8888 - Config
- http://localhost:9090 - API
- http://localhost:3000 - Front-end
All Spring Boot applications require an already running Config Server for startup. However, we can start all the containers simultaneously because of depends_on docker-compose option.
You must follow a specific registration process to create the routing process. This documentation will provide all information needed to complete the process through a step-by-step guide.
The first verification from Heimdall is the environment linked in the request. For an API be registered, it must have a linked environment. The environment is the heart of the routing, with which Heimdall will identify both the origin and destiny routes. One API can be linked with more than one environment; it is your choice.
The first step before registering an API is to define an environment. To do that, use the menu under Menu -> Environment -> Add to start an environment registration.
Once there is a registered environment, it is possible to register an API. For that, use the API menu. During the API's registration process, its identification will be the "basepath." An API is a resource group; this resources can be added after the API registration is finished.
The resource is nothing more than one operation group. Its use is to organize the operations (that will be explained in the next topic). The resource registration can be initialized after an API is added. The resource was created to organize the operations and make it easier to link the interceptors to a group.
Example: User domain; the resource name will be "users"
- POST - /basePath/users
- GET - /basePath/users/{id}
- PUT - /basePath/users/{id}
- DELETE - /basePath/users/{id}
A resource can have any name, but to make this example simpler, we will use the names that make sense about the operations used in this documentation.
It is necessary to add some operations to complete the basic lifecycle to use the API. The operation is a real service the gateway will route. A group of operations comprise an API. They are responsible for mapping the back-end services that will be called. As an example, we used the same paths as in the resources topic.
Example: User domain; the resource name will be "users"
- POST - /basePath/users
- GET - /basePath/users/{id}
- PUT - /basePath/users/{id}
- DELETE - /basePath/users/{id}
The bolded portions above are operations. An operation needs an HTTP verb to be unique.
The plan is just a tag to the API. Its main function is to link some resources that Heimdall have without impacting the API directly, making possible for multiple API consumers to have their respective configurations without one affecting the other.
For instance, think of two clients consuming the same API, but one of them wants to save the request logs, and the other does not. To enable this, one client will have a "Plan A," and the other will have a "Plan B," where "Plan A" will be linked with an "Interceptor Log" and "Plan B" will not. This way, both will be consuming the same service without affecting each other.
With Heimdall, you can manipulate the requests through the interceptors. You can intercept requests in lots of situations, like block access to some services or save the request logs. By default, Heimdall already has some interceptors available.
To create an interceptor, an API needs to exist. When you select an API, you can see an "Interceptor" tab to manipulate or add a new interceptor. Using drag n' drop, it is possible to add or remove an interceptor where you wish. Drag an interceptor to the request or response areas, and a dialog will be shown for you to submit an interceptor with its details.
It is important to note that you cannot add an interceptor directly to an API; you can attach it to a Plan, Resource or Operation that are registered to that API.
Heimdall being an orchestrator, you have lots of managers, and one of their responsibilities is to govern the developers using the API. A developer can use registered apps to consume the API services. To manage the developers, you need to navigate to developers menu; there you can add a new developer or manipulate the registered developers.
The developer can own multiple apps inside Heimdall. An app represents an external application that the developer wants to register in Heimdall. The app can consume any API registered in Heimdall. Every app created has its own 'Client ID'; this 'Client ID,' in most cases, is used to identify the app in the request.
'Access tokens' are tokens used to provide basic access through Heimdall. They are linked to an app and, to turn on the validation, it is necessary you add an 'Access Token Interceptor.'
It is important to know that Access Token Interceptor requires a Client ID Interceptor
Heimdall is composed of six modules, where three of them are central to the project — Config, API and Gateway —, being built around certain business domains.
Spring Cloud Config is a horizontally scalable centralized configuration service for distributed systems. It uses a pluggable repository layer that currently supports local storage, Git, and Subversion.
In this project, we use native profile which loads config files from the local classpath. You can look into shared directory in Config service resources. Now, when Heimdall-api requests its configuration, Config service responds with shared/application-api.yml.
We built our algorithm on top of Netflix Zuul. We put some steroids on the Zuul Filters and added some criteria to make the routes matching more rigid (like the HTTP Verb on the match). Plus, to manage the request/response and Zuul Filters flow, we applied a message broker (RabbitMQ) to communicate with the API.
To present an easy way to manage the gateway, we implemented an API to make it easier to add new routes, interceptors, rate limit and others things to manipulate the gateway at runtime.
Heimdall can be easily deployed to Heroku clicking on this button:
alternatively, executing the commands:
$ heroku login
$ heroku create
$ git push heroku master
$ heroku openHeimdall is open source, and we appreciate your help. Feel free to contribute.
When contributing to this repository, please first discuss the change you wish to make via issue, email, or any other method with the owners of this repository before making a change.
Please note we have a code of conduct, please follow it in all your interactions with the project.
- Ensure any install or build dependencies are removed before the end of the layer when doing a build.
- Update the README.md with details of changes to the interface. Including new environment variables, exposed ports, useful file locations and container parameters.
- Increase the version numbers in any examples files and the README.md to the new version that this Pull Request would represent. The versioning scheme we use is SemVer.
- You may merge the Pull Request in once you have the sign-off of two other developers, or if you do not have permission to do that, you may request the second reviewer to merge it for you.
Only Heimdall subteam members should create new issues in this repo. If you believe a project should be added within the tracker, please leave a comment on the appropriate "parent" issue, i.e., one of the issues linked below. Moreover, in general, feel free to use comments to ask questions, pitch ideas, or mention updates that need to be made!
There are issues for each of the vision statements: