Category:

The Problem

A result of migrating our monolithic system towards microservices in the last couple of years is 20+ internal services (so far). Many of these services lacked great API documentation, the kind where our developers could easily grasp all endpoints, behaviours, and error codes. We needed three things for our API documentation: a common and easy way to document each endpoint of every service, a centralized location to access all this documentation, and a way to automatically update after changes to an endpoint. Swagger to the rescue.

Swagger

swagger

Swagger is a specification and complete framework implementation for describing, producing, consuming, and visualizing RESTful web services. It also comes with Swagger UI, a great documentation viewer for endpoints. It lists endpoints and details of each one, and also provides a UI that can actually run test queries against test servers. Another bonus is that Swagger documentation is done with annotations in source code and so reduces overhead of managing multiple document sources. Sounds good!

  • Swagger documentation library for Play framework? Check.
  • Swagger documentation library for arbitrary Java web apps? Check.
  • Swagger documentation for endpoints in general for Scala? Nope.
sbt-swagger

No Swagger for Scala endpoints? OK, let’s help. We made sbt-swagger Scala Library as an SBT plugin. Our sbt-swagger sbt plugin generates swagger-ui compatible JSON data based on the Swagger & JAX-RS (jsr311) annotations in your code. Any Scala applications that provide APIs can benefit from this plugin.

Today, we released it as open source. We have been using sbt-swagger in our products for documenting, exclusively for our internal Scala microservice component that provides our internal protocol over ZeroMQ.

Using sbt-swagger

Three steps:

  1. Add sbt-swagger config/dependency in your SBT build file
  2. Add docs in your Scala code with JAX-RS (jsr311) annotations
  3. run sbt swagger
Read More …

At Hootsuite, we process millions of social messages every day. We strive to keep our service stable and secure, and rely on open source projects such as Scala and Akka to achieve our goals. We are excited to contribute back to the community today with a Redis plugin for Akka Persistence.

So what is Akka and how is it useful? Akka provides means to make a distributed system scalable, asynchronous, and fault-tolerant. It achieves this by sending messages among lightweight processes called actors. These actors only communicate through Akka’s message delivery mechanism such as mailboxes and certain level of delivery guarantee. This allows developers to concentrate on actor behaviours, and not on message delivery. This is certainly the use case at Hootsuite. Most of the time, we focus on defining actors and trust Akka to deliver those millions of messages.

New Redis plugin for Akka Persistence
New Redis plugin for Akka Persistence

Read More …