This repository contains the API specification of the SnowballR project.
For communication between the backend and frontend, gRPC is
used, whereas the services are defined by Protocol Buffers
(see /proto for the service definition
(in main.proto) and all required .proto files).
To integrate the API specification into the backend or frontend, download this repository in the build pipeline or add it as a git submodule. Afterwards, use the protoc compiler to generate the relevant files for your project. When using a TypeScript-based frontend, you can use the snowballr-api NPM package, which already contains the generated gRPC client and all relevant types.
The package ships ES modules with type declarations, one module per proto file. Install it together with its peer dependencies and import from the module that defines what you need:
npm install snowballr-api @protobuf-ts/runtime @protobuf-ts/runtime-rpcimport { SnowballRClient } from "snowballr-api/main.client";
import { Project } from "snowballr-api/project";When using it as a git submodule, execute the following commands:
git submodule add [-b branch] git@github.com:SE-UUlm/snowballr-api.git <name>
git submodule update --init --recursiveThen follow the instructions on the gRPC documentation page to generate the relevant files for your project.
We create a new release whenever a set of features, bug fixes, or changes is ready to be integrated into the frontend / backend. To release a new version of the API, follow the steps in the SnowballR Wiki.
Remember to also update the version in the package.json of the NPM package.
To update the API when using it as a git submodule, checkout the new version tag in the submodule (see this StackOverflow post for additional information).
A static site documentation can be generated using Sabledocs. To build the documentation locally, use docker:
docker build . -t snowballr-api
docker run -it -p 8080:80 snowballr-api:latestThe generated documentation is packaged into a docker container running nginx and is served on the
internal port 80.
Moreover, the documentation will also be built automatically after every push to main as well as after a version tag
has been set.
This project is linted using Protolint. Just is used to ease the process of running the linter. There are the following two recipes:
lint: Prints all the detected issues with the proto files.fix: Automatically tries to fix all detected issues.
These actions can be invoked by providing them as a parameter to the just cli like this: just (lint|fix).