ReportPortal API Definitions

This repository contains gRPC protocol definitions and OpenAPI Specification for ReportPortal APIs and provides knowledge about its own services. You can use Protocol Buffers (Protobuf) descriptions or OpenAPI specifications to generate your client's libraries or take pre-generated.

Contents

• ReportPortal API Definitions
  • Contents
  • Overview
  • Repository Structure
  • How to work with Protobuf
    • Buf CLI
    • Verify
    • Lint API
    • Detect breaking changes
  • Generate code
    • Java
    • Other languages
      • Remote generating
      • Local generating
  • Third-party libraries
    • Google types
      • Additional types
  • Contribution

Overview

ReportPortal APIs are deployed as the API Service (ext. link).

Main ReportPortal APIs use OpenAPI Specification (OAS) to describe their services.

Some ReportPortal APIs use Protobuf version 3 (proto3) as their Interface Definition Language (IDL) to define the API interface and the structure of the payload messages.

Currently, we're migrating from a Code-first to an API-first approach. That means that you can't find all specifications here. You can find other specifications in ReportPortal UI Settings. Little by little, we will provide the specifications here.

Repository Structure

.
├── api
│   ├── openapi
│   │   ├── models
│   │   │   └── model.yaml
│   │   └── api-references.yaml
│   └── proto
│       ├── buf.md
│       ├── buf.yaml
│       └── reportportal
│           ├── common
│           │   ├── v1
│           │   │   └── types.proto
│           │   └── v2
│           └── reporting (domain)
│               ├── v1
│               │   └── reporting.proto
│               └── v2
├── docs
├── src
│   └── build
└── templates

• api - root catalog for Report Portal Interface Definitions
• openapi - contains OpenAPI Specification for Report Portal APIs
  • models - contains shared models for all Report Portal APIs
• proto - contains gRPC definitions for Report Portal services and types
  • common - contains common types for all Report Portal gRPC services
  • reporting - contains gRPC definitions for domain specific
  • vN - catalog for grouping definitions by versions
  • buf.md (ext. link) - it's analogous to a GitHub repository's README.md and supports the CommonMark syntax
  • buf.yaml (ext. link) - defines a module, and is placed at the root of the Protobuf source files it defines
• docs - contains Guidelines for Report Portal APIs
• gradle - contains Gradle wrapper
• src - contains source code for building language-specific packages
  • build - catalog for generated stubs for clients or servers
• templates - contains templates for Buf CLI generating code

How to work with Protobuf

Buf CLI

We use buf CLI to create consistent Protobuf APIs that preserve compatibility and comply with best practices.

To work with this repository, install buf.

Verify

The buf build command is used to verify that an input compiles.

buf build --exclude-source-info -o -#format=json | jq '.file[] | .package'

Lint API

Just use

buf lint

Detect breaking changes

buf breaking --against '.git#branch=main'

Generate code

Java

For generating Java code we use Protobuf Plugin for Gradle.

Perform for generate code:

./gradlew generateProto

Other languages

For other programming languages we use buf.

Remote generating

Buf doesn't have a built-in compiler. We use remote plugins for generating code for the following languages:

• Python
• C#
• JS Node
• TS

Perform for generate code:

buf generate

Optional languages:

• JS Web Connect Protocol
• Ruby
• Go
• Kotlin
• Scala

Perform for generate code:

buf generate --template templates/buf.gen.opt.yaml

Local generating

Before, you need to install protocol buffer compiler with standard plugins.

Config buf.gen.local.yaml for your needs or use default protoc command.

Perform for generate code:

buf generate --template templates/buf.gen.local.yaml

Third-party libraries

Google types

We use additional types provided by Google Type Library.

You can use them in your proto files like:

import "google/type/<type_name>.proto";

Additional types

• CalendarPeriod (enum)
• Color (message)
• Date (message)
• DateTime (message)
• DayOfWeek (enum)
• Decimal (message)
• Expr (message)
• Fraction (message)
• Interval (message)
• LatLng (message)
• LocalizedText (message)
• Money (message)
• Month (enum)
• PhoneNumber (message)
• ShortCode (message)
• PostalAddress (message)
• Quaternion (message)
• TimeOfDay (message)
• TimeZone (message)

Contribution

• Use official Protocol Buffers Style Guide
• Read the Contribution details
• Use buf lint for check style guid requirements and buf breaking --against '.git#branch=main' for checking forwards and backward compatibility