Facia's Scala client is split into two parts.

The fapi-client project contains the main Fronts API client. This provides ways to fetch Fronts data and includes high-level logic to convert Facia's low-level internal data structures into more easily-used types.

Add the following line to your SBT build file:

libraryDependencies += "com.gu" %% "fapi-client-play30" % "x.y.z"

To use the Fronts API client you will need instances of:

• the content API client
• the underlying Facia JSON library

These instances will need to be configured with your access/API keys. The FAPI class contains the public interface to the behaviour in the library. Examples of how to use the client can be found in the demo.sc file, an IntelliJ worksheet.

The low-level Facia API client is designed to fetch and manipulate Facia's internal JSON structures. This library provides underlying behaviour for the main Fronts API client.

Add the following line to your SBT build file:

libraryDependencies += "com.gu" %% "facia-json-play26" % "3.3.3"

ApiClient.config

Returns the current config.

ApiClient.collection("id goes here")

Returns the collection with the given ID.

To run the tests you need to pass a content api key and facia client target url to the library via your environment.

export CONTENT_API_KEY="<api-key>"
export FACIA_CLIENT_TARGET_URL="<target-url>"
sbt test

Before releasing, consider whether your changes are likely to be backwards-compatible with older versions of the client -- for example, if the new version introduces new serialisations that old versions won't be able to read. Where possible, we should aim to maintain backwards compatibility.

At the time of writing, Tools, CAPI, Dotcom, Mobile teams (Mapi) and Ophan all use facia-scala-client -- take care to understand who is using the library and communicate changes where appropriate. In particular remember the Apple News feed uses this client, we've forgotten that twice before.

This project uses the gha-scala-library-release-workflow to release to Maven Central. To release a new version, execute the Release workflow in the Actions tab on GitHub:

You'll need to refresh the page to see the new workflow run.