servant-hateoas: HATEOAS extension for servant

[ bsd3, hateoas, library, rest, servant, web ] [ Propose Tags ]

Create Resource-Representations for your types and make your API HATEOAS-compliant. Resource construction is generic where possible and manually adjustable where required. Currently HAL+JSON is the only supported Content-Type, work for more is in progress. The ultimate goal is to generate an entirely HATEOAS-compliant API generically.


[Skip to Readme]

Downloads

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees

Candidates

  • No Candidates
Versions [RSS] 0.1.0, 0.1.1, 0.2.0, 0.2.1
Change log CHANGELOG.md
Dependencies aeson (>=2.2.3 && <2.3), base (>=4.17.2 && <5), http-media (>=0.8.1 && <0.9), servant (>=0.20.2 && <0.21), servant-server (>=0.20.2 && <0.21) [details]
License BSD-3-Clause
Copyright © 2024 Julian Bruder
Author Julian Bruder
Maintainer julian.bruder@outlook.com
Category Servant, Web, REST, HATEOAS
Home page https://github.com/bruderj15/servant-hateoas
Bug tracker https://github.com/bruderj15/servant-hateoas/issues
Uploaded by bruderj15 at 2024-10-29T17:48:42Z
Distributions
Downloads 35 total (35 in the last 30 days)
Rating (no votes yet) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Docs uploaded by user
Build status unknown [no reports yet]

Readme for servant-hateoas-0.2.1

[back to package description]

Hackage Static Badge Haskell-CI

servant-hateoas

HATEOAS support for servant.

State

This is not affiliated with the official servant maintainers.

Currently in infant state. Final goal is something similar to what has been proposed here.

What can we do already?

Define an instance for class ToResource api res a where api is the type of your Servant-Api within which the resty representation of your datatype a lives and res is the resource-representation to create.

When providing some extra information with an instance for Related a there are stock instances which derive the links based on the relations in your instance.

Example

data User = User { usrId :: Int, addressId :: Int, income :: Double }
  deriving stock (Generic, Show, Eq, Ord)
  deriving anyclass ToJSON

data Address = Address { addrId :: Int, street :: String, number :: Int}
  deriving stock (Generic, Show, Eq, Ord)
  deriving anyclass ToJSON

type CompleteApi = AddressApi :<|> UserApi

type AddressApi = AddressGetOne
type AddressGetOne = "address" :> Capture "id" Int :> Get '[HAL JSON] (HALResource Address)

type UserApi = UserGetOne :<|> UserGetAll
type UserGetOne = "user" :> Capture "id" Int :> Get '[HAL JSON] (HALResource User)
type UserGetAll = "user" :> Get '[Collection JSON] (CollectionResource User)

instance Related User where
  type IdSelName User = "usrId"
  type GetOneApi User = UserGetOne
  type CollectionName User = "users"
  type Relations User =
    '[ 'HRel "address" "addressId" AddressGetOne
     ]

>>> mimeRender (Proxy @(HAL JSON)) $ toResource @CompleteApi @HALResource $ User 1 42 100000
{
  "_links": {
    "address": {
      "href": "address/42"
    },
    "self": {
      "href": "user/1"
    }
  },
  "addressId": 42,
  "income": 100000,
  "usrId": 1
}

Goals

  • Deriving simple links for self and relations
  • Deriving links for paging, ...
  • Type-level rewriting of APIs like CompleteAPI to make API HATEOAS-compliant

Media-Types

  • application/hal+json
  • application/collection+json
  • Others: Easily extensible

Client usage with MimeUnrender is not yet supported.

Contact information

Contributions, critics and bug reports are welcome!

Please feel free to contact me through GitHub.