0
# HTTP4S DSL
1
2
The http4s-dsl package provides a Domain Specific Language (DSL) for building HTTP services in Scala. It offers intuitive syntax for route definition using pattern matching on HTTP methods and paths, status code generation through named objects, and composable request/response handling with built-in support for content negotiation and entity encoding/decoding.
3
4
## Package Information
5
6
- **Package Name**: http4s-dsl_2.13
7
- **Package Type**: maven
8
- **Language**: Scala
9
- **Installation**: `libraryDependencies += "org.http4s" %% "http4s-dsl" % "0.23.30"`
10
11
## Core Imports
12
13
```scala
14
import org.http4s.dsl.io._
15
```
16
17
For custom effect types:
18
19
```scala
20
import cats.effect.IO
21
import org.http4s.dsl.Http4sDsl
22
23
// Create DSL instance for your effect type
24
val dsl = Http4sDsl[IO]
25
import dsl._
26
```
27
28
## Basic Usage
29
30
```scala
31
import cats.effect.IO
32
import org.http4s._
33
import org.http4s.dsl.io._
34
35
// Define routes using pattern matching
36
val routes = HttpRoutes.of[IO] {
37
case GET -> Root / "hello" =>
38
Ok("Hello, World!")
39
40
case GET -> Root / "users" / IntVar(userId) =>
41
Ok(s"User ID: $userId")
42
43
case POST -> Root / "users" =>
44
Created("User created")
45
46
case req @ POST -> Root / "data" =>
47
req.as[String].flatMap { body =>
48
Ok(s"Received: $body")
49
}
50
}
51
```
52
53
## Architecture
54
55
The http4s-dsl is built around several key components:
56
57
- **Pattern Matching DSL**: Combines HTTP methods and path patterns for route definition
58
- **Status Code Generators**: Type-safe response builders for all HTTP status codes
59
- **Path Extractors**: Pattern matching utilities for URL paths and path variables
60
- **Query Parameter Matchers**: Type-safe query string parsing and validation
61
- **Request Processing**: Utilities for handling request bodies, headers, and authentication
62
- **Response Building**: Fluent API for constructing HTTP responses with proper headers
63
64
## Capabilities
65
66
### HTTP Methods and Route Matching
67
68
Core HTTP method constants and path pattern matching for defining web service routes. Enables clean, readable route definitions using Scala's pattern matching syntax.
69
70
```scala { .api }
71
// HTTP Methods
72
val GET: Method.GET.type
73
val POST: Method.POST.type
74
val PUT: Method.PUT.type
75
val DELETE: Method.DELETE.type
76
val HEAD: Method.HEAD.type
77
val OPTIONS: Method.OPTIONS.type
78
val PATCH: Method.PATCH.type
79
val CONNECT: Method.CONNECT.type
80
val TRACE: Method.TRACE.type
81
82
// Route matching operators
83
val -> : impl.->.type // Method and path matcher
84
val → : impl.->.type // Unicode alias for ->
85
val ->> : impl.->>.type // Method enumeration matcher
86
```
87
88
[HTTP Methods and Routing](./http-methods-routing.md)
89
90
### Path Pattern Matching
91
92
Path construction and variable extraction utilities for URL routing. Provides type-safe path segment matching and variable extraction from URL paths.
93
94
```scala { .api }
95
// Path components
96
val Path: Uri.Path.type
97
val Root: Uri.Path.Root.type
98
val / : impl./.type // Path segment separator
99
100
// Path extractors
101
val /: : impl./:.type // Path head/tail extractor
102
val IntVar: impl.IntVar.type // Integer path variable
103
val LongVar: impl.LongVar.type // Long path variable
104
val UUIDVar: impl.UUIDVar.type // UUID path variable
105
106
// File extensions
107
val ~ : impl.~.type // File extension extractor
108
```
109
110
[Path Pattern Matching](./path-matching.md)
111
112
### HTTP Status Codes and Response Generation
113
114
Complete set of HTTP status codes with fluent response generation API. Each status code provides type-safe methods for creating responses with or without bodies.
115
116
```scala { .api }
117
// 2xx Success responses
118
val Ok: Status.Ok.type
119
val Created: Status.Created.type
120
val Accepted: Status.Accepted.type
121
val NoContent: Status.NoContent.type
122
123
// 3xx Redirection responses
124
val MovedPermanently: Status.MovedPermanently.type
125
val Found: Status.Found.type
126
val SeeOther: Status.SeeOther.type
127
val NotModified: Status.NotModified.type
128
129
// 4xx Client error responses
130
val BadRequest: Status.BadRequest.type
131
val Unauthorized: Status.Unauthorized.type
132
val Forbidden: Status.Forbidden.type
133
val NotFound: Status.NotFound.type
134
135
// 5xx Server error responses
136
val InternalServerError: Status.InternalServerError.type
137
val NotImplemented: Status.NotImplemented.type
138
val ServiceUnavailable: Status.ServiceUnavailable.type
139
```
140
141
[Status Codes and Response Generation](./status-codes-responses.md)
142
143
### Query Parameter Processing
144
145
Type-safe query parameter extraction and validation with support for optional parameters, multi-value parameters, and custom decoders.
146
147
```scala { .api }
148
val :? : impl.:?.type // Query parameter extractor
149
val +& : impl.+&.type // Multiple parameter combinator
150
151
// Query parameter matcher types
152
type QueryParamDecoderMatcher[T]
153
type OptionalQueryParamDecoderMatcher[T]
154
type QueryParamDecoderMatcherWithDefault[T]
155
type ValidatingQueryParamDecoderMatcher[T]
156
type FlagQueryParamMatcher
157
```
158
159
[Query Parameter Processing](./query-parameters.md)
160
161
### Authentication Support
162
163
Authentication context extraction utilities for working with authenticated requests and user context.
164
165
```scala { .api }
166
// Authentication extractor
167
object as {
168
def unapply[F[_], A](ar: AuthedRequest[F, A]): Option[(Request[F], A)]
169
}
170
```
171
172
[Authentication Support](./authentication.md)
173
174
### Pattern Matching Utilities
175
176
Additional utilities for advanced pattern matching in route definitions.
177
178
```scala { .api }
179
// Conjunction extractor for pattern matching combinations
180
object & {
181
def unapply[A](a: A): Some[(A, A)]
182
}
183
```
184
185
## Common Types
186
187
```scala { .api }
188
// Core path types
189
type Path = Uri.Path
190
type Root = Uri.Path.Root.type
191
192
// Method concatenation for multiple method matching
193
type MethodConcat = impl.MethodConcat
194
195
// Response generator base types
196
trait ResponseGenerator {
197
def status: Status
198
}
199
200
trait EntityResponseGenerator[F[_], G[_]] extends ResponseGenerator {
201
def liftG: G ~> F
202
def apply(): F[Response[G]]
203
def apply[A](body: A, headers: Header.ToRaw*): F[Response[G]]
204
}
205
```