github.com/m-lab/locate@v0.17.6/openapi.yaml (about)

     1  # Copyright 2020, locate Authors.
     2  #
     3  # Licensed under the Apache License, Version 2.0 (the "License");
     4  # you may not use this file except in compliance with the License.
     5  # You may obtain a copy of the License at
     6  #
     7  #     https://www.apache.org/licenses/LICENSE-2.0
     8  #
     9  # Unless required by applicable law or agreed to in writing, software
    10  # distributed under the License is distributed on an "AS IS" BASIS,
    11  # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    12  # See the License for the specific language governing permissions and
    13  # limitations under the License.
    14  
    15  # [START swagger]
    16  swagger: "2.0"
    17  info:
    18    description: |-
    19      The locate API provides consistent, expected measurement quality for M-Lab
    20      clients.
    21    title: "M-Lab Locate API ({{DEPLOYMENT}})"
    22    version: "2.0.0"
    23  host: "locate-dot-{{PROJECT}}.appspot.com"
    24  # [END swagger]
    25  
    26  consumes:
    27  - "application/json"
    28  produces:
    29  - "application/json"
    30  schemes:
    31  - "https"
    32  - "wss"
    33  
    34  paths:
    35    # Shared "nearest" requests without an API key.
    36    "/v2/nearest/{name}/{type}":
    37      get:
    38        description: |-
    39          Find the nearest healthy service.
    40  
    41          All requests are scheduled as part of a "shared" resource pool. This
    42          is a good choice for small client integrations. When the platform is
    43          overloaded and the locate API must choose which requests to allow and
    44          which to block, priority is given to requests using explicit API keys
    45          to the /v2/priority/* resource.
    46  
    47          This resource does not require an API key. All requests to this resource
    48          are managed collectively as if they all used a single API key.
    49  
    50        operationId: "v2-shared-nearest"
    51        produces:
    52        - "application/json"
    53        parameters:
    54          - name: name
    55            in: path
    56            description: The service name, e.g. "ndt", "neubot", "wehe", etc.
    57            type: string
    58            required: true
    59          - name: type
    60            in: path
    61            description: The service type, e.g. "ndt7", "dash", "replay", etc.
    62            type: string
    63            required: true
    64        responses:
    65          # NOTE: non-number values are a schema error for the config, despite
    66          # openapi documentation.
    67          '200':
    68            description: The result of the nearest request. Clients should use the
    69              next request fields to schedule the next request in the event of
    70              error or batch scheduling.
    71            schema:
    72              $ref: "#/definitions/NearestResult"
    73          '500':
    74            description: An error occurred while looking for the service.
    75              Clients should use the next request fields to schedule the next
    76              request in the event of error.
    77            schema:
    78              $ref: "#/definitions/ErrorResult"
    79        tags:
    80          - public
    81  
    82    # Priority "nearest" requests WITH an API key.
    83    "/v2/priority/nearest/{name}/{type}":
    84      get:
    85        description: |-
    86          Find the nearest healthy service.
    87  
    88          This resource requires an API key. When the system is under sufficient
    89          load that the locate API must choose which requests to allow and which
    90          to reject, these requests are prioritized over "shared" requests.
    91  
    92        operationId: "v2-priority-nearest"
    93        produces:
    94        - "application/json"
    95        parameters:
    96          - name: name
    97            in: path
    98            description: service
    99            type: string
   100            required: true
   101          - name: type
   102            in: path
   103            description: datatype
   104            type: string
   105            required: true
   106        responses:
   107          '200':
   108            description: The result of the nearest request. Clients should use the
   109              next request fields to schedule the next request for batch
   110              scheduling.
   111            schema:
   112              $ref: "#/definitions/NearestResult"
   113          '500':
   114            description: An error occurred while looking for the service.
   115              Clients should use the next request fields to schedule the next
   116              request in the event of error.
   117            schema:
   118              $ref: "#/definitions/ErrorResult"
   119        security:
   120        - api_key: []
   121        tags:
   122          - public
   123  
   124    "/v2/platform/heartbeat":
   125      get:
   126        description: |-
   127          Platform-specific path.
   128        operationId: "v2-platform-heartbeat"
   129        responses:
   130          '200':
   131            description: OK.
   132        security:
   133        - api_key: []
   134        tags:
   135          - platform
   136  
   137    "/v2/platform/prometheus":
   138      get:
   139        description: |-
   140          Platform-specific path.
   141        operationId: "v2-platform-prometheus"
   142        responses:
   143          '200':
   144            description: OK.
   145        security:
   146        - api_key: []
   147        tags:
   148          - platform
   149  
   150    "/v2/platform/monitoring/{name}/{type}":
   151      get:
   152        description: |-
   153          Platform-specific path.
   154        operationId: "v2-platform-monitoring"
   155        parameters:
   156          - name: name
   157            in: path
   158            description: service
   159            type: string
   160            required: true
   161          - name: type
   162            in: path
   163            description: datatype
   164            type: string
   165            required: true
   166        responses:
   167          '200':
   168            description: OK.
   169        tags:
   170          - platform
   171  
   172    "/v2/siteinfo/registrations":
   173      get:
   174        description: |-
   175          Returns heartbeat registration information in various formats.
   176        operationId: "v2-siteinfo-registrations"
   177        produces:
   178        - "application/json"
   179        responses:
   180          '200':
   181            description: OK.
   182          '500':
   183            description: Error.
   184        tags:
   185          - siteinfo
   186  
   187  definitions:
   188    # Define the query reply without being specific about the structure.
   189    ErrorResult:
   190      type: object
   191      properties:
   192          error:
   193            type: object
   194            properties:
   195              type:
   196                type: string
   197                description: The error type.
   198              title:
   199                type: string
   200                description: A descriptive title for this error.
   201              status:
   202                type: integer
   203                description: The HTTP status code of this error, e.g. 4xx or 5xx.
   204              detail:
   205                type: string
   206              instance:
   207                type: string
   208          next_request:
   209            $ref: "#/definitions/NextRequest"
   210  
   211    NearestResult:
   212      type: object
   213      properties:
   214          next_request:
   215            $ref: "#/definitions/NextRequest"
   216            description: The next request defines the earliest time that a client
   217              should make a new request using the included URL.
   218          results:
   219            type: array
   220            items:
   221              type: object
   222              properties:
   223                machine:
   224                  type: string
   225                  description: The machine name that all URLs reference.
   226                location:
   227                  type: object
   228                  additionalProperties: {}
   229                  description: The machine location metadata.
   230                urls:
   231                  type: object
   232                  additionalProperties: {}
   233                  description: Specific service URLs with access tokens.
   234  
   235    NextRequest:
   236      type: object
   237      properties:
   238        nbf:
   239          type: string
   240          description: |-
   241            "not before" defines the time after which the URL will
   242            become valid. This value is the same time used in "nbf" field of
   243            the underlying JSON Web Token (JWT) claim. To show this equivalence,
   244            we use the same name.
   245        exp:
   246          type: string
   247          description: |-
   248            Expires defines the time after which the URL will be invalid.
   249            Expires will always be greater than NotBefore. This value is the
   250            same time used in the "exp" field of the underlying JWT claim.
   251        url:
   252          type: string
   253          description: |-
   254            URL should be used to make the next request to the location service.
   255  
   256  securityDefinitions:
   257    # This section configures basic authentication with an API key.
   258    # Paths configured with api_key security require an API key for all requests.
   259    api_key:
   260      type: "apiKey"
   261      description: |-
   262        An API key for your client integration restricted to the Locate API and
   263        allocated using a self-service [signup](https://docs.google.com/forms/d/e/1FAIpQLSeWMiPSRWHIcg5GVRG-oc5kkefLpR4Nqk4aNYBFK6Wr8jAAdw/viewform)
   264        or allocated by M-Lab for your client integration.
   265      name: "key"
   266      in: "query"
   267  
   268  tags:
   269    - name: public
   270      description: Public API.
   271    - name: platform
   272      description: Platform API.