Skip to content

Define your API

Write a service's contract in protobuf, check it compiles, publish it as a versioned package and, when needed, share it with other products. Define is the first step of the Define, Build, Deploy loop.

Prerequisites

  • The service exists and its define folder is on disk: ~/alis.build/<org>/define/<org>/<product>/<path>/<vN>.
  • You know the service's package id, for example acme.sh.orders.v1.

Write the protos

Put one or more .proto files in the define folder. The package statement must match the folder: acme/sh/orders/v1 holds package acme.sh.orders.v1;. A mismatch is reported by the dry run below; a real define skips such a file silently.

orders.proto
syntax = "proto3";

package acme.sh.orders.v1;

service OrdersService {
  rpc GetOrder(GetOrderRequest) returns (Order) {}
}

Imports of Google well-known types and of other Alis packages resolve during compilation.

Validate before you commit

alis define acme.sh.orders.v1 --dry-run --json

The local files, uncommitted edits included, are compiled with the same compiler and dependency resolution as a define. Nothing is published. The result reports valid, diagnostics[] (severity, file, line, column, message) and git (uncommitted files, unpushed commits and the commit a define would use). The command exits non-zero when there are errors. Inside the service's folder the package id can be omitted.

Publish a contract version

Commit and push the definitions repo, then:

alis define acme.sh.orders.v1 --install
  • The latest pushed commit is compiled into a new contract version and language packages are generated. Pass --commit <sha> to define an earlier, reviewed commit.
  • --install runs alis packages install for the service once the define succeeds, so the generated packages are usable at once. Limit it to one language with --install-language go|node|python|dart|dotnet|swift|rust.
  • --async returns the operation name; resume with alis operations wait <name>.

Contract versions keep patch zero: the first define publishes 1.0.0, later ones 1.1.0, 1.2.0 and so on. Build versions of the implementation fill in the patch number.

The console shows the published contract under the product's Reference page, one entry per package, with services, methods, messages and enums.

Refresh generated code after a change

If generated types look stale, pull the service's latest contract package:

alis packages install acme.sh.orders.v1

Do not inspect protos through runtime reflection in service code.

Share the contract with another product

A defined package reaches another product's registries only once it is shared. Administrators of the source product run:

alis packages share acme.sh.orders.v1 --with acme.am

The destination receives the current latest version now and every version defined after that. alis packages sharing acme.sh.orders.v1 lists the destinations; alis packages unshare acme.sh.orders.v1 --with acme.am stops further deliveries while versions already copied stay.