Voter Service

Introduction

The Voter Spring Boot RESTful Web Service, backed by MongoDB, is used for DevOps-related training and testing. The Voter service exposes several HTTP API endpoints, listed below. API users can review a static list candidates (based on the 2016 US Presidential Election), submit a vote, view voting results, and inspect technical information about the running service. API users can also create random voting data by calling the /simulation endpoint.

Quick Start for Local Development

The Voter service requires MongoDB to be pre-installed and running locally, on port 27017. The service will create the voters database on startup. To clone, build, test, and run the Voter service locally:

git clone --depth 1 --branch master \
  https://github.com/ThoughtWorksInc/voter-service.git
cd voter-service
./gradlew clean cleanTest build
java -jar build/libs/voter-service-0.2.0.jar

Getting Started with the API

The easiest way to get started with the Voter service API, using HTTPie from the command line:

1. View a list of candidates: http http://localhost:8099/candidates
2. Create sample voter data: http http://localhost:8099/simulation
3. View sample voter results: http http://localhost:8099/results

Service Endpoints

By default, the service runs on localhost, port 8099. By default, the service looks for MongoDB on localhost, port 27017.

Purpose	Method	Endpoint
Create Random Sample Data	GET	/simulation
List Candidates	GET	/candidates
Submit Vote	POST	/votes
View Voting Results	GET	/results
View Total Votes	GET	/results/votes
View Winner(s)	GET	/winners
View Winning Vote Count	GET	/winners/votes
Service Info	GET	/info
Service Health	GET	/health
Service Metrics	GET	/metrics
Other Spring Actuator endpoints	GET	/actuator, /mappings, /env, /configprops, etc.
Other HATEOAS endpoints for /votes	Various	DELETE, PATCH, PUT, page sort, size, etc.

The HAL Browser API browser for the hal+json media type is installed alongside the service. It can be accessed at http://localhost:8099/actuator/.

Voting

Submitting a new vote, requires an HTTP POST request to the /votes endpoint, as follows:

HTTPie

http POST http://localhost:8099/votes candidate="Jill Stein"

cURL

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{ "candidate": "Jill Stein" }' \
  "http://localhost:8099/votes"

wget

wget --method POST \
  --header 'content-type: application/json' \
  --body-data '{ "candidate": "Jill Stein" }' \
  --no-verbose \
  --output-document - http://localhost:8099/votes

Sample Output

Using HTTPie command line HTTP client.

http http://localhost:8099/simulation

{
    "message": "simulation data created"
}

http http://localhost:8099/candidates

{
    "candidates": [
        "Chris Keniston",
        "Darrell Castle",
        "Donald Trump",
        "Gary Johnson",
        "Hillary Clinton",
        "Jill Stein"
    ]
}

http http://localhost:8099/results

{
    "results": [
        {
            "candidate": "Gary Johnson",
            "votes": 20
        },
        {
            "candidate": "Hillary Clinton",
            "votes": 15
        },
        {
            "candidate": "Donald Trump",
            "votes": 11
        },
        {
            "candidate": "Jill Stein",
            "votes": 8
        },
        {
            "candidate": "Chris Keniston",
            "votes": 3
        },
        {
            "candidate": "Darrell Castle",
            "votes": 2
        }
    ]
}

http http://localhost:8099/results/votes

{
    "votes": 59
}

http http://localhost:8099/winners

{
    "results": [
        {
            "candidate": "Gary Johnson",
            "votes": 20
        }
    ]
}

http http://localhost:8099/winners/votes

{
    "votes": 20
}

http POST http://localhost:8099/votes candidate="Jill Stein"

{
    "_links": {
        "self": {
            "href": "http://localhost:8099/votes/5872f388a6e0de7595dd22ac"
        },
        "vote": {
            "href": "http://localhost:8099/votes/5872f388a6e0de7595dd22ac"
        }
    },
    "candidate": "Jill Stein"
}

Continuous Integration

The project's source code is continuously built and tested on every commit to GitHub, using Travis CI. If all unit tests pass, the resulting Spring Boot JAR is pushed to the artifacts branch of the ThoughtWorksInc/voter-service GitHub repository. The JAR's filename is incremented with each successful build (i.e. voter-service-0.2.10.jar).

Spring Profiles

The Voter service includes (3) Spring Boot Profiles, in a multi-profile YAML document: src/main/resources/application.yml. The profiles are default, aws-production, and docker-production. You will need to ensure your MongoDB instance is available at that host address and port of the profile you choose, or you may override the profile's properties.

server:
  port: 8099
spring:
  data:
    mongodb:
      host: localhost
      port: 27017
      database: voters
logging:
  level:
    root: INFO
info:
  java:
    source: ${java.version}
    target: ${java.version}
management:
  info:
    git:
      mode: full
    build:
      enabled: true
---
spring:
  profiles: aws-production
  data:
    mongodb:
      host: 10.0.1.6
logging:
  level:
    root: WARN
management:
  info:
    git:
      enabled: false
    build:
      enabled: false
endpoints:
  sensitive: true
  enabled: false
  info:
    enabled: true
  health:
    enabled: true
---
spring:
  profiles: docker-production
  data:
    mongodb:
      host: mongodb
logging:
  level:
    root: WARN
management:
  info:
    git:
      enabled: false
    build:
      enabled: false
endpoints:
  sensitive: true
  enabled: false
  info:
    enabled: true
  health:
    enabled: true

All profile property values may be overridden on the command line, or in a .conf file. For example, to start the Voter service with the aws-production profile, but override the mongodb.host value with a new host address, you might use the following command:

java -jar <name_of_jar_file> \
  --spring.profiles.active=aws-production \
  --spring.data.mongodb.host=<new_host_address>
  -Djava.security.egd=file:/dev/./urandom

References

• Spring Data MongoDB - Reference Documentation
• Accessing MongoDB Data with REST
• Spring Boot Testing
• Installing Spring Boot applications
• Externalized Configuration
• 2016 Presidential Candidates