Skip to main content

Compiled Protobufs

Sylk CLI will build (autogenerate) and compile .proto files based on your sylk.json file.

The build process (both compilation and generating the .proto files) is instantiated with running: sylk build command under root sylk project directory.

The generated .proto files are following google API Improvement Proposal for File and directory structure of the generated .proto's.

Resolving Sylk Resources Into Proto Files​

Sylk is following well defined rules to resolve sylk.json file into one or more .proto file(s) based on the following scenarios:

👀 Multi-pattern Protobufs

Since sylk CLI version >= 0.3 multi pattern resolution of protbuf files are supported, before then we has supported less use cases see Legacy Section Below

  • Standalone Service: "Standalone" services are well defined API's in a single .proto file which holds all service definitions including Methods with thier respective Inputs / Outputs Messages and all Schema related messages as well in a single file. To achieve this with Sylk CLI you will need to create a Messages and your Enums (if needed) "directly" under your service, this will create a "virtual" package in sylk.json which will have the same name as your service. Once built with sylk build command, the SylkProto plugin will resolve both the package and the service definitions into a single file.

    /TodoApp
    ├── protos
    │   └── sylklabs
    │       └── Todos
    │           └── v1
    │               └── Todos.proto

  • Multi Files Per Service: You can seperate your services schema to multi files and multiple hierarchies and versions, you can create a Package which will create evantualy a .proto file or a Service which will have the same effect, this in turn will seperate your Messages and Enums definitions from your Services and thier Methods. This pattern meant to large services schema which share a set of common packages into multiple services.

    /TodoApp
    ├── protos
    │   └── sylklabs
    │       ├── API
    │       │   └── v1
    │       │       └── API.proto
    │       ├── Todo
    │       │   └── v1
    │       │       └── Todo.proto
    │       └── Todos
    │           └-─ v1
    │              └── Todos.proto

  • Versioning: Every .proto file can be versioned by creating the Package with a full path, the supported versions are in a format as follows:

    • Start with a v

    • followed with a version number (a whole number e.g integer): A new major version of an API must not depend on a previous major version of the same API. An API may depend on other APIs, with an expectation that the caller understands the dependency and stability risk associated with those APIs. In this scenario, a stable API version must only depend on stable versions of other APIs.

      Optionally suffixed with​

    • Channel: A stability channel is a long-lived release at a given stability level that receives in-place updates. There is no more than one channel per stability level for a major version. Under this strategy, there are up to three channels available: alpha, beta, and stable.

    • Release: An individual release is an alpha or beta release that is expected to be available for a limited time period before its functionality is incorporated into the stable channel, after which the individual release will be shut down. When using release-based versioning strategy, an API may have any number of individual releases at each stability level.

      if not specified the v1 version will be assigned automaticlly. This pattern meant to large services schema which share a set of common packages into multiple services.

      /TodoApp
      ├── protos
      │   └── sylklabs
      │       ├── API
      │       │   └── v1
      │       │   │   └── API.proto
      │       │   └── v2
      │       │       └── API.proto
      │       ├── Todo
      │       │   └── v1
      │       │       └── Todo.proto
      │       └── Todos
      │           ├── v1
      │           │   └── Todos.proto
      │           └── v2
      │               └── Todos.proto

Legacy Resolutions​

Before sylk CLI version 0.3 the .proto files were resolved in a single pattern.

Each project must had a manually created package by the developer which was holding all messegas and enums this package later could be imported to services (Just like packages can be imported to services after version 0.3) and used in Inputs and Outputs for service methods.

This pattern would create a single file hierarchy for each service and package independently.

/TodoApp
├── protos
│   ├── API.proto
│   ├── Todo.proto
│   └── Todos.proto