Home

Awesome

CodelyTV Scala HTTP API

<img src="http://codely.tv/wp-content/uploads/2016/05/cropped-logo-codelyTV.png" align="left" width="192px" height="192px"/> <img align="left" width="0" height="192px" hspace="10"/>

License Build Status Coverage Status

Project showing up how you could implement a HTTP API with Scala.

This is the first iteration of the project where you will find a very Object Oriented approach. We've followed the Ports & Adapters (or Hexagonal Architecture) Software Architecture using traits as the domain contracts/ports in order to be implemented by the infrastructure adapters.

Contents

Endpoints

One of the goals of this project is to serve as an example for the course on Scala HTTP API (Spanish) illustrating how to implement several concepts you would commonly find in any production application. In order to accomplish so, we have implemented the following 5 endpoints:

Libraries and implementation examples

FeatureLibraryImplementation examples
Build toolSBTDependencies, configuration & build.sbt
Style formattingScalaFmtRules
HTTP serverAkka HTTPRoutes definition, server implementation,<br> Video POST controller & its corresponding acceptance test
JSON marshallingSpray JSONUser & User attributes marshallers
Database integrationDoobieVideo repository & its corresponding integration test
Domain events publishingAkka RabbitMQPublisher implementation & its corresponding integration test
Infrastructure managementDockerDocker Compose definition
LoggingScalaLogging<br> + Logback<br> + Logstash encoderLogback configuration, logger implementation & its corresponding integration test
Command line commandScoptDatabase tables creation script
Distribution/deploySBT Native packagerBuild & deploy instructions
Continuous IntegrationTravis CITravis definition
Acceptance testsAkka HTTP TestKitPreviously specified acceptance tests
Integration testsScalaTestPreviously specified integration tests
Unit testsScalaTest<br> + ScalaMockVideo creator use case test
Continuous IntegrationTravis CI<br> + SBT CoverallsTravis definition

Environment setup

Install the needed tools

  1. Clone this repository: git clone https://github.com/CodelyTV/cqrs-ddd-scala-example.git cqrs-ddd-scala-example
  2. Download and install Docker compose. We'll need it in order to run all the project infrastructure.
  3. Download and install SBT

Prepare the application environment

  1. Copy the Docker environment variables config file and tune it with your desired values: cp .env.dist .env
  2. Start Docker and bring up the project needed containers: docker-compose up -d
  3. Create the database tables in your Docker MySQL container: sbt createDbTables

Run the tests and start the HTTP server

  1. Enter into the SBT console: sbt
  2. Run the tests: t
  3. Start the local server: app/run mooc-api (if you run the app from outside SBT: sbt "app/run mooc-api")
  4. Request for the server status: curl http://localhost:8080/status
  5. Take a look at the courses related to this repository (Spanish) just in case you're interested into them!

Pre-push Git hook

There's one Git hook included. It's inside the doc/hooks folder and it will run the prep SBT task before pushing to any remote.

This prep task is intended to run all the checks you consider before pushing. At this very moment, it try to compile and check the code style rules with ScalaFmt.

You can define what this task does modifying the prep task in the build.sbt file. We like the approach of just running 1 single SBT task as the hook instead of multiple tasks because it's more efficient (the hook doesn't have to run SBT multiple times), and also because this way we can control the pre push tasks with the SBT alias defined at the build.sbt without altering the hooks.

In order to install this hook, just cd doc/hooks and run ./install-hooks.sh.

Logs

We've added a logging mechanism thanks to logback and logstash-logback-encoder in order to:

If you want more information on the logging policies and appenders, take a look at the logback.xml.

Deploy

We use SBT Native Packager in order to package the app in single Jar file that you can execute.

  1. Create the universal package: sbt universal:packageBin.
  2. Extract the generated zip: unzip target/universal/codelytv-cqrs-ddd-scala-example-1.0.zip -d ~/var/www/ which will contain:
    • bin/: All the executable binaries of our main classes in Unix and Windows (bat) format
    • lib/: All the project dependencies jar files.
  3. Run the main app binary:
    • Without specifying any parameters (OK for this example app): ~/var/www/codelytv-cqrs-ddd-scala-example-1.0/bin/codelytv-cqrs-ddd-scala-example
    • Specifying parameters for the JVM: ~/var/www/codelytv-cqrs-ddd-scala-example-1.0/bin/codelytv-cqrs-ddd-scala-example -Dconfig.resource=application/$CONFIG_PATH
    • Specifying application parameters: ~/var/www/codelytv-cqrs-ddd-scala-example-1.0/bin/codelytv-cqrs-ddd-scala-example -Dconfig.resource=application/$CONFIG_PATH -- -appParam

About

This hopefully helpful utility has been developed by CodelyTV and contributors.

We'll try to maintain this project as simple as possible, but Pull Requests are welcome!

License

The MIT License (MIT). Please see License for more information.