API grammar#

API grammar describes HTTP-style integration declarations, endpoint methods, request and response shapes, and route bindings.

Source#

How to use this page#

Read the examples first when authoring Business Language. Use the rule inventory when checking exact grammar coverage or when updating parser, lowering, editor, or documentation behavior.

Entry rules and syntax families#

Start with these rules when reading this grammar: apiDeclaration, routeDeclaration, routeBody, endpointDeclaration, methodBody, functionReturnType.

• Declarations: apiDeclaration, endpointDeclaration, routeDeclaration
• Types: functionReturnType
• Bodies: methodBody, routeBody

Key grammar excerpts#

apiDeclaration#

apiDeclaration
    : API identifier OPEN_BRACE apiMemberList? CLOSE_BRACE
    ;

routeDeclaration#

routeDeclaration
    : ROUTE httpMethod stringLiteral routeBody
    ;

routeBody#

routeBody: OPEN_BRACE routeMemberList? CLOSE_BRACE;

Complete rule and token inventory#

apiDeclaration, apiMember, apiMemberList, endpointDeclaration, functionReturnType, httpMethod, methodBody, parameter
parameterList, routeBody, routeDeclaration, routeFunction, routeMember, routeMemberList

Examples#

No-parameter endpoint#

api VendorApi {
  get "/vendors" list_vendors(): Json;
}

Typed endpoint with block body#

api InvoiceApi {
  post "/invoices" create_invoice(payload: Json): Json {
    return payload;
  }
}

Route-local functions#

api InvoiceApi {
  route get "/invoices" {
    async function list(company_code: CompanyCode) -> Json;
  }
}

Options endpoint and patch route#

api HealthApi {
  options "/health" health_options;

  route patch "/vendors" {
    function update(payload: Json, dry_run: bool = false): Json {
      return payload;
    }
  }
}

Common authoring mistakes#

• Do not copy examples without checking the rule inventory for the exact grammar boundary.
• Do not add behavior that depends on missing configuration or undeclared user-facing errors.

Related guides#

• /language/services-apis/
• /language/functions-services/

Authoring notes#

• Keep examples aligned with the grammar source, not with inferred syntax from another language.
• Use declared messages for user-facing failures, and fail closed when required configuration is absent.