Guide HTTP Services

HTTP Services

ARO provides built-in HTTP server capabilities using a contract-first approach. Routes are defined in an OpenAPI specification, and ARO feature sets handle the requests.

Contract-First HTTP

ARO uses OpenAPI contracts to define HTTP routes. The HTTP server automatically starts when a contract file is present in your application directory. The runtime looks for files in this precedence order: openapi.yaml, openapi.yml, openapi.json.

Key Principles:

1. Routes are defined in your OpenAPI contract, not in ARO code
2. Feature set names must match operationId values from the contract
3. No HTTP server without a contract (no OpenAPI file = no server)

Application Structure

MyAPI/
├── openapi.yaml      # Required: Defines all HTTP routes
├── main.aro          # Application-Start with Keepalive
└── handlers.aro      # Feature sets matching operationIds

Defining Routes (openapi.yaml)

openapi: 3.0.3
info:
  title: User API
  version: 1.0.0

paths:
  /users:
    get:
      operationId: listUsers      # Feature set name in ARO
      responses:
        '200':
          description: Success
    post:
      operationId: createUser     # Feature set name in ARO
      responses:
        '201':
          description: Created

  /users/{id}:
    get:
      operationId: getUser        # Feature set name in ARO
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Success

Route Handlers

Feature sets must be named after the operationId from your OpenAPI contract:

(* Feature set name = operationId from openapi.yaml *)

(listUsers: User API) {
    Retrieve the <users> from the <user-repository>.
    Return an <OK: status> with <users>.
}

(createUser: User API) {
    Extract the <data> from the <request: body>.
    Create the <user> with <data>.
    Store the <user> into the <user-repository>.
    Return a <Created: status> with <user>.
}

(getUser: User API) {
    Extract the <id> from the <pathParameters: id>.
    Retrieve the <user> from the <user-repository> where id = <id>.
    Return an <OK: status> with <user>.
}

Application Entry Point

The HTTP server starts automatically. Use Keepalive to keep the application running:

(Application-Start: User API) {
    Log "User API starting..." to the <console>.
    Keepalive the <application> for the <events>.
    Return an <OK: status> for the <startup>.
}

Request Data Access

Path Parameters

Extract the <user-id> from the <pathParameters: id>.

Query Parameters

Extract the <page> from the <queryParameters: page>.

Request Body

Extract the <data> from the <request: body>.

Request Headers

Extract the <auth-token> from the <request: headers.Authorization>.

Response Status Codes

(* 2xx Success *)
Return an <OK: status> with <data>.           (* 200 *)
Return a <Created: status> with <resource>.   (* 201 *)
Return a <NoContent: status> for <deletion>.  (* 204 *)

(* 4xx Client Errors *)
Return a <BadRequest: status> with <errors>.       (* 400 *)
Return an <Unauthorized: status> for <auth>.       (* 401 *)
Return a <Forbidden: status> for <access>.         (* 403 *)
Return a <NotFound: status> for <missing>.         (* 404 *)

(* 5xx Server Errors *)
Return an <InternalError: status> for <error>.     (* 500 *)

HTTP Client

For making outgoing HTTP requests, use the Request action:

Request the <data> from "https://api.example.com/resource".

For more details on HTTP client functionality including configuration objects, headers, and POST/PUT requests, see HTTP Client.

Next Steps

• File System - File operations and monitoring
• Sockets - TCP communication
• Events - Event-driven patterns