Java libraries for writing composable microservices
Java CSS HTML Gherkin JavaScript Shell
Clone or download
Permalink
Failed to load latest commit information.
apollo-api-impl [maven-release-plugin] prepare for next development iteration May 15, 2018
apollo-api [maven-release-plugin] prepare for next development iteration May 15, 2018
apollo-bom [maven-release-plugin] prepare for next development iteration May 15, 2018
apollo-core [maven-release-plugin] prepare for next development iteration May 15, 2018
apollo-entity [maven-release-plugin] prepare for next development iteration May 15, 2018
apollo-environment [maven-release-plugin] prepare for next development iteration May 15, 2018
apollo-extra [maven-release-plugin] prepare for next development iteration May 15, 2018
apollo-http-service [maven-release-plugin] prepare for next development iteration May 15, 2018
apollo-route [maven-release-plugin] prepare for next development iteration May 15, 2018
apollo-test [maven-release-plugin] prepare for next development iteration May 15, 2018
examples bump minor version Sep 23, 2016
modules [maven-release-plugin] prepare for next development iteration May 15, 2018
website consistent and modern args input Feb 21, 2016
.gitignore initial import Nov 17, 2015
CONTRIBUTING.md Removed CHANGELOG file and updated CONTRIBUTING guidelines Nov 23, 2015
DEPLOYING.md Update DEPLOYING.md Feb 29, 2016
LICENSE.txt Add license files in all modules Nov 17, 2015
NOTICE.txt Add license files, first take Nov 17, 2015
README.md Update README.md Apr 27, 2016
circle.yml switch to codecov.io for coverage reporting Apr 27, 2016
pom.xml [maven-release-plugin] prepare for next development iteration May 15, 2018

README.md

Apollo

Circle Status Codecov Maven Central License

Apollo is a set of Java libraries that we use at Spotify when writing microservices. Apollo includes modules such as an HTTP server and a URI routing system, making it trivial to implement restful API services.

Apollo has been used in production at Spotify for a long time. As a part of the work to release version 1.0.0 we are moving the development of Apollo into the open. Please note that the API and documentation might change prior to the stable 1.0.0 open source release.

There are three main libraries in Apollo:

Apollo HTTP Service

The apollo-http-service library is a standardized assembly of Apollo modules. It incorporates both apollo-api and apollo-core and ties them together with other modules to get a standard api service using http for incoming and outgoing communication.

Apollo API

The apollo-api library is the Apollo library you are most likely to interact with. It gives you the tools you need to define your service routes and your request/reply handlers.

Here, for example, we define that our service will respond to a GET request on the path / with the string "hello world":

public static void init(Environment environment) {
  environment.routingEngine()
      .registerAutoRoute(Route.sync("GET", "/", requestContext -> "hello world"));
}

Note that, for an Apollo-based service, you can see the routes defined for a service by querying /_meta/0/endpoints.

The apollo-api library provides several ways to help you define your request/reply handlers. You can specify how responses should be serialized (such as JSON). Read more about this library in the Apollo API Readme.

Apollo Core

The apollo-core library manages the lifecycle (loading, starting, and stopping) of your service. You do not usually need to interact directly with apollo-core; think of it merely as "plumbing". For more information about this library, see the Apollo Core Readme.

Apollo Test

In addition to the three main Apollo libraries listed above, to help you write tests for your service we have an additional library called apollo-test. It has helpers to set up a service for testing, and to mock outgoing request responses.

Getting Started with Apollo

Apollo will be distributed as a set of Maven artifacts, which makes it easy to get started no matter the build tool; Maven, Ant + Ivy or Gradle. Below is a very simple but functional service — more extensive examples are available in the examples directory. Until these are released, you can build and install Apollo from source by running mvn install.

public final class App {

    public static void main(String... args) throws LoadingException {
        HttpService.boot(App::init, "my-app", args);
    }

    static void init(Environment environment) {
        environment.routingEngine()
            .registerAutoRoute(Route.sync("GET", "/", rc -> "hello world"));
    }
 }

Links

Introduction Website
JavaDocs
Maven site

Diagrams

Apollo set-up

Apollo in runtime

Code of conduct

This project adheres to the Open Code of Conduct. By participating, you are expected to honor this code.