Skip to content

About

Definition of the API for the SnowballR project

Topics

Resources

Stars

3 stars

Watchers

1 watching

Forks

Repository files navigation

SnowballR Logo

SnowballR API

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).

Getting started

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-rpc
import { 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 --recursive

Then follow the instructions on the gRPC documentation page to generate the relevant files for your project.

Release procedure

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).

Documentation

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:latest

The 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.

Linting

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).

About

Definition of the API for the SnowballR project

Topics

Resources

Stars

3 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages