0
# Http4s DSL
1

2
Http4s DSL provides a simple, expressive domain-specific language for building HTTP services in Scala. It offers idiomatic Scala constructs for handling HTTP requests and responses, including pattern matching on request methods, paths, and query parameters. The DSL enables developers to write clean, composable HTTP route definitions using familiar Scala syntax.
3

4
## Package Information
5

6
- **Package Name**: org.http4s:http4s-dsl_3
7
- **Package Type**: maven
8
- **Language**: Scala 3
9
- **Installation**: `libraryDependencies += "org.http4s" %% "http4s-dsl" % "0.23.30"`
10

11
## Core Imports
12

13
```scala
14
import org.http4s.dsl.io._
15
import cats.effect.IO
16
```
17

18
For other effect types:
19

20
```scala
21
import org.http4s.dsl.Http4sDsl
22
// Create instance for your effect type F[_]
23
val dsl = Http4sDsl[F]
24
import dsl._
25
```
26

27
For effect-agnostic imports (request-only DSL):
28

29
```scala
30
import org.http4s.dsl.request._
31
```
32

33
## Basic Usage
34

35
```scala
36
import org.http4s.dsl.io._
37
import org.http4s.HttpRoutes
38
import cats.effect.IO
39

40
val routes = HttpRoutes.of[IO] {
41
  // Simple GET route
42
  case GET -> Root / "hello" => 
43
    Ok("Hello, World!")
44
    
45
  // Path parameter extraction
46
  case GET -> Root / "users" / IntVar(userId) =>
47
    Ok(s"User ID: $userId")
48
    
49
  // Query parameter extraction
50
  case GET -> Root / "search" :? QueryParam("q", query) =>
51
    Ok(s"Search query: $query")
52
    
53
  // Multiple HTTP methods
54
  case req @ (GET | POST) -> Root / "api" / "data" =>
55
    req.method match {
56
      case GET => Ok("Getting data")
57
      case POST => Ok("Creating data")
58
    }
59
}
60
```
61

62
## Architecture
63

64
The http4s DSL is built around several key components:
65

66
- **Pattern Matching**: Uses Scala extractors for declarative route matching
67
- **Path Extractors**: Composable operators for URL path decomposition (`/`, `Root`, path variables)
68
- **Query Parameter Matchers**: Type-safe query parameter extraction and validation
69
- **Response Generators**: Fluent API for creating HTTP responses with proper status codes
70
- **Effect Type Polymorphism**: Works with any effect type `F[_]` with appropriate type class instances
71

72
## Capabilities
73

74
### HTTP Methods
75

76
Standard HTTP method constants for pattern matching in routes.
77

78
```scala { .api }
79
val GET: Method.GET.type
80
val POST: Method.POST.type
81
val PUT: Method.PUT.type
82
val DELETE: Method.DELETE.type
83
val HEAD: Method.HEAD.type
84
val OPTIONS: Method.OPTIONS.type
85
val PATCH: Method.PATCH.type
86
val CONNECT: Method.CONNECT.type
87
val TRACE: Method.TRACE.type
88
```
89

90
[HTTP Methods](./http-methods.md)
91

92
### Path Matching and Extraction
93

94
Powerful path decomposition and parameter extraction system for building REST APIs with type-safe URL routing.
95

96
```scala { .api }
97
val Root: Uri.Path.Root.type
98
val / : impl./.type
99
val -> : impl.->.type
100
val IntVar: impl.IntVar.type
101
val LongVar: impl.LongVar.type
102
val UUIDVar: impl.UUIDVar.type
103
```
104

105
[Path Matching](./path-matching.md)
106

107
### Response Generation
108

109
Complete HTTP status code constants and response builders for creating well-formed HTTP responses.
110

111
```scala { .api }
112
// Success responses
113
val Ok: Status.Ok.type
114
val Created: Status.Created.type
115
val NoContent: Status.NoContent.type
116

117
// Client error responses  
118
val BadRequest: Status.BadRequest.type
119
val NotFound: Status.NotFound.type
120
val Unauthorized: Status.Unauthorized.type
121

122
// Server error responses
123
val InternalServerError: Status.InternalServerError.type
124
val ServiceUnavailable: Status.ServiceUnavailable.type
125
```
126

127
[Response Generation](./response-generation.md)
128

129
## Types
130

131
### Core DSL Types
132

133
```scala { .api }
134
trait Http4sDsl[F[_]] extends Http4sDsl2[F, F] with RequestDsl {
135
  val liftG: FunctionK[F, F]
136
}
137

138
trait RequestDsl extends Methods with Auth {
139
  type Path = Uri.Path
140
  type Root = Uri.Path.Root.type
141
  type MethodConcat = impl.MethodConcat
142
  
143
  // Path extractors
144
  val Path: Uri.Path.type
145
  val Root: Uri.Path.Root.type
146
  val / : impl./.type
147
  val :? : impl.:?.type
148
  val ~ : impl.~.type
149
  val -> : impl.->.type
150
  val /: : impl./:.type
151
  val +& : impl.+&.type
152
  
153
  // Variable extractors
154
  val IntVar: impl.IntVar.type
155
  val LongVar: impl.LongVar.type
156
  val UUIDVar: impl.UUIDVar.type
157
}
158
```
159

160
### Method Combination
161

162
```scala { .api }
163
class MethodConcat(val methods: Set[Method]) {
164
  def unapply(method: Method): Option[Method]
165
}
166

167
// Extension methods for combining HTTP methods
168
implicit class MethodOps(val method: Method) extends AnyVal {
169
  def |(another: Method): MethodConcat
170
}
171

172
implicit class MethodConcatOps(val methods: MethodConcat) extends AnyVal {
173
  def |(another: Method): MethodConcat  
174
}
175
```
176

177
### Pattern Matching Extractors
178

179
```scala { .api }
180
// Query parameter extractor
181
object :? {
182
  def unapply[F[_]](req: Request[F]): Some[(Request[F], Map[String, collection.Seq[String]])]
183
}
184

185
// Method and path extractor  
186
object -> {
187
  def unapply[F[_]](req: Request[F]): Some[(Method, Path)]
188
}
189

190
// Path segment extractor
191
object / {
192
  def unapply(path: Path): Option[(Path, String)]
193
}
194

195
// File extension extractor
196
object ~ {
197
  def unapply(path: Path): Option[(Path, String)]
198
  def unapply(fileName: String): Option[(String, String)]
199
}
200
```