Get Started with ARO

Build your first API in 5 minutes. No magic required—just features.

1

Create Your Project

An ARO application is simply a folder containing .aro files and an openapi.yaml contract. Let's create a Hello World API.

$ mkdir HelloWorldAPI && cd HelloWorldAPI

Your project structure will look like this:

📁 HelloWorldAPI/
📄 openapi.yaml
📜 main.aro
📜 hello.aro
2

Define Your API Contract

ARO uses contract-first development. Your openapi.yaml defines what endpoints exist. The operationId maps directly to your ARO feature sets.

openapi.yaml 
openapi: 3.0.3
info:
  title: Hello World API
  version: 1.0.0

servers:
  - url: http://localhost:8000

paths:
  /hello:
    get:
      operationId: sayHello  # ← This maps to your ARO feature set!
      summary: Say Hello
      responses:
        '200':
          description: A friendly greeting
💡 Key Insight

The operationId is the bridge between your API and your code. sayHello in the contract means you need a feature set named sayHello.

3

Write Your Application Entry Point

Every ARO application needs exactly one Application-Start feature set. This is where your application begins.

main.aro 
(* Application Entry Point *)

(Application-Start: Hello World API) {
    (* Log a startup message *)
    <Log> the <startup: message> for the <console> with "Starting server...".

    (* Start the HTTP server on port 8000 *)
    <Start> the <http-server> on <port> with 8000.

    (* Keep the application running to process HTTP requests *)
    <Keepalive> the <application> for the <events>.

    (* Return OK to indicate successful startup *)
    <Return> an <OK: status> for the <startup>.
}
4

Create Your Feature Handler

Now create the feature set that handles your API endpoint. Remember: the feature set name must match the operationId from your contract.

hello.aro 
(* Handler for GET /hello *)
(* Feature set name matches operationId from openapi.yaml *)

(sayHello: Greeting API) {
    (* Create our greeting message *)
    <Create> the <greeting> with "Hello, World!".

    (* Return it as a successful response *)
    <Return> an <OK: status> with <greeting>.
}
🎯 The ARO Pattern

Every statement follows: <Action> the <Result> preposition the <Object>.
It reads like English because it is English—structured for machines.

5

Run Your Application

Check your syntax, then run your application:

$ aro check ./HelloWorldAPI
✅ No errors found in 2 file(s)
$ aro run ./HelloWorldAPI
Starting server... Server running at http://localhost:8000

Test your API:

$ curl http://localhost:8000/hello
{"message": "Hello, World!"}

🎉 That's it! You've built your first ARO application.

What's Next?

You've just scratched the surface. ARO can handle complex APIs, event-driven architectures, and AI-assisted development.

Read the Docs Learn About FDD