SureThing_CROSS_Data

---

Protobuf data type definitions and API service specification of CROSS

Structure

Directory	Description
CROSS-Contract	CROSS Contract Project (Maven)
CROSS-Contract-Lite	CROSS Contract Lite Project (Gradle)
openapi	CROSS REST API specification (OpenAPI)
proto	CROSS Protobuf data message definitions

Table of Contents

• Build the Contract
  • Contract Prerequisites
  • Resolve the Dependencies and Build the Contract
• Build the Lite Contract
  • Lite Contract Prerequisites
  • Resolve the Dependencies and Build the Lite Contract
• Process to Produce the API Specification
  • Prerequisites
  • Protobuf to OpenAPI Conversion Process
• Authors

Build the Contract

Contract Prerequisites

• Java Development Kit (JDK) >= 11
• Maven >= 3.8

Resolve the Dependencies and Build the Contract

From the root of the project change directory:

cd CROSS-Contract

Execute:

mvn clean install

Build the Lite Contract

For the mobile client application (Android)

Lite Contract Prerequisites

• Java Development Kit (JDK) >= 11
• Gradle >= 7.2

Resolve the Dependencies and Build the Lite Contract

From the root of the project change directory:

cd CROSS-Contract-Lite

Execute:

./gradlew clean build

Process to Produce the API Specification

Prerequisites

• Go >= 1.17
• Python >= 3.8.10
• Protocol Buffer Compiler (Protoc) >= 3.6.1
• protoc-gen-openapi plugin

Protobuf to OpenAPI Conversion Process

Here we go over the process followed to specify a REST API in Protobuf and produce an equivalent OpenAPI specification:

1. The API is defined using RPCs, following the Google APIs Guidelines, to be presented as an API that follows the REST convention. As examples, our proto defined files can be found at proto, alongside the Google related dependencies at proto/google.

   A detailed example of a POST endpoint (for creating a book) receiving a protobuf body (CreateBookRequest), inline param in the query path and returning a protobuf response (Book) can be found here.

2. Convert the Proto files using the gnostic protoc-gen-openapi plugin to an openapi.yml file by executing the following command:

   protoc [PROTO-FILES] -I. --openapi_out=.

   For example, with only the Dataset.proto and Reward.proto files the command executed would be:

   protoc Dataset.proto Reward.proto -I. --openapi_out=.

3. OpenAPI lacks the proper support of the protobuf media type, therefore we change the payloads of each endpoint to application/x-protobuf using the following command:

   sed -i 's/application\/json/application\/x-protobuf/g' ./openapi.yaml

4. We generate an html file of the OpenAPI specification to be easily visualized through a browser, using the swagger-yaml-to-html.py python script:

   python swagger-yaml-to-html.py < /path/to/openapi.yaml > openapi.html

Authors

Name	University	More info
Lucas Vicente	Instituto Superior Técnico
Rafael Figueiredo	Instituto Superior Técnico
Ricardo Grade	Instituto Superior Técnico