# HTTP API

`HttpApi` lets you describe an HTTP API **once**, as a tree of typed endpoints,
and then derive everything else from that single definition:

- a **server** that validates requests and encodes responses against your schemas,
- a **typed client** whose method signatures mirror your endpoints exactly, and
- **OpenAPI** documentation (Scalar or Swagger UI) generated from the same source.

Because the definition is built from [Schema](https://effect.plants.sh/schema/), every payload, path
parameter, query value, response and error is decoded and encoded at runtime and
checked end-to-end at compile time. Rename an endpoint or change a field and both
the server handlers and the client call sites stop compiling until you fix them.

## The shape of an HttpApi

An API is composed of **endpoints**, grouped into **groups**, combined into a
single **`HttpApi`**:

```ts
import { Schema } from "effect"
import { HttpApi, HttpApiEndpoint, HttpApiGroup } from "effect/unstable/httpapi"

// A group bundles related endpoints under a common path prefix
class UsersGroup extends HttpApiGroup.make("users")
  .add(
    // GET /users/:id -> 200 with a decoded `name`
    HttpApiEndpoint.get("getById", "/:id", {
      params: { id: Schema.FiniteFromString },
      success: Schema.Struct({ id: Schema.Number, name: Schema.String })
    })
  )
  .prefix("/users")
{}

// The root API combines all groups. This value is shared by server and client.
class Api extends HttpApi.make("acme-api").add(UsersGroup) {}
```

The `Api` value is the contract. The server implements it, the client consumes
it, and the OpenAPI generator documents it — all from this one declaration.
**Tip:** Keep your API **definitions** in a separate file (ideally a separate package)
from your server **implementation**. The definition is shared with clients, and
you never want server-only code leaking into a browser bundle.

## Where to next
**Defining APIs**
Describe groups, endpoints, path params, queries, payloads, responses and
    errors. [Read more](https://effect.plants.sh/http-api/defining-apis/)

**Handlers**
Implement each endpoint with full access to [services and
    Layers](https://effect.plants.sh/services-and-layers/). [Read more](https://effect.plants.sh/http-api/handlers/)

**Middleware & auth**
Secure endpoints, inject the current user, and define security schemes.
    [Read more](https://effect.plants.sh/http-api/middleware-and-auth/)

**Serving & clients**
Serve the API and call it with a generated, fully typed client.
    [Read more](https://effect.plants.sh/http-api/serving-and-clients/)

**OpenAPI**
Generate an OpenAPI spec and interactive docs from the definition.
    [Read more](https://effect.plants.sh/http-api/openapi/)

The pages that follow build up the same example API incrementally. If you want
the lower-level request/response building blocks instead, see the
[HTTP Client](https://effect.plants.sh/http-client/) section and the [Platform](https://effect.plants.sh/platform/) HTTP server
primitives.