---
title: "Define your API"
url: "https://docs.alisx.com/how-to/alis-build/define-your-api/"
---
# 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.

```protobuf title="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

```bash title="Terminal"
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:

```bash title="Terminal"
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:

```bash title="Terminal"
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:

```bash title="Terminal"
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.

## Related

- [Install and upgrade packages](https://docs.alisx.com/how-to/alis-build/install-and-upgrade-packages.md)
- [Define, Build, Deploy](https://docs.alisx.com/explanation/define-build-deploy.md)