openapi.yaml

# Copyright 2020, locate Authors.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     https://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

# [START swagger]
swagger: "2.0"
info:
  description: |-
    The locate API provides consistent, expected measurement quality for M-Lab
    clients.
  title: "M-Lab Locate API ({{DEPLOYMENT}})"
  version: "2.0.0"
host: "locate-dot-{{PROJECT}}.appspot.com"
# [END swagger]

consumes:
- "application/json"
produces:
- "application/json"
schemes:
- "https"
- "wss"

paths:
  # Shared "nearest" requests without an API key.
  "/v2/nearest/{name}/{type}":
    get:
      description: |-
        Find the nearest healthy service.

        All requests are scheduled as part of a "shared" resource pool. This
        is a good choice for small client integrations. When the platform is
        overloaded and the locate API must choose which requests to allow and
        which to block, priority is given to requests using explicit API keys
        to the /v2/priority/* resource.

        This resource does not require an API key. All requests to this resource
        are managed collectively as if they all used a single API key.

      operationId: "v2-shared-nearest"
      produces:
      - "application/json"
      parameters:
        - name: name
          in: path
          description: The service name, e.g. "ndt", "neubot", "wehe", etc.
          type: string
          required: true
        - name: type
          in: path
          description: The service type, e.g. "ndt7", "dash", "replay", etc.
          type: string
          required: true
      responses:
        # NOTE: non-number values are a schema error for the config, despite
        # openapi documentation.
        '200':
          description: The result of the nearest request. Clients should use the
            next request fields to schedule the next request in the event of
            error or batch scheduling.
          schema:
            $ref: "#/definitions/NearestResult"
        '500':
          description: An error occurred while looking for the service.
            Clients should use the next request fields to schedule the next
            request in the event of error.
          schema:
            $ref: "#/definitions/ErrorResult"
      tags:
        - public

  # Priority "nearest" requests WITH an API key.
  "/v2/priority/nearest/{name}/{type}":
    get:
      description: |-
        Find the nearest healthy service.

        This resource requires an API key. When the system is under sufficient
        load that the locate API must choose which requests to allow and which
        to reject, these requests are prioritized over "shared" requests.

      operationId: "v2-priority-nearest"
      produces:
      - "application/json"
      parameters:
        - name: name
          in: path
          description: service
          type: string
          required: true
        - name: type
          in: path
          description: datatype
          type: string
          required: true
      responses:
        '200':
          description: The result of the nearest request. Clients should use the
            next request fields to schedule the next request for batch
            scheduling.
          schema:
            $ref: "#/definitions/NearestResult"
        '500':
          description: An error occurred while looking for the service.
            Clients should use the next request fields to schedule the next
            request in the event of error.
          schema:
            $ref: "#/definitions/ErrorResult"
      security:
      - jwt_auth: []
      tags:
        - public
    options:
      description: CORS preflight request handler.
      operationId: "v2-priority-nearest-cors"
      parameters:
        - name: name
          in: path
          description: service
          type: string
          required: true
        - name: type
          in: path
          description: datatype
          type: string
          required: true
      responses:
        '200':
          description: CORS preflight response.
      tags:
        - public

  "/v2/platform/heartbeat":
    get:
      description: |-
        Platform-specific path. Protected by API key authentication.
      operationId: "v2-platform-heartbeat"
      responses:
        '200':
          description: OK.
      security:
      - api_key: []
      tags:
        - platform

  "/v2/platform/heartbeat-jwt":
    get:
      description: |-
        Platform-specific path. Protected by JWT authentication with organization validation.
        The JWT token must include an "org" claim that matches the organization in the hostname
        of any heartbeat registration or health update messages.
      operationId: "v2-platform-heartbeat-jwt"
      responses:
        '200':
          description: OK.
        '401':
          description: Unauthorized - invalid JWT token or missing/invalid org claim.
        '403':
          description: Forbidden - organization mismatch between JWT and hostname.
      security:
      - jwt_auth: []
      tags:
        - platform

  "/v2/platform/prometheus":
    get:
      description: |-
        Platform-specific path.
      operationId: "v2-platform-prometheus"
      responses:
        '200':
          description: OK.
      security:
      - api_key: []
      tags:
        - platform

  "/v2/platform/monitoring/{name}/{type}":
    get:
      description: |-
        Platform-specific path.
      operationId: "v2-platform-monitoring"
      parameters:
        - name: name
          in: path
          description: service
          type: string
          required: true
        - name: type
          in: path
          description: datatype
          type: string
          required: true
      responses:
        '200':
          description: OK.
      tags:
        - platform

  "/v2/siteinfo/registrations":
    get:
      description: |-
        Returns heartbeat registration information in various formats.
      operationId: "v2-siteinfo-registrations"
      produces:
      - "application/json"
      responses:
        '200':
          description: OK.
        '500':
          description: Error.
      tags:
        - siteinfo

  # Legacy mlab-ns compatibility
  # TODO(https://github.com/m-lab/locate/issues/185)
  "/ndt":
    get:
      description: |-
        Compatibility endpoint for the retired mlab-ns /ndt resource.

        This endpoint exists solely to support known integrators that have not
        yet completed their migration away from mlab-ns. It returns ndt7 server
        metadata in the legacy mlab-ns JSON format.

        No support is offered for this resource. It will be removed once affected
        integrators confirm they no longer depend on it.

        See https://github.com/m-lab/locate/issues/185.

      operationId: "v1-ndt"
      produces:
      - "application/json"
      responses:
        '200':
          description: The result of the request.
        '204':
          description: No results available.
        '400':
          description: Unsupported query parameter value.
        '501':
          description: Unsupported HTTP method.
        '502':
          description: The inner nearest lookup failed.
      tags:
        - public

definitions:
  # Define the query reply without being specific about the structure.
  ErrorResult:
    type: object
    properties:
        error:
          type: object
          properties:
            type:
              type: string
              description: The error type.
            title:
              type: string
              description: A descriptive title for this error.
            status:
              type: integer
              description: The HTTP status code of this error, e.g. 4xx or 5xx.
            detail:
              type: string
            instance:
              type: string
        next_request:
          $ref: "#/definitions/NextRequest"

  NearestResult:
    type: object
    properties:
        next_request:
          $ref: "#/definitions/NextRequest"
          description: The next request defines the earliest time that a client
            should make a new request using the included URL.
        results:
          type: array
          items:
            type: object
            properties:
              machine:
                type: string
                description: The machine name that all URLs reference.
              location:
                type: object
                additionalProperties: {}
                description: The machine location metadata.
              urls:
                type: object
                additionalProperties: {}
                description: Specific service URLs with access tokens.

  NextRequest:
    type: object
    properties:
      nbf:
        type: string
        description: |-
          "not before" defines the time after which the URL will
          become valid. This value is the same time used in "nbf" field of
          the underlying JSON Web Token (JWT) claim. To show this equivalence,
          we use the same name.
      exp:
        type: string
        description: |-
          Expires defines the time after which the URL will be invalid.
          Expires will always be greater than NotBefore. This value is the
          same time used in the "exp" field of the underlying JWT claim.
      url:
        type: string
        description: |-
          URL should be used to make the next request to the location service.

securityDefinitions:
  # This section configures basic authentication with an API key.
  # Paths configured with api_key security require an API key for all requests.
  api_key:
    type: "apiKey"
    description: |-
      An API key for your client integration restricted to the Locate API and
      allocated using a self-service [signup](https://docs.google.com/forms/d/e/1FAIpQLSeWMiPSRWHIcg5GVRG-oc5kkefLpR4Nqk4aNYBFK6Wr8jAAdw/viewform)
      or allocated by M-Lab for your client integration.
    name: "key"
    in: "query"

  # This section configures JWT authentication for heartbeat endpoints.
  # Paths configured with jwt_auth security require a valid JWT token with an "org" claim.
  jwt_auth:
    authorizationUrl: "" # Required for swagger 2.0 oauth2, but not used by ESPv2/Apigee
    flow: "implicit" # Required for swagger 2.0 oauth2, but not used by ESPv2/Apigee
    type: "oauth2"
    # x-google-jwks_uri and x-google-issuer identify the service that issues JWTs.
    x-google-issuer: "token-exchange"
    x-google-jwks_uri: "https://auth.{{PLATFORM_PROJECT}}.measurementlab.net/.well-known/jwks.json"
    # x-google-audiences are the audiences JWTs are allowed to target.
    # The audience must match the JWT token audience from token-exchange service.
    x-google-audiences: "autojoin,locate,integration"

tags:
  - name: public
    description: Public API.
  - name: platform
    description: Platform API.