backstage-grpc-playground

Overview

backstage-grpc-playground is a backstage plugin ported from BloomRPC which is an Electron application. We modified some of the original code to make this compatible with Backstage entity. See Compare to BloomRPC

This repo contains React frontend plugin. For the backend plugin, please checkout backstage-grpc-playground-backend

Requirements

Backstage ^1.1.0
Node.JS 14 | 16

Methods supported

Unary
Client streaming
Server streaming

Not supported (yet)

We are currently not supporting

SSL call See issue
Load proto from reflection. See issue

Install

Install backstage-grpc-playground for packages/app

E.g: In your backstage project root

yarn --cwd packages/app add backstage-grpc-playground

Usage

Customize ApiDoc to use backstage-grpc-playground for `grpc` type

// packages/app/src/apis.ts
import { GrpcPlaygroundComponent } from 'backstage-grpc-playground';

// your code
// ...

export const apis: AnyApiFactory[] = [
  // other apis 
  // ...
  
  createApiFactory({
    api: apiDocsConfigRef,
    deps: {},
    factory: () => {
      // load the default widgets
      const definitionWidgets = defaultDefinitionWidgets();

      return {
        getApiDefinitionWidget: (apiEntity: ApiEntity) => {
          // custom rendering for grpc
          if (apiEntity.spec.type === 'grpc') {
            return {
              type: 'grpc',
              title: 'gRPC Playground',
              component: GrpcPlaygroundComponent
            }
          }
          
          // fallback to the defaults
          return definitionWidgets.find(d => d.type === apiEntity.spec.type);
        },
      };
    },
  }),
]

A path `/grpc-playground` in backstage application

// packages/app/src/App.tsx
import { GrpcPlaygroundPage } from 'backstage-grpc-playground'

// your code
// ...

const routes = (
  <FlatRoutes>
    // other routes 
    // ...
    <Route path="/grpc-playground" element={<GrpcPlaygroundPage />} />
  </FlatRoutes>
);

Example importing API definition from Github examples/yaml-definition/unary.yaml

Compare to BloomRPC

Load proto files from defined entity spec (learn more at examples), creating clients and send gRPC requests at backstage backend
Proto files are contained in backend (default /packages/backend/proto)
Removed “Import from server reflection” See issue
Removed “Add import paths” button
Removed “gRPC-web” switch
Missing imports warning, allow user to upload folder
- User upload a file “employee.proto” that imports “common.proto”
- User upload a file “account.proto” that imports some google-apis proto files. In this case user should import google folder

Yaml file definition

See yaml-definition

Examples

Unary

See example

Stream