Skip to content

api-reference.md

Latest commit

 

History

History
87 lines (65 loc) · 8.55 KB

api-reference.md

File metadata and controls

87 lines (65 loc) · 8.55 KB
Raw

API Reference

Documentation home · Getting started · Browser fixtures · Challenge fixtures

BTLR HTTP exposes versionless fixture paths for familiar HTTP diagnostics and namespaced /browser and /challenge surfaces for specialized behavior. /docs provides a comprehensive running-service guide, while /openapi.json provides the generated machine-readable OpenAPI 3.1 contract for documented public operations. Catch-all /anything routes accept additional methods through their documented any-method behavior.

Response conventions

  • Diagnostic JSON normally uses request, response, and meta sections.
  • Errors use a structured application error with a stable code and request ID.
  • Direct browser navigation receives indented JSON when whitespace does not affect the fixture contract; programmatic clients receive compact JSON.
  • Bodyless, encoded, streamed, fixed-length, shared-cacheable, validator-bearing, attachment, and HEAD responses remain wire-accurate.
  • Sensitive headers and cookies are redacted unless an explicit synthetic-only echo mode is documented.
  • Resource-intensive routes use hard bounds and route-class rate policies.

Route families

Family Routes Detailed contract
System /, /docs, /openapi.json, /health, /version System endpoints
Request methods /anything, /anything/*, /get, /post, /put, /patch, /delete Request diagnostics
Request metadata and cookies /headers, /ip, /user-agent, /cookies, /cookies/set, /cookies/delete Request diagnostics
Status and safe headers /status/:codes, /response-headers Status and headers
Redirects /redirect/:count, /relative-redirect/:count, /absolute-redirect/:count, /redirect-to, /redirect-loop, /malformed-redirect/:kind Redirects
Body formats /json, /xml, /html, /robots.txt, /encoding/utf8, /base64/:value, /bytes/:count, /stream-bytes/:count Body formats
Authentication /basic-auth/:user/:password, /bearer, /auth/forbidden, /proxy-auth, /digest-auth/* Authentication
Negotiation and methods /negotiate/accept, /negotiate/language, /negotiate/content-type, /protocol/methods, /protocol/cors, /protocol/early-hints, /protocol/early-hints.css Protocol and negotiation
Compression /gzip, /deflate, /brotli Compression and caching
Caching and validators /cache, /cache/:seconds, /etag/:etag, /last-modified/:timestamp Compression and caching
Timing and streams /delay/:seconds, /drip, /stream/:count Timing and streaming
Ranges /range/:bytes Timing and streaming
Browser documents and fixture APIs /browser/*, /api/fixtures/* Browser fixtures
Controlled challenges /challenge/* Challenge fixtures

Choose a fixture

flowchart TD
    Need["What do you need to prove?"]
    Need -->|"Request parsing or redaction"| Inspect["Request diagnostics"]
    Need -->|"HTTP response semantics"| Response["Status · redirects · formats · cache · streams"]
    Need -->|"Rendered browser behavior"| Browser["Browser fixtures"]
    Need -->|"Challenge detection or completion"| Challenge["Controlled challenges"]
    Inspect --> OpenAPI["/docs or /openapi.json"]
    Response --> OpenAPI
    Browser --> Selectors["Stable selectors + completion marker"]
    Challenge --> Synthetic["Synthetic, signed, bounded state"]
Loading

Request inspection example

curl -X POST \
  -H 'Content-Type: application/json' \
  --data '{"client":"curl","safe":true}' \
  'http://localhost:8787/post?tag=one&tag=two'

The response reports the method, resolved URL, repeated query values, selected redacted headers, cookies, and bounded parsed body details. The service does not persist the request.

Browser automation contract

Every documented browser fixture sets these attributes on <body>:

Attribute Meaning
data-fixture-id Stable fixture identifier
data-fixture-version Fixture schema version
data-fixture-complete false while pending; true at the documented final state

Controls use stable data-testid selectors. See browser fixtures for capability-specific behavior and testing for Playwright coverage.

Limits and errors

Important shared ceilings include a 1 MiB inspected request body, 256 KiB generated or range body, 10 redirects, 10 seconds of delay, 100 stream items, 8 KiB query and normalized header values, 64 normalized headers, and a 10-minute maximum session. Individual routes often use smaller bounds, and response-producing routes document their own output bounds rather than relying on a single global response-size gate.

Validation, method, policy, and rate-limit failures return safe structured errors. Endpoint-family guides emphasize semantics, examples, important route-specific errors, and boundary values; /openapi.json supplies the generated operation schemas. The security guide contains the authoritative threat model and abuse controls.

Contract sources

The public contract is maintained in three complementary forms:

  1. Route definitions and schemas generate /openapi.json.
  2. Endpoint-family guides explain semantics, limits, examples, and platform caveats.
  3. Integration, contract, wire, and browser tests prove behavior at the relevant runtime boundary.

Integration tests compare concretely registered named methods and routes with OpenAPI so undocumented named operations fail validation. Catch-all any-method behavior is tested separately.