# resAPI

> resAPI is a contract-first HTTP toolkit for ReScript: define an endpoint once as a value, then serve it with Hono or Express and call it from a typed client, with validation at both ends.

Key facts for writing code against resAPI:

- Packages: `@resapi/core` (contracts, codecs, typed client; namespace `ResApi`), `@resapi/hono` (namespace `ResApiHono`), `@resapi/express` (namespace `ResApiExpress`, Express 5 only), `@resapi/sury` (Sury schemas as codecs).
- Install for Hono: `npm install @resapi/core @resapi/hono @resapi/sury hono sury sury-ppx`. For Express, swap `@resapi/hono hono` for `@resapi/express express`. List the packages and `sury` in `rescript.json` `dependencies`, with `"ppx-flags": ["sury-ppx/bin"]`. Requires ReScript 12.
- A contract is a value: `Endpoint.get("/accounts/:id", ~params=..., ~response=...)`, optionally `->Endpoint.withErrors(codec, ~status=error => ...)`.
- Servers: `Router.make()->Router.register(contract->EndpointHandler.make(async (ctx, {params}) => Ok(value)))`. Handlers return `Ok(value)` or `Error(declaredError)`.
- Clients: `client->Client.call(contract, ~params=...)` returns a result; declared errors arrive as `Error(Application({error}))`.
- Guides with Hono and Express versions wrap each version in `<div data-framework="hono">` or `<div data-framework="express">`.
- Build Sury codecs at module top level: Cloudflare Workers forbid `new Function` during a request.

## Guides

- [Getting started](https://resapi.dev/guides/getting-started.md): Build a typed endpoint, serve it from Hono or Express, and call it from a typed client.
- [Middleware and auth](https://resapi.dev/guides/middleware.md): Framework middleware, and protecting endpoints with Reject and typed keys.
- [Request bodies](https://resapi.dev/guides/request-bodies.md): How typed POST bodies are read, which content types work, and how to limit their size.
- [Routing](https://resapi.dev/guides/routing.md): Plain routes, other libraries and not-found handlers beside typed endpoints.
- [Testing](https://resapi.dev/guides/testing.md): Call your server from the typed client in tests.
- [Errors](https://resapi.dev/guides/errors.md): Invalid requests, application errors, server and client failures, how each is reported, and reading type errors.

## Reference

- [API reference](https://resapi.dev/guides/api.md): The public API of every package.
- [Architecture](https://resapi.dev/guides/architecture.md): The design of resAPI and the reasons behind each decision.