HTTP Ingresses

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

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'
    }
  }