Sightmap Requests: Routes, Methods, and Payload Shapes

A request assigns a semantic name to an API endpoint. Consumers can show SearchFlights alongside POST /api/flights/search in enriched network output.

- name: SearchFlights
  route: /api/flights/search
  method: POST
  source: src/api/flights.ts
  request:
    fields:
      - name: origin
        type: string
        description: IATA code
      - name: destination
        type: string
        description: IATA code
      - name: departureDate
        type: string
        description: ISO-8601 date
  response:
    fields:
      - name: results
        type: array
  headers: [x-request-id]

name and route are required. See Schema reference for the full type, including the Payload and Field sub-types.

Route patterns

Request routes use the same glob syntax as views: * matches one segment, and ** matches any depth. Express-style :param segments are normalized to *, so these routes are equivalent:

- route: /api/users/:id/orders    # same as below
- route: /api/users/*/orders

Use :param when the application already expresses the route that way. Consumers treat both forms identically.

Method filter

method is an optional, case-insensitive HTTP method filter such as GET, POST, or PUT. If omitted, the definition matches any method.

- name: GetUser
  route: /api/users/:id
  method: GET

- name: UpdateUser
  route: /api/users/:id
  method: PATCH

Definitions may share a route. Conformance fixture 007-request-method-filter verifies that the optional method filters choose the matching definitions.

All matches apply

Requests are matched independently. Every definition whose route matches the URL and whose optional method matches the request method applies.

requests:
  - name: SearchFlights
    route: /api/flights/search    # specific
  - name: AnyFlightsCall
    route: /api/flights/**        # catch-all

A POST /api/flights/search matches both SearchFlights and AnyFlightsCall. Declaration order does not affect request matching.

View matching uses a different rule: exactly one view wins by specificity. See Views.

Payloads are documentary

request and response describe the expected payload shape. Both are Payload objects with an optional fields array. Each field requires a name and may include a free-text type and description. The type value is not restricted to a predefined set. The listed fields are documentary, not exhaustive. They do not validate live request or response payloads. headers lists header names that a consumer may highlight in network details. This example documents the response from a current-user endpoint:

- name: GetCurrentUser
  route: /api/me
  method: GET
  description: Returns the current user, or 401 if unauthenticated
  response:
    fields:
      - name: id
        type: string
      - name: email
        type: string

Scoped vs global

Requests can be declared at the file root or inside a view.

Global requests at the file root are matched on every view.
View-scoped requests are matched only when that view is active.
The two scopes are additive: an active view receives its requests and all global requests. See Views.

Declare a request at the file root when it applies regardless of the active view. Put it inside a view when it applies only to that view.

Memory covers the memory: field that any request can carry, surfaced to the agent in the network-trace detail view.

The spec

Reference

Sightmap Requests: Routes, Methods, and Payload Shapes

Route patterns

Method filter

All matches apply

Payloads are documentary

Scoped vs global

Next

​Route patterns

​Method filter

​All matches apply

​Payloads are documentary

​Scoped vs global

​Next

Route patterns

Method filter

All matches apply

Payloads are documentary

Scoped vs global

Next