oncall-engine/grafana-plugin/README.md

Grafana OnCall

Developer-Friendly Alert Management with Brilliant Slack Integration

• Connect monitoring systems
• Collect and analyze data
• On-call rotation
• Automatic escalation
• Never miss alerts with calls and SMS

Documentation

• On Github
• Grafana OnCall

Development

Autogenerating TS types based on OpenAPI schema

⚠️ WARNING
Transition to this approach is in progress

Overview

In order to automate types creation and prevent API usage pitfalls, OnCall project is using the following approach:

1. OnCall Engine (backend) exposes OpenAPI schema
2. OnCall Grafana Plugin (frontend) autogenerates TS type definitions based on it
3. OnCall Grafana Plugin (frontend) uses autogenerated types as a single source of truth for any backend-related interactions (url paths, request bodies, params, response payloads)

Instruction

1. Whenever API contract changes, run yarn generate-types from grafana-plugin directory

2. Then you can start consuming types and you can use fully typed http client:

   import { ApiSchemas } from 'network/oncall-api/api.types';
   import onCallApi from 'network/oncall-api/http-client';
   
   const {
     data: { results },
   } = await onCallApi.GET('/alertgroups/');
   const alertGroups: Array<ApiSchemas['AlertGroup']> = results;
   

3. [Optional] If there is any property that is not yet exposed in OpenAPI schema and you already want to use it, you can append missing properties to particular schemas by editing grafana-plugin/src/network/oncall-api/types-generator/custom-schemas.ts file:

   export type CustomApiSchemas = {
     Alert: {
       propertyMissingInOpenAPI: string;
     };
     AlertGroup: {
       anotherPropertyMissingInOpenAPI: number[];
     };
   };
   

   Then add their names to CUSTOMIZED_SCHEMAS array in grafana-plugin/src/network/oncall-api/types-generator/generate-types.ts:

   const CUSTOMIZED_SCHEMAS = ['Alert', 'AlertGroup'];
   

   The outcome is that autogenerated schemas will be modified as follows:

   import type { CustomApiSchemas } from './types-generator/custom-schemas';
   
   export interface components {
       schemas: {
           Alert: CustomApiSchemas['Alert'] & {
               readonly id: string;
               ...
           };
           AlertGroup: CustomApiSchemas['AlertGroup'] & {
               readonly pk: string;
               ...
           },
           ...
       }
   }