HTTP ingresses expose reactor components as HTTP endpoints, allowing external systems to call component methods via standard HTTP requests.

Configuration

An HTTP ingress is configured through the properties field when creating an ingress with type: http.

Basic Structure

uri: /resources/ingresses/my-ingress
spec:
  type: http
  componentId: my-component.hreactor
  properties:
    route: api/my-endpoint
    httpMethod: post
    isPublic: false
    headers: {}
    queryParams: {}
    body:
      mode: structured

Route Configuration

Route

The route property defines the URL path where the ingress will be accessible:

properties:
  route: api/orders/create

The ingress will be callable at /ingress/api/orders/create.

Route Parameters

Routes can include dynamic parameters using the {paramName} syntax:

properties:
  route: api/orders/{orderId}/status

Route parameters are automatically extracted and passed to the component:

curl -X GET https://your-instance.hantera.io/ingress/api/orders/12345/status
# orderId parameter will be "12345"

Multiple route parameters are supported:

properties:
  route: api/warehouses/{warehouseId}/products/{productId}

HTTP Method

The httpMethod property defines which HTTP method the ingress accepts:

properties:
  httpMethod: post  # get, post, put, patch, or delete

Available methods:

• get - HTTP GET requests
• post - HTTP POST requests
• put - HTTP PUT requests
• patch - HTTP PATCH requests
• delete - HTTP DELETE requests

Requests using other HTTP methods will receive a 405 Method Not Allowed response.

Access Control

Calling HTTP Ingresses

To call an HTTP ingress, a session must have the appropriate permission based on the ingress resource ID:

ingresses[/`<ingressId>`]:http

Important: The permission uses the ingress resource ID (the uri when creating the ingress), NOT the HTTP route.

Example:

uri: /resources/ingresses/api/skus/search  # This is the ingressId
spec:
  type: http
  properties:
    route: search/skus  # This is the HTTP route (can be different!)

Permissions needed:

• To call this ingress: ingresses/api/skus/search:http (uses the ingressId)
• To manage this ingress: ingresses:read or ingresses:write

Public Ingresses

Mark an ingress as public to allow unauthenticated access:

properties:
  isPublic: true

Public ingresses:

• Don't require authentication
• Have a 10 MB maximum payload size
• Rate limiting applied by the platform
• Should validate input carefully in component code
• Are ideal for webhooks and public APIs

Quick Example

Here's a complete example of an HTTP ingress:

uri: /resources/ingresses/api/skus/search
spec:
  type: http
  componentId: sku-search.hreactor
  acl:
    - graph/sku:read
  properties:
    route: api/skus/search
    httpMethod: get
    queryParams:
      searchTerm: q
      sortBy: sort

//sku-search.hreactor
param searchTerm: text
param sortBy: text

let sort = sortBy match
  nothing |> 'skuNumber'
  |> sortBy

from query skus(skuNumber)
  phrase searchTerm
  orderBy $'{sort} asc'

curl -X GET \
  "https://your-instance.hantera.cloud/ingress/api/skus/search?q=laptop&sort=skuNumber" \
  -H "Authorization: Bearer YOUR_TOKEN"

Best Practices

Validation

Always validate input parameters, especially for public ingresses:

param email: text | nothing
param name: text | nothing

from { email, name } match
  {
    email: /^[A-Za-z0-9!#$%&'*+\/=?^_`{|}~-]+(?:\.[A-Za-z0-9!#$%&'*+\/=?^_`{|}~-]+)*@(?:[A-Za-z0-9](?:[A-Za-z0-9-){0,61}[A-Za-z0-9))?\.)+[A-Za-z]{2,63}$/i,
    name: /.+/
  } |> createUser(email, name)
  |> {
    error = {
      code = 'INVALID_INPUT'
      message = 'Email and name are required'
    }
  }

See Also

• Parameter Mapping - Headers, query params, and body handling
• Response Handling - JSON, streams, and error responses
• SSE Streaming - Real-time server-sent events
• Ingresses Overview - Core ingress concepts
• Components - Creating reactor components