API description

Kalix uses Protocol buffers to describe the contract for an API. Protocol Buffers are a language and platform agnostic, extensible description model. To create and deploy a service on Kalix, you define APIs and Entity data structures in a .proto file. As a best practice, you should separate the descriptors that define the external APIs from those that define the domain state model, so each can evolve independently. You define each API as a gRPC service. Depending on the component (Views, Actions, or Entities) you choose, the options you can define can differ. For a detailed overview of all options, check out the respective guide for the component you want to implement.

Protocol Buffer example

syntax = "proto3"; (1)

package shopping.product.api; (2)

import "kalix/annotations.proto"; (3)
import "google/api/annotations.proto";

message Order { (4)
    string userID = 1 [(kalix.field).entity_key = true]; (5)
    string orderID = 2;
    repeated OrderItem items = 3;

message OrderItem {
    string productID = 1;
    int32 quantity = 2;
    float price = 3;

service OrderBackendService { (6)
    option (kalix.service) = { (7)
        component: "shopping.product.domain.ProductPopularityValueEntity"

    rpc AddOrder (Order) returns (Order) { (8)
        option (google.api.http) = {
            post: "/order/{userID}",
            body: "*"
1 Specify the version of the Protobuf syntax, Kalix uses proto3.
2 Packages prevent name clashes between protocol messages, similar to how packages work in programming languages.
3 Imports allow you to use definitions from other protobuf files. You’ll always need kalix/annotations.proto, other imports are optional. In this case google/api/annotations.proto adds the ability to expose services with HTTP endpoints.
4 Messages represent the request and response of API calls and are used to define the data structure of the data you want to persist (also known as state). These structures can be as simple or as complex as you need for your use case.
5 This annotation defines which field in your message uniquely identifies the instance of your entity.
6 A gRPC service defines how the external clients can interact with your business logic.
7 This annotation is used by the Kalix codegen tools to specify what type of code needs to be generated (in this case an entity) and the fully qualified name (package name and entity name) of the message that represents the state.
8 Every service has one or more RPC methods that specify the functionality of your service. Each method will be handled by a function in your code. The google.api.http option tells Kalix that this RPC method should get a gRPC and an HTTP endpoint.

The implementation, your code, ties these .proto files together as shown in the image below:

api description