# Service Usage API reference

Source: `@socra/service-api@0.1.0` (ServiceUsageContract).

Consumer service discovery and project enablement.

## API surface

Base URL: `https://service.socra.cloud`

## Service usage

Services available to or enabled on a project.

### Resource schema

- `id` custom, required
- `name` string (min length: 1; max length: 253; pattern: ^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$), required
- `title` string, required
- `state` "enabled" | "disabled", required
- `dependencies` string[], required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {},
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 253,
      "pattern": "^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$"
    },
    "title": {
      "type": "string"
    },
    "state": {
      "type": "string",
      "enum": [
        "enabled",
        "disabled"
      ]
    },
    "dependencies": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "id",
    "name",
    "title",
    "state",
    "dependencies"
  ],
  "additionalProperties": false
}
```

### List services for project

`GET /usage/v1/services`

#### Query parameters

- `project_id` custom, required
- `available` boolean | "true" | "false", optional
- `enabled` boolean | "true" | "false", optional
- `limit` integer (min: 1; max: 100), optional
- `after` string, optional

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "project_id": {},
    "available": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "string",
          "enum": [
            "true",
            "false"
          ]
        }
      ]
    },
    "enabled": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "string",
          "enum": [
            "true",
            "false"
          ]
        }
      ]
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "after": {
      "type": "string"
    }
  },
  "required": [
    "project_id"
  ]
}
```

#### Response

- `data` object[], required
  - `id` custom, required
  - `name` string (min length: 1; max length: 253; pattern: ^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$), required
  - `title` string, required
  - `state` "enabled" | "disabled", required
  - `dependencies` string[], required
- `has_more` boolean, required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {},
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 253,
            "pattern": "^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$"
          },
          "title": {
            "type": "string"
          },
          "state": {
            "type": "string",
            "enum": [
              "enabled",
              "disabled"
            ]
          },
          "dependencies": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "id",
          "name",
          "title",
          "state",
          "dependencies"
        ],
        "additionalProperties": false
      }
    },
    "has_more": {
      "type": "boolean"
    }
  },
  "required": [
    "data",
    "has_more"
  ],
  "additionalProperties": false
}
```

### Enable service

`POST /usage/v1/services/{name}/enable`

#### Path parameters

- `name` string (min length: 1; max length: 253; pattern: ^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$), required

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "string",
  "minLength": 1,
  "maxLength": 253,
  "pattern": "^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$"
}
```


#### Request body

- `project_id` custom, required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "project_id": {}
  },
  "required": [
    "project_id"
  ]
}
```

#### Response

- `id` custom, required
- `name` string (min length: 1; max length: 253; pattern: ^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$), required
- `title` string, required
- `state` "enabled" | "disabled", required
- `dependencies` string[], required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {},
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 253,
      "pattern": "^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$"
    },
    "title": {
      "type": "string"
    },
    "state": {
      "type": "string",
      "enum": [
        "enabled",
        "disabled"
      ]
    },
    "dependencies": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "id",
    "name",
    "title",
    "state",
    "dependencies"
  ],
  "additionalProperties": false
}
```

### Disable service

`POST /usage/v1/services/{name}/disable`

#### Path parameters

- `name` string (min length: 1; max length: 253; pattern: ^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$), required

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "string",
  "minLength": 1,
  "maxLength": 253,
  "pattern": "^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$"
}
```


#### Request body

- `project_id` custom, required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "project_id": {}
  },
  "required": [
    "project_id"
  ]
}
```

#### Response

- `id` custom, required
- `name` string (min length: 1; max length: 253; pattern: ^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$), required
- `title` string, required
- `state` "enabled" | "disabled", required
- `dependencies` string[], required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {},
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 253,
      "pattern": "^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$"
    },
    "title": {
      "type": "string"
    },
    "state": {
      "type": "string",
      "enum": [
        "enabled",
        "disabled"
      ]
    },
    "dependencies": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "id",
    "name",
    "title",
    "state",
    "dependencies"
  ],
  "additionalProperties": false
}
```

## Metric usage

Aggregated managed-service metrics for a consumer project.

### Query project service usage

`GET /usage/v1/projects/{project_id}/services/{service}/usage`

#### Path parameters

- `project_id` custom, required

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```

- `service` string (min length: 1; max length: 253; pattern: ^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$), required

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "string",
  "minLength": 1,
  "maxLength": 253,
  "pattern": "^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$"
}
```


#### Query parameters

- `metric` string (min length: 1; max length: 384), optional
- `start_time` custom, required
- `end_time` custom, required
- `interval` "hour" | "day", required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "metric": {
      "type": "string",
      "minLength": 1,
      "maxLength": 384
    },
    "start_time": {},
    "end_time": {},
    "interval": {
      "type": "string",
      "enum": [
        "hour",
        "day"
      ]
    }
  },
  "required": [
    "start_time",
    "end_time",
    "interval"
  ]
}
```

#### Response

- `service_id` custom, required
- `service` string (min length: 1; max length: 253; pattern: ^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$), required
- `start_time` custom, required
- `end_time` custom, required
- `interval` "hour" | "day", required
- `series` object[], required
  - `metric` string (min length: 1; max length: 384), required
  - `kind` "delta" | "gauge" | "cumulative", required
  - `value_type` "integer" | "number", required
  - `unit` string, required
  - `aggregation` "sum" | "latest", required
  - `consumer_project_id` custom, optional
  - `points` object[], required
    - `start_time` custom, required
    - `end_time` custom, required
    - `value` number, required
    - `samples` integer (min: 0; max: 9007199254740991), required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "service_id": {},
    "service": {
      "type": "string",
      "minLength": 1,
      "maxLength": 253,
      "pattern": "^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$"
    },
    "start_time": {},
    "end_time": {},
    "interval": {
      "type": "string",
      "enum": [
        "hour",
        "day"
      ]
    },
    "series": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "metric": {
            "type": "string",
            "minLength": 1,
            "maxLength": 384
          },
          "kind": {
            "type": "string",
            "enum": [
              "delta",
              "gauge",
              "cumulative"
            ]
          },
          "value_type": {
            "type": "string",
            "enum": [
              "integer",
              "number"
            ]
          },
          "unit": {
            "type": "string"
          },
          "aggregation": {
            "type": "string",
            "enum": [
              "sum",
              "latest"
            ]
          },
          "consumer_project_id": {},
          "points": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "start_time": {},
                "end_time": {},
                "value": {
                  "type": "number"
                },
                "samples": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 9007199254740991
                }
              },
              "required": [
                "start_time",
                "end_time",
                "value",
                "samples"
              ],
              "additionalProperties": false
            }
          }
        },
        "required": [
          "metric",
          "kind",
          "value_type",
          "unit",
          "aggregation",
          "points"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "service_id",
    "service",
    "start_time",
    "end_time",
    "interval",
    "series"
  ],
  "additionalProperties": false
}
```

---

Company: Socra — Multiply Your Judgment
Canonical URL: https://cloud.socra.com/docs/service/reference/api