Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

Akka HTTP microservice example

Join the chat at GitHub license Build Status

Hot update: it's now running on Scala 3!

This project demonstrates the Akka HTTP library and Scala to write a simple REST (micro)service. The project shows the following tasks that are typical for most Akka HTTP-based projects:

  • starting standalone HTTP server,
  • handling file-based configuration,
  • logging,
  • routing,
  • deconstructing requests,
  • unmarshalling JSON entities to Scala's case classes,
  • marshaling Scala's case classes to JSON responses,
  • error handling,
  • issuing requests to external services,
  • testing with mocking of external services.

The service in the template provides two REST endpoints - one which gives GeoIP info for given IP and another for calculating geographical distance between given pair of IPs. The project uses the service ip-api which offers JSON IP and GeoIP REST API for free for non-commercial use.

If you want to read a more thorough explanation, check out tutorial.

Deploy to Heroku Gitpod Ready-to-Code


Start services with sbt:

$ sbt
> ~reStart

With the service up, you can start sending HTTP requests:

$ curl http://localhost:9000/ip/
  "city": "Mountain View",
  "query": "",
  "country": "United States",
  "lon": -122.0881,
  "lat": 37.3845
$ curl -X POST -H 'Content-Type: application/json' http://localhost:9000/ip -d '{"ip1": "", "ip2": ""}'
  "distance": 4347.624347494718,
  "ip1Info": {
    "city": "Mountain View",
    "query": "",
    "country": "United States",
    "lon": -122.0881,
    "lat": 37.3845
  "ip2Info": {
    "city": "Norwell",
    "query": "",
    "country": "United States",
    "lon": -70.8228,
    "lat": 42.1508


Execute tests using test command:

$ sbt
> test

Author & license

If you have any questions regarding this project, contact:

Łukasz Sowa from Iterators.

For licensing info see LICENSE file in project's root directory.