API Reference

This page provides reference documentation for the Metrics Configuration Generator (MCG) API endpoints.

Endpoints overview

The following sections detail the API endpoints available in MCG.

Metrics configuration

• POST /api/v1/generate_metrics_config: Create a MetricsConfig instance from metric configuration request details.
• POST /api/v1/get_file_descriptor_set: Return file descriptors for a given MetricsConfig for decoding reports.
• POST /api/v1/validate_metrics_config: Validate the passed MetricsConfig, returning a list of any validation errors.

Vehicle Signal Catalogs

• POST /api/v1/vs/: Create new or update existing Vehicle Signal Catalog.
• GET /api/v1/vs/: List all Vehicle Signal Catalog metadata.
• DELETE /api/v1/vs/{version}: Delete the specified Vehicle Signal Catalog.

Service status

• GET /health: Check the service's health.

Protobuf content types

Several API endpoints accept or return data in protocol buffer (protobuf) format. Two content types are used:

• application/x-protobuf: Indicates protobuf data in its binary wire format. This format is efficient for machine-to-machine communication but isn't human readable.
• text/x-protobuf: Indicates protobuf data in its text format, which is human readable and useful for debugging or manual inspection.

When an endpoint supports multiple protobuf formats for a request or response, use the Content-Type header to specify the format of request data, and the Accept header to specify the selected format of response data. For example:

• -H 'Content-Type: application/x-protobuf'
• -H 'Accept: text/x-protobuf'

Call the API

The examples on this page use curl for calling the REST API and assume you set the SERVICE_URL environment variable to refer to the host where MCG is deployed. When running locally, this is usually http://localhost:8005.

To target a remote Cloud Run instance, set SERVICE_URL using gcloud. Then, append an authorization header with an OpenID Connect (OIDC) identity token to your curl command:

SERVICE_URL=$(gcloud run services describe mcg-service --region=<var label="Google Cloud region">GCP_REGION</var> --format='value(status.url)')

# Authorization header to append to curl command:
-H "Authorization: Bearer $(gcloud auth print-identity-token)"

Metrics configuration

This section describes endpoints for generating and validating metrics configurations.

POST /api/v1/generate_metrics_config

Create a MetricsConfig instance from metrics configuration request details. This process includes validation, and if generation fails due to schema violations, invalid references, cyclic dependencies, or other issues, the API returns a list of error details.

curl -H "Content-Type: application/json" \
  -H "Accept: text/x-protobuf" \
  --data-binary @PATH_TO_METRICS_CONFIG_JSON \
  "$SERVICE_URL/api/v1/generate_metrics_config"
      

POST /api/v1/get_file_descriptor_set

Return file descriptors for a given MetricsConfig for decoding reports.

curl -H "Content-Type: application/x-protobuf" \
  -H "Accept: application/x-protobuf" \
  --data-binary @PATH_TO_METRICS_CONFIG_PB \
  "$SERVICE_URL/api/v1/get_file_descriptor_set"
      

POST /api/v1/validate_metrics_config

Validate the provided MetricsConfig, returning a list of any validation errors.

curl -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  --data-binary @PATH_TO_METRICS_CONFIG_JSON \
  "$SERVICE_URL/api/v1/validate_metrics_config"
      

Vehicle Signal Catalogs

This section describes endpoints for managing Vehicle Signal Catalogs.

POST /api/v1/vs/

Create new or update existing Vehicle Signal Catalog.

{
  "version": "string",
  "vehicle_signals": "string"
}

{"version": "string"}

curl -H "Content-Type: application/json" \
  --data-binary @- "$SERVICE_URL/api/v1/vs/" << EOF
{
  "version": "v1.0",
  "vehicle_signals": "VEHICLE_SIGNALS_BASE64"
}
EOF
      

GET /api/v1/vs/

List all Vehicle Signal Catalog metadata.

{"versions": [{"version": "string"}]}

curl "$SERVICE_URL/api/v1/vs/"
      

DELETE /api/v1/vs/{version}

Delete the specified Vehicle Signal Catalog.

{"version": "string"}

curl --request DELETE "$SERVICE_URL/api/v1/vs/v1.0"
      

Service status

This section describes endpoints for checking service health.

GET /health

Check the service's health.

curl "$SERVICE_URL/health"
      

Error responses

When an API call results in an error (HTTP status 4xx or 5xx), the response body contains an error object with the following structure:

{
  "error": {
    "code": 400,
    "status": "INVALID_ARGUMENT",
    "message": "Request validation failed",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "fieldName",
            "description": "error description"
          }
        ]
      }
    ]
  }
}