Progress Software Service Groups API

openapi: 3.2.0
info:
  description: '# Authentication

    The Chef Automate API typically uses an API token passed in the header of your API request.'
  title: Chef Automate API Documentation Service Groups API
  termsOfService: https://www.chef.io/terms-and-conditions-of-use/
  contact:
    url: https://www.chef.io/support/
    email: support@chef.io
  license:
    name: Apache 2.0
    url: https://github.com/chef/automate/blob/main/LICENSE
  version: version not set
  x-logo:
    altText: Chef logo
    url: /images/chef-automate-logo.svg
servers:
- url: https://automate.chef.io
tags:
- name: Service Groups
  x-displayName: Service Groups and Services
paths:
  /api/v0/applications/delete_disconnected_services:
    post:
      description: 'Removes services marked as disconnected based on the `threshold_seconds` setting.

        This function is not used by the API or CLI and is here for testing purposes.

        The functionality is currently covered by a periodically running job that can be configured using `UpdateDeleteDisconnectedServicesConfig`.


        Authorization Action:

        ```

        applications:serviceGroups:delete

        ```'
      tags:
      - Service Groups
      summary: Remove Disconnected Services
      operationId: ApplicationsService_DeleteDisconnectedServices
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/chef.automate.api.applications.ServicesRes'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/grpc.gateway.runtime.Error'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/chef.automate.api.applications.DisconnectedServicesReq'
        required: true
  /api/v0/applications/delete_services_by_id:
    post:
      description: 'Authorization Action:

        ```

        applications:serviceGroups:delete

        ```'
      tags:
      - Service Groups
      summary: Delete the services with the given IDs
      operationId: ApplicationsService_DeleteServicesByID
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/chef.automate.api.applications.ServicesRes'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/grpc.gateway.runtime.Error'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/chef.automate.api.applications.DeleteServicesByIDReq'
        required: true
  /api/v0/applications/disconnected_services:
    get:
      description: 'Marks services as disconnected based on the `threshold_seconds` setting.

        This function is not used by the API or CLI and is here for testing purposes.

        The functionality is currently covered by a periodically running job that can be configured

        by utilizing the `UpdateDisconnectedServicesConfig` endpoint.


        Authorization Action:

        ```

        applications:serviceGroups:list

        ```'
      tags:
      - Service Groups
      summary: Mark Services as Disconnected
      operationId: ApplicationsService_GetDisconnectedServices
      parameters:
      - description: Threshold for marking services disconnected in seconds.
        name: threshold_seconds
        in: query
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/chef.automate.api.applications.ServicesRes'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/grpc.gateway.runtime.Error'
  /api/v0/applications/service-groups:
    get:
      description: 'Lists service groups with name, health information, and application, environment, package, release metadata.

        Accepts pagination, sorting, search, and status filters.


        Example:

        ```

        applications/service-groups?sorting.field=percent_ok&sorting.order=ASC&pagination.page=1&pagination.size=25

        ```


        Authorization Action:

        ```

        applications:serviceGroups:list

        ```'
      tags:
      - Service Groups
      summary: List Service Groups
      operationId: ApplicationsService_GetServiceGroups
      parameters:
      - description: "Applies search and status filters, in the format of `fieldname:value` or `status:value`.\n\nValid filter fieldnames are:\n* `origin`: origin component of the service's package identifier\n* `service`: the name component of the service's package identifier\n* `version`: the version number component of the service's package identifier\n* `buildstamp`: the build timestamp (also called \"release\") of the service's package identifier\n* `channel`: the package channel to which the service subscribes for updates\n* `application`: the application field of the service's event-stream metadata\n* `environment`: the environment field of the service's event-stream metadata\n* `site`: the site field of the service's event-stream metadata\n* `group`: the suffix of the service group name\n\n`status` filters refine the service group results by a service's\n most recent connected/disconnected state or healthcheck result.\n\n Valid status filter parameters are:\n* `status:disconnected`: returns service groups with at least one service in a disconnected state\n* `status:critical`: returns service groups with a with at least one service in a \"critical\" healthcheck result\n* `status:unknown`: returns service groups with at least one service with an \"unknown\" healthcheck result\n* `status:warning`: returns service groups with at least one service with a \"warning\" healthcheck result\n* `status:ok`: returns service groups with at least one service with an \"ok\" health check result"
        name: filter
        in: query
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - description: Page number of the results to return.
        name: pagination.page
        in: query
        schema:
          type: integer
          format: int32
      - description: Amount of results to include per page.
        name: pagination.size
        in: query
        schema:
          type: integer
          format: int32
      - description: Field to sort the list results on.
        name: sorting.field
        in: query
        schema:
          type: string
      - description: Order the results should be returned in.
        name: sorting.order
        in: query
        schema:
          type: string
          enum:
          - ASC
          - DESC
          default: ASC
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/chef.automate.api.applications.ServiceGroups'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/grpc.gateway.runtime.Error'
  /api/v0/applications/service-groups/{service_group_id}:
    get:
      description: 'List the services for a service group with health status and service metadata.

        Uses the service group ID generated by Chef Automate instead of the Chef Habitat- provided ID.

        Supports pagination and filtering.


        Example:

        ```

        applications/service-groups/1dfff679054c60a10c51d059b6dbf81a765c46f8d3e8ce0752b22ffe8d4d9716?pagination.page=1&pagination.size=25

        ```


        Authorization Action:

        ```

        applications:serviceGroups:list

        ```'
      tags:
      - Service Groups
      summary: List Services for a Service Group
      operationId: ApplicationsService_GetServicesBySG
      parameters:
      - description: Service group ID.
        name: service_group_id
        in: path
        required: true
        schema:
          type: string
      - description: Page number of the results to return.
        name: pagination.page
        in: query
        schema:
          type: integer
          format: int32
      - description: Amount of results to include per page.
        name: pagination.size
        in: query
        schema:
          type: integer
          format: int32
      - description: Field to sort the list results on.
        name: sorting.field
        in: query
        schema:
          type: string
      - description: Order the results should be returned in.
        name: sorting.order
        in: query
        schema:
          type: string
          enum:
          - ASC
          - DESC
          default: ASC
      - description: 'Applies filters, in the format of `fieldname:value`.

          See documentation for ServicesReq for valid filter parameters.'
        name: filter
        in: query
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/chef.automate.api.applications.ServicesBySGRes'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/grpc.gateway.runtime.Error'
  /api/v0/applications/service_groups_health_counts:
    get:
      description: 'Lists the total service group health reports by critical, warning, ok and unknown responses. Supports search and status filtering.


        Authorization Action:

        ```

        applications:serviceGroups:list

        ```'
      tags:
      - Service Groups
      summary: List Service Groups Health Counts
      operationId: ApplicationsService_GetServiceGroupsHealthCounts
      parameters:
      - description: 'Applies search filters, in the format of `fieldname:value`.

          See the documentation for ServiceGroupsReq for valid filter parameters.'
        name: filter
        in: query
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/chef.automate.api.applications.HealthCounts'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/grpc.gateway.runtime.Error'
  /api/v0/applications/services:
    get:
      description: 'Lists service health status and service metadata for services.

        Supports pagination and search and status filtering. For a list of services for a specific service-group see "List Services for a Service Group" (GetServicesBySG endpoint).


        Authorization Action:

        ```

        applications:serviceGroups:list

        ```'
      tags:
      - Service Groups
      summary: List Services
      operationId: ApplicationsService_GetServices
      parameters:
      - description: "Applies search filters, in the format of `fieldname:value`.\n\nValid filter fieldnames are:\n* `origin`: origin component of the service's package identifier\n* `service`: the name component of the service's package identifier\n* `version`: the version number component of the service's package identifier\n* `buildstamp`: the build timestamp (also called \"release\") of the service's package identifier\n* `channel`: the package channel to which the service subscribes for updates\n* `application`: the application field of the service's event-stream metadata\n* `environment`: the environment field of the service's event-stream metadata\n* `site`: the site field of the service's event-stream metadata\n* `group`: the suffix of the service group name\n\n`status` filters refine service results by a service's\n current state or most recent healthcheck result.\n Disconnected services keep their last healthcheck result\n until their reports are removed by Chef Automate.\n When you apply a healthcheck filter, the report includes\n all recently disconnected services.\n Valid status filter parameters are:\n* `status:disconnected`: returns services in a disconnected state\n* `status:critical`: returns services with a \"critical\" healthcheck result\n* `status:unknown`: returns services with an \"unknown\" healthcheck result\n* `status:warning`: returns services with a \"warning\" healthcheck result\n* `status:ok`: returns services with an  \"ok\" health check result"
        name: filter
        in: query
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - description: Page number of the results to return.
        name: pagination.page
        in: query
        schema:
          type: integer
          format: int32
      - description: Amount of results to include per page.
        name: pagination.size
        in: query
        schema:
          type: integer
          format: int32
      - description: Field to sort the list results on.
        name: sorting.field
        in: query
        schema:
          type: string
      - description: Order the results should be returned in.
        name: sorting.order
        in: query
        schema:
          type: string
          enum:
          - ASC
          - DESC
          default: ASC
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/chef.automate.api.applications.ServicesRes'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/grpc.gateway.runtime.Error'
  /api/v0/applications/services-distinct-values:
    get:
      description: 'Lists all of the possible filter values for a given valid field.

        Limit the returned values by providing at one or more characters in the `query_fragment` parameter.

        Supports wildcard (* and ?)


        Authorization Action:

        ```

        applications:serviceGroups:list

        ```'
      tags:
      - Service Groups
      summary: List Filter Values
      operationId: ApplicationsService_GetServicesDistinctValues
      parameters:
      - description: Field name of service values.
        name: field_name
        in: query
        schema:
          type: string
      - description: Query value, supports wildcards (* and ?).
        name: query_fragment
        in: query
        schema:
          type: string
      - description: 'Applies filters, in the format of `fieldname:value`.

          See documentation for ServicesReq for valid filter parameters.'
        name: filter
        in: query
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/chef.automate.api.applications.ServicesDistinctValuesRes'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/grpc.gateway.runtime.Error'
  /api/v0/applications/stats:
    get:
      description: 'Shows a summary of service-groups, services, deployments, and supervisors.

        Used for telemetry.

        Does not support filtering.


        Authorization Action:

        ```

        applications:serviceGroups:list

        ```'
      tags:
      - Service Groups
      summary: Show Summary
      operationId: ApplicationsService_GetServicesStats
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/chef.automate.api.applications.ServicesStatsRes'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/grpc.gateway.runtime.Error'
components:
  schemas:
    google.protobuf.Any:
      type: object
      properties:
        type_url:
          type: string
        value:
          type: string
          format: byte
    chef.automate.api.applications.HealthCheckResult:
      type: object
      title: 'HealthCheckResult aggregates the stdout output, stderr output and process

        exit status of a habitat health check'
      properties:
        exit_status:
          type: integer
          format: int32
        stderr:
          type: string
        stdout:
          type: string
    chef.automate.api.applications.DisconnectedServicesReq:
      description: Request message for GetDisconnectedServices.
      type: object
      properties:
        threshold_seconds:
          description: Threshold for marking services disconnected in seconds.
          type: integer
          format: int32
    chef.automate.api.applications.HealthCounts:
      description: Combined count values from the health status and disconnected status reports.
      type: object
      properties:
        critical:
          type: integer
          format: int32
        disconnected:
          type: integer
          format: int32
        ok:
          type: integer
          format: int32
        total:
          type: integer
          format: int32
        unknown:
          type: integer
          format: int32
        warning:
          type: integer
          format: int32
    chef.automate.api.applications.ServicesDistinctValuesRes:
      description: Response message for GetServicesDistinctValues.
      type: object
      properties:
        values:
          description: List of distinct values fitting query_fragment and filters.
          type: array
          items:
            type: string
    chef.automate.api.applications.ServiceGroups:
      description: List of service groups.
      type: object
      properties:
        service_groups:
          description: List of service groups.
          type: array
          items:
            $ref: '#/components/schemas/chef.automate.api.applications.ServiceGroup'
    chef.automate.api.applications.Service:
      type: object
      properties:
        application:
          description: Application name.
          type: string
        channel:
          description: Chef Habitat channel that the service is subscribed to.
          type: string
        current_health_since:
          description: Time interval of current health status from last status change until now.
          type: string
        disconnected:
          description: 'Service connection information.

            Based on time since last healthcheck received and disconnected service configuration.'
          type: boolean
        environment:
          description: Environment name.
          type: string
        fqdn:
          description: FQDN reported by a Chef Habitat Supervisor.
          type: string
        group:
          description: Service group name.
          type: string
        health_check:
          description: Intentionally blank.
          $ref: '#/components/schemas/chef.automate.api.applications.HealthStatus'
        health_check_result:
          description: Intentionally blank.
          $ref: '#/components/schemas/chef.automate.api.applications.HealthCheckResult'
        health_updated_at:
          description: Timestamp since health status change.
          type: string
          format: date-time
        id:
          type: string
          title: Internal ID
        last_event_occurred_at:
          description: Timestamp of last received health check message.
          type: string
          format: date-time
        last_event_since:
          description: Interval since last event received until now.
          type: string
        previous_health_check:
          description: Intentionally blank.
          $ref: '#/components/schemas/chef.automate.api.applications.HealthStatus'
        release:
          description: 'Combination of the service version and release in a single string.

            Example: 0.1.0/8743278934278923.'
          type: string
        site:
          description: Site reported by Chef Habitat service, a user defined flag.
          type: string
        supervisor_id:
          description: The Chef Habitat Supervisor ID.
          type: string
        update_strategy:
          description: Update strategy that the service employs.
          type: string
    chef.automate.api.applications.ServicesRes:
      description: Response message for GetServices.
      type: object
      properties:
        services:
          description: List of services.
          type: array
          items:
            $ref: '#/components/schemas/chef.automate.api.applications.Service'
    chef.automate.api.applications.ServicesStatsRes:
      description: Response message for ServicesStats.
      type: object
      properties:
        total_deployments:
          description: Total number of deployments reporting to Chef Automate.
          type: integer
          format: int32
        total_service_groups:
          description: Total number of service groups reporting to Chef Automate.
          type: integer
          format: int32
        total_services:
          description: Total number of services reporting to Chef Automate, counts both connected and disconnected services.
          type: integer
          format: int32
        total_supervisors:
          description: Total number of supervisors reporting to Chef Automate.
          type: integer
          format: int32
    chef.automate.api.applications.ServiceGroup:
      description: 'A service group message is the representation of an individual service group that

        is internally generated by aggregating all of its services.'
      type: object
      properties:
        application:
          description: Application name for the service group.
          type: string
        disconnected_count:
          description: Count of disconnected services within this service group.
          type: integer
          format: int32
        environment:
          description: Environment name for the service group.
          type: string
        health_percentage:
          description: 'Percentage of services reporting OK status.

            The health_percentage can be a number between 0-100.'
          type: integer
          format: int32
        id:
          description: Service group ID. This is a value constructed by Chef Automate and is not reported by Chef Habitat.
          type: string
        name:
          description: Name of service group.
          type: string
        package:
          description: 'Combination of the origin and package name in a single string.

            Example: core/redis.'
          type: string
        release:
          description: 'Combination of the version and release in a single string.

            Example: 0.1.0/8743278934278923.'
          type: string
        services_health_counts:
          description: Intentionally blank.
          $ref: '#/components/schemas/chef.automate.api.applications.HealthCounts'
        status:
          description: Intentionally blank.
          $ref: '#/components/schemas/chef.automate.api.applications.HealthStatus'
    chef.automate.api.applications.DeleteServicesByIDReq:
      type: object
      properties:
        ids:
          description: List of the database IDs of the services to be deleted.
          type: array
          items:
            type: string
    chef.automate.api.applications.HealthStatus:
      description: 'The HealthStatus enumerable matches the Chef Habitat implementation for health-check status:

        => https://www.habitat.sh/docs/reference/#health-check

        For a health status within a service group.

        *critical* means that one or more services are in critical condition.

        *warning* means that one or more services have a warning, but none are in critical condition.

        *unknown* means that one or more services have not responded, but all of the remaining nodes responded to the health check as "OK".

        *OK* means that all of the services are OK and all have responded to the health check.

        *none* means that there is no health check information.'
      type: string
      default: OK
      enum:
      - OK
      - WARNING
      - CRITICAL
      - UNKNOWN
      - NONE
    chef.automate.api.applications.ServicesBySGRes:
      description: Response message for GetServicesBySG.
      type: object
      properties:
        group:
          description: Service group name.
          type: string
        services:
          description: List of services.
          type: array
          items:
            $ref: '#/components/schemas/chef.automate.api.applications.Service'
        services_health_counts:
          description: Intentionally blank.
          $ref: '#/components/schemas/chef.automate.api.applications.HealthCounts'
    grpc.gateway.runtime.Error:
      type: object
      properties:
        code:
          type: integer
          format: int32
        details:
          type: array
          items:
            $ref: '#/components/schemas/google.protobuf.Any'
        error:
          type: string
        message:
          type: string
  securitySchemes:
    APIToken:
      description: Authenticate with the Automate API using an API Token.
      type: apiKey
      name: api-token
      in: header
x-tagGroups:
- name: Compliance
  tags:
  - ReportingService
  - StatsService
  - JobsService
  - ProfilesService
  - Comp_Assets
- name: Report Manager
  tags:
  - ReportManagerService
- name: Infra
  tags:
  - ConfigMgmt
  - InfraProxy
- name: Ingest
  tags:
  - ChefIngester
  - JobScheduler
- name: Node Management
  tags:
  - NodeManagerService
  - NodesService
- name: Event Feed
  tags:
  - EventFeedService
- name: Secrets
  tags:
  - SecretsService
- name: Applications
  tags:
  - service_groups
  - retention
  - ApplicationsService
- name: Data Feed
  tags:
  - DatafeedService
- name: Data Lifecycle
  tags:
  - DataLifecycle
- name: Notifications
  tags:
  - Notifications
- name: Content Delivery
  tags:
  - Cds
- name: Audit and Settings
  tags:
  - UserSettingsService
- name: System
  tags:
  - Gateway
  - Deployment
  - License
  - Telemetry
  - LegacyDataCollector
- name: Identity
  tags:
  - users
  - teams
  - tokens
- name: Access Management
  tags:
  - policies
  - roles
  - projects
  - rules
  - Authorization