Skip to content

Changing the API

The api module provides the external interface of Ankaios.

The single source of truth for the APIs are the ankaios_api/proto files in a combination with the build scripts. During the build, Rust objects are generated using prost and annotated with the instructions in the ankaios_api/build.rs and the utility build scripts under ankaios_api/build/. The annotations take care of the generation of the spec objects and the JSON Schema. The following list summarizes which files are used for which object type:

  • The prost objects, generated by prost from the proto files. The configuration for this step is in the build.rs file of the api crate.
  • The spec objects, generated from the prost ones by the spec derive macros. The spec definitions that configure this process are in ankaios_api/build/spec_structs.rs.
  • The JSON Schema, generated from the spec objects. The process is configured in the ankaios_api/build/schema_annotations.rs script.

Please perform the following checks when making changes in the api crate:

  • Test the filtering of the Complete State and the output of the ank CLI. The prost objects are used for serializing the filtered output and changes or additions could be needed in the annotations in ankaios_api/build.rs.
  • Test the usage of Ankaios manifests for the server startup and the ank apply commands. The spec objects are used for the deserialization of the manifests which is configured in the ankaios_api/build/spec_structs.rs.
  • Check the generated JSON Schema for correctness and expected behavior. If the descriptions of the Schema need to be changed, edit them in the proto files as this is where they originate from.