guardian / mobile-notifications-api-client

Moved to

Version Matrix

Mobile Notifications API Client

Maven Central Project status

Scala client for the Guardian Mobile Notifications API.

Integrating with your application

Add to build.sbt: libraryDependencies += "" %% "mobile-notifications-client" % "0.6.0"

Configure API Client

Implement HttpProvider trait methods.

This provider will be used by API Client to make an actual calls from your service. Example trait implementation:


object NotificationHttpProvider extends HttpProvider {

  private def extract(response: Response): HttpResponse = {
    if (response.status >= 200 && response.status < 300)
      HttpOk(response.status, response.body)
      HttpError(response.status, response.body)
  override def post(url: String, contentType: ContentType, body: Array[Byte]): Future[HttpResponse] = {
      .withHeaders("Content-Type" -> s"${contentType.mediaType}; charset=${contentType.charset}")

  override def get(url: String): Future[HttpResponse] = WS.url(url).get().map(extract)

Hint: it is recommended to prefix name of this implementation with your application/service/artifact name to avoid name collisions.

Create configured Notifications API Client


val httpProvider = <your http provider instance>
val client = ApiClient(
  host = "", 
  apiKey = "API-KEY", 
  httpProvider = httpProvider, 
  legacyHost = "",
  legacyApiKey = "OLD-API-KEY"

Using client

Sending notification

You have to construct notification payload using one of the case classes from hierarchy and send that object through the wire using ApiClient.send method.

Example: sending Breaking News alert

val payload = BreakingNewsPayload(
  message = "195 countries and nearly 150 world leaders including Barack Obama and Xi Jinping meet in Paris for COP21 UN climate change conference",
  sender = "test sender",
  imageUrl = None,
  thumbnailUrl = None,
  link = ExternalLink("http://mylink"),
  importance = Importance.Major,
  topic = Set(BreakingNewsUk, "environment/climate-change"))


Error handling

If you take a look at ApiClient.send method signature, you can spot its return type:

def send(notificationPayload: NotificationPayload): Future[Either[ApiClientError, Unit]]

If you're interesed in root error cause, you can pattern match on Either's Left side and errors from hierarchy. For instance:

client.send(...).map { case Left(e: CompositeApiError) => ... }

Releasing the library

Because of the incompatibility of the play-json module between version 2.3 and 2.4, a different branch has been created. Each change that has been merged into master MUST be merged into the play-2.4 branch

Once this is done, make sure to run sbt release on both branches