Narcolepsy - A Scala framework for building typesafe API clients

Narcolepsy is a Scala framework to help you build clients for third-party RESTful web services with maximum typesafety and minimal moving parts. Narcolepsy is modelled closely after Squeryl: it provides a typesafe, ORM-like abstraction layer on top of HTTP method-based, resource-oriented web services. As such it works best with APIs which conform closely to the RESTful ideal.

Health warning

Narcolepsy is highly incomplete. Error handling, non-HTTP-based authentication, POST, PUT and HEAD support are all still to come. Apologies - we wanted to release early (not least because SBT doesn't support private GitHub repositories as dependencies). If there is a specific feature you would like to see sooner rather than later, please create a GitHub issue for it.

How Narcolepsy works

Narcolepsy is designed as a framework which you extend and configure on a per-web service basis. An example of a Narcolepsy-based client library is Prestasac, v2 branch, a Scala client for the PrestaShop web service.

The rest of this section coming soon

Who shouldn't use Narcolepsy

Narcolepsy probably isn't for you if any of the following things is true:

• Your target web service is fragile or frequently changing
• You only need to extract a small subset of data from your target web service
• Your target web service is non-RESTful - for example, it is RPC- or SOAP-like

In these cases, we strongly recommend using the excellent Unfiltered Scala toolkit instead of Narcolepsy.

Technologies

Narcolepsy uses Jackson for JSON (un)marshalling, and JAXB for XML (un)marshalling. In theory Narcolepsy can work with any JAXB implementation - it has been tested with the Oracle Glassfish JAXB reference implementation, and also with the Eclipse Foundation's EclipseLink MOXy. A small subset of Narcolepsy's XML functionality is only compatible with MOXy, but this functionality is sandboxed in the moxy sub-package.

Although we write our binding classes for Typesafe mode in Scala, Jackson and JAXB are pure-Java technologies, so writing your bindings in Java (or generating them using e.g. xjc) should work fine as well.

By default Narcolepsy uses the Apache HttpComponents HttpClient for HTTP communication with the target web service. However, Narcolepsy has been designed so that HttpClient can be swapped out for an alternative 'adapter' at the point of configuring your Narcolepsy-based client library. We plan on bundling a second adapter for spray-client in due course.

License

Like its main component technologies, Narcolepsy is licensed under the Apache License, Version 2.0.