servant-elm: Automatically derive Elm functions to query servant webservices.

[ bsd3, library, web ] [ Propose Tags ]

Please see README.md


[Skip to Readme]
Versions [faq] 0.1.0.0, 0.1.0.1, 0.1.0.2, 0.2.0.0, 0.3.0.0, 0.3.0.1, 0.4.0.0, 0.4.0.1, 0.5.0.0, 0.6.0.0, 0.6.0.1, 0.6.0.2, 0.6.1, 0.7.0, 0.7.1
Change log CHANGELOG.md
Dependencies base (>=4.7 && <5), elm-export, lens, servant (==0.5.*), servant-foreign (==0.5.*), text [details]
License BSD-3-Clause
Copyright 2015-2016 Matt Bray
Author Matt Bray
Maintainer mattjbray@gmail.com
Category Web
Home page http://github.com/mattjbray/servant-elm#readme
Source repo head: git clone https://github.com/mattjbray/servant-elm
Uploaded by mattjbray at Fri Mar 11 20:04:16 UTC 2016
Distributions LTSHaskell:0.5.0.0, NixOS:0.7.1, Stackage:0.5.0.0
Downloads 3662 total (356 in the last 30 days)
Rating (no votes yet) [estimated by rule of succession]
Your Rating
  • λ
  • λ
  • λ
Status Hackage Matrix CI
Docs uploaded by user [build log]
All reported builds failed as of 2016-03-11 [all 1 reports]

Modules

[Index]

Downloads

Maintainer's Corner

For package maintainers and hackage trustees


Readme for servant-elm-0.1.0.2

[back to package description]

Servant Elm

Build Status

Generate Elm functions to query your Servant API!

Elm type generation coutesy of krisajenkins/elm-export.

Installation

Until elm-export and servant >= 0.5 are released, servant-elm requires stack. Add this to your stack.yaml file:

...
packages:
  ...
- location:
    git: https://github.com/haskell-servant/servant.git
    commit: 761443fffecbe83aa408d5f705dd0a8dade08af9
  subdirs:
  - servant
  - servant-foreign
  - servant-server
  extra-dep: True
- location:
    git: https://www.github.com/mattjbray/elm-export
    commit: a8a5b61798fbb04e081f5c83cab76ceaabc5ba13
  extra-dep: True
- location:
    git: https://www.github.com/mattjbray/servant-elm
    commit: 749e09ed9d623284b3b90d1ae1ccba7ae79ad381
  extra-dep: True
...

Example

Let's get some language pragmas and imports out of the way.

{-# LANGUAGE DataKinds     #-}
{-# LANGUAGE DeriveGeneric #-}
{-# LANGUAGE TypeOperators #-}

import           GHC.Generics (Generic)
import           Servant.API  ((:>), Capture, Get, JSON)
import           Servant.Elm  (Proxy (Proxy), Spec (Spec), ToElmType,
                               defElmImports, generateElmForAPI, specsToDir,
                               specsToDir)

We have some Haskell-defined types and our Servant API.

data Book = Book
  { name :: String
  } deriving (Generic)

instance ToElmType Book

type BooksApi = "books" :> Capture "bookId" Int :> Get '[JSON] Book

Now we can generate Elm functions to query the API:

spec :: Spec
spec = Spec ["Generated", "MyApi"]
            (defElmImports
             : generateElmForAPI (Proxy :: Proxy BooksApi))

main :: IO ()
main = specsToDir [spec] "my-elm-dir"

Let's save this as example.hs and run it:

$ stack runghc example.hs
Writing: my-elm-dir/Generated/MyApi.elm
$

Here's what was generated:

module Generated.MyApi where

import Json.Decode exposing ((:=))
import Json.Decode.Extra exposing ((|:))
import Json.Encode
import Http
import String
import Task


type alias Book =
  { name : String
  }

decodeBook : Json.Decode.Decoder Book
decodeBook =
  Json.Decode.succeed Book
    |: ("name" := Json.Decode.string)

getBooksBy : Int -> Task.Task Http.Error (Book)
getBooksBy bookId =
  let
    request =
      { verb =
          "GET"
      , headers =
          [("Content-Type", "application/json")]
      , url =
          "/" ++ "books"
          ++ "/" ++ (bookId |> toString |> Http.uriEncode)
      , body =
          Http.empty
      }
  in
    Http.fromJson
      decodeBook
      (Http.send Http.defaultSettings request)

See examples for a complete usage example, or take a look at mattjbray/servant-elm-example-app for an example project using this library.

Development

$ git clone https://github.com/mattjbray/servant-elm.git
$ cd servant-elm
$ stack build
$ stack test

TODO

Servant API coverage:

  • MatrixFlag / MatrixParam / MatrixParams
  • Header (request)
  • Headers (response)
  • Delete / Patch / Put / Raw
  • Vault / RemoteHost / IsSecure

Other:

  • Encode captures and query params?
  • Option to not use elm-export: generate functions that take a decoder and String arguments.