openapi: 3.0.0
info:
  title: Metrics API
  version: '1.0'
  description: >-
    The Tidepool API is an HTTP REST API used by Tidepool clients use to
    communicate with the Tidepool Platform.


    For more information, see the [Getting Started](../docs/quick-start.md)
    section.
  contact:
    name: API Support
    url: https://support.tidepool.org/
    email: support@tidepool.org
  license:
    name: BSD-2-Clause
    url: https://github.com/tidepool-org/highwater/master/LICENSE
  x-tidepool-service: https://github.com/tidepool-org/highwater
servers:
  - url: https://external.integration.tidepool.org
    description: integration
  - url: https://api.tidepool.org
    description: production
  - url: https://dev1.dev.tidepool.org
    description: dev1
  - url: https://qa1.development.tidepool.org
    description: qa1
  - url: https://qa2.development.tidepool.org
    description: qa2
tags:
  - name: Internal
    description: APIs intended for internal use by Tidepool.
  - name: Metrics
    description: >-
      Record metrics events.


      These metrics APIs are intended for use by Tidepool products to capture
      free-form metrics events.

      The APIs have no request body, nor do they return any meaningful
      responses.

      There are very few constraints or validation of the input parameters.

      Any number of additional query parameters can be included in the API
      requests, and they are recorded along with the metrics event.

      It is OK to send them asynchronously in a fire-and-forget manner.
paths:
  /metrics/user/{userId}/{eventName}:
    parameters:
      - $ref: '#/components/parameters/tidepooluserid'
      - $ref: '#/components/parameters/eventname.v1'
    get:
      summary: Record Metrics Event for User
      description: >-
        Records a new metrics event for the user identified by the `userId`
        parameter. This API does not require a session token, but if one is
        provided it must be a valid token. The `userId` parameter is not
        validated. Any query parameters supplied with the request will be
        recorded as part of the event.
      responses:
        '200':
          description: Success
      operationId: RecordMetricsEventForNamedUser
      security:
        - sessionToken: []
      tags:
        - Metrics
  /metrics/thisuser/{eventName}:
    parameters:
      - $ref: '#/components/parameters/eventname.v1'
    get:
      summary: Record Metrics Event for Logged-In User
      description: >-
        Records a new metrics event for the user identified by the session
        token. This API requires a session token, and it must be a valid user
        token. The `userId` parameter is extracted from the session token. Any
        query parameters supplied with the request will be recorded as part of
        the event.
      responses:
        '200':
          description: Success
        '401':
          description: Unauthorized
      operationId: RecordMetricsEventForLoggedInUser
      security:
        - sessionToken: []
      tags:
        - Metrics
  /metrics/server/{serverName}/{eventName}:
    parameters:
      - $ref: '#/components/parameters/servername.v1'
      - $ref: '#/components/parameters/eventname.v1'
    get:
      summary: Record Metrics Event for Server
      description: >-
        Records a new metrics event on behalf of a server. This API requires a
        session token, and it must be a valid server token. Any query parameters
        supplied with the request will be recorded as part of the event.
      responses:
        '200':
          description: Success
        '401':
          description: Unauthorized
      operationId: RecordMetricsEventForServer
      security:
        - sessionToken: []
      tags:
        - Metrics
        - Internal
components:
  securitySchemes:
    sessionToken:
      description: Tidepool Session Token
      type: apiKey
      name: X-Tidepool-Session-Token
      in: header
  schemas:
    tidepooluserid:
      type: string
      title: Tidepool User ID
      pattern: >-
        ^([0-9a-f]{10}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$
      description: >-
        String representation of a Tidepool User ID. Old style IDs are 10-digit
        strings consisting of only hexadeximcal digits. New style IDs are
        36-digit [UUID
        v4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random))
      readOnly: true
      x-go-type: string
    eventname.v1:
      title: Metrics Event Name
      type: string
      example: blip%20-%20Viewed%20Care%20Team%20List
    servername.v1:
      title: Metrics Server Name
      type: string
      example: hydrophone
  parameters:
    tidepooluserid:
      description: Tidepool User ID
      name: userId
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/tidepooluserid'
    eventname.v1:
      description: >-
        Client-defined event name. The metrics service imposes no restrictions
        on the event name. The event name must be URL-safe, or encoded as such,
        as it is sent as part of the URL path. Current best practice is to
        prefix the event name with the client application name, such as `blip`,
        followed by the actual event name, such as `Viewed Care Team List`. The
        resulting full event name might be `blip - Viewed Care Team List`, but
        encoded in URL-safe manner (i.e. converting spaces to `%20`). This
        allows differentiation between recording similar events by different
        client applications.
      name: eventName
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/eventname.v1'
    servername.v1:
      description: >-
        Server-defined server name. The metrics service imposes no restrictions
        on the server name. The server name must be URL-safe, or encoded as
        such, as it is sent as part of the URL path.
      name: serverName
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/servername.v1'
