Getting Started

WebGear is a collection of Haskell packages and can be added to your Haskell project just like any other package.

This version of WebGear supports GHC versions from 9.0 till 9.8. WebGear supports both Cabal and Stack. The rest of this guide contains instructions only for Cabal, but they can be adjusted easily for Stack.

First Project

Let's create the customary hello world project using WebGear. First, create a new Haskell project with Cabal:

$ mkdir webgear-tutorial
$ cd webgear-tutorial
$ cabal init --minimal --non-interactive --exe

We'll need a number of language extensions and package dependencies in the cabal file. Edit webgear-tutorial.cabal and add them:

default-extensions:
    Arrows
    DataKinds
    DerivingStrategies
    FlexibleContexts
    GeneralizedNewtypeDeriving
    OverloadedStrings
    QuasiQuotes
    ScopedTypeVariables
    TypeApplications
    TypeOperators

build-depends:
    base,
    http-api-data ==0.6,
    http-types ==0.12.4,
    openapi3 ==3.2.4,
    time,
    wai ==3.2.4,
    warp ==3.4.1,
    webgear-core ==1.3.0,
    webgear-server ==1.3.0,
    webgear-openapi ==1.3.0

Edit app/Main.hs and replace its contents with:

module Main where

import WebGear.Core
import WebGear.Server
import qualified Network.HTTP.Types as HTTP
import qualified Network.Wai as Wai
import qualified Network.Wai.Handler.Warp as Warp

main :: IO ()
main = Warp.run 3000 helloApp

helloApp :: Wai.Application
helloApp = toApplication $
  [route| HTTP.GET /hello |] $
    proc request ->
      respondA HTTP.ok200 PlainText -< "Hello, World!" :: Text

In the above code, WebGear checks if the request method is GET and the request URL is /hello. If both these conditions are met, a request handler is invoked. The handler is implemented as an arrow - hence the use of proc syntax. It ignores the request input and responds with a 200 OK response having a text/plain content type and a Hello, World body.

Tip

If you are unfamiliar with Haskell arrows, you are strongly recommended to go through the Arrows Primer chapter.

Trying It Out

You may launch the API server with:

$ cabal run

And test it with:

$ curl --dump-header - http://localhost:3000/hello
HTTP/1.1 200 OK
Transfer-Encoding: chunked
Date: Wed, 15 May 2024 19:15:46 GMT
Server: Warp/3.4.1
Content-Type: text/plain

Hello, World!

Summary

Congratulations! You've got a basic WebGear application server working. In the next chapter, you'll learn more about routing HTTP requests and handlers.