Skip to content

endpoint-definition.md

Latest commit

 

History

History
128 lines (87 loc) · 2.88 KB

endpoint-definition.md

File metadata and controls

128 lines (87 loc) · 2.88 KB

Endpoint Definition

The Endpoint class defines an HTTP endpoint with its method, path, serializers, and parsers.

Constructor

const endpoint = new Endpoint({
  method: 'GET',
  pathname: '/users/(:id)',
  // ...options
})

Options

method (required)

HTTP method for the endpoint:

type HTTPMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'
  • GET - Cannot have a body schema
  • POST, PUT, PATCH, DELETE - Can have a body schema

pathname (required)

URL path with optional dynamic segments:

pathname: '/users'           // Static path
pathname: '/users/:id'       // Required param
pathname: '/users/(:id)'     // Optional param
pathname: '/posts/:id/comments/:commentId'  // Multiple params

params

Serializer for path parameters. See Serialization.

query

Serializer for query string parameters. See Serialization.

body

Serializer for request body. See Serialization.

data

Parser for successful response body. See Response Parsing.

error

Parser for error response body. See Response Parsing.

Constructor

The Endpoint constructor takes a definition and optional default options:

const endpoint = new Endpoint({
  method: 'GET',
  pathname: '/users',
  // Definition: method, pathname, params, query, body, data, error
}, {
  headers: {
    'X-API-Version': '2',
  },
  timeout: 5000,
  retry: {
    attempts: 3,
    delay: 1000,
    when: ({ response }) => response?.status === 503,
  },
})

The second argument accepts:

  • headers: Default headers for all requests
  • timeout: Request timeout in milliseconds
  • retry: Default retry policy

These can be overridden per-request.

See Retry Policy for retry configuration.

Low-level Methods

Most users should use http_client instead of calling these methods directly. The HTTP client handles URL generation, body serialization, and response parsing automatically.

generate_url(init)

Generates a full URL with params and query serialized:

const url = await endpoint.generate_url({
  base_url: 'https://api.example.com',
  params: { id: '123' },
  query: { include: 'posts' },
})

Returns URL on success or SerializationError on validation failure.

serialize_body(init)

Serializes the request body:

const { body, content_type } = await endpoint.serialize_body({
  body: { name: 'John' },
})

Returns { body, content_type } on success or SerializationError on validation failure.

parse_response(response)

Parses an HTTP response:

const result = await endpoint.parse_response(response)

Returns typed result based on status code. See Response Parsing.