openapi.yaml

# Copyright 2023 Google LLC
#
# 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
#
#     http://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.

openapi: '3.0.2'
info:
  title: API Title
  version: '1.0'
servers:
  - url: https://api.server.test/v1
paths:
  /v1/features:
    get:
      summary: List features
      parameters:
        - $ref: '#/components/parameters/paginationTokenParam'
        - $ref: '#/components/parameters/paginationSizeParam'
        - in: query
          name: wpt_metric_view
          schema:
            $ref: '#/components/schemas/WPTMetricView'
        - in: query
          name: q
          description: >
            A query string to represent the filters to apply the datastore while searching.
            The query must follow the ANTLR grammar. Please read the query readme at antlr/FeatureSearch.md.
            The query must be url safe.
          required: false
          schema:
            type: string
            minLength: 1
        - in: query
          name: sort
          description: >
            Field to sort by, with 'asc' for ascending and 'desc' for descending order.
            Defaults to sorting by 'name' in ascending order (e.g., 'name_asc').
          required: false
          schema:
            type: string
            enum:
              - name_asc
              - name_desc
              - baseline_status_asc
              - baseline_status_desc
              - stable_chrome_asc
              - stable_chrome_desc
              - stable_safari_asc
              - stable_safari_desc
              - stable_edge_asc
              - stable_edge_desc
              - stable_firefox_asc
              - stable_firefox_desc
              - experimental_chrome_asc
              - experimental_chrome_desc
              - experimental_safari_asc
              - experimental_safari_desc
              - experimental_edge_asc
              - experimental_edge_desc
              - experimental_firefox_asc
              - experimental_firefox_desc
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeaturePage'
        '400':
          description: Bad Input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '429':
          description: Rate Limit
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '500':
          description: Internal Service Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
  /v1/features/{feature_id}:
    parameters:
      - name: feature_id
        in: path
        description: Feature ID
        required: true
        schema:
          type: string
      - in: query
        name: wpt_metric_view
        schema:
          $ref: '#/components/schemas/WPTMetricView'
    get:
      summary: Get Feature
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Feature'
        '400':
          description: Bad Input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '429':
          description: Rate Limit
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '500':
          description: Internal Service Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
  /v1/features/{feature_id}/feature-metadata:
    parameters:
      - name: feature_id
        in: path
        description: Feature ID
        required: true
        schema:
          type: string
    get:
      summary: Get metadata for a given feature from github.com/web-platform-dx/web-features
      operationId: getFeatureMetadata
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeatureMetadata'
        '400':
          description: Bad Input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '429':
          description: Rate Limit
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '500':
          description: Internal Service Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
  /v1/features/{feature_id}/stats/wpt/browsers/{browser}/channels/{channel}/{metric_view}:
    parameters:
      - name: feature_id
        in: path
        description: Feature ID
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/browserPathParam'
      - $ref: '#/components/parameters/channelPathParam'
      - $ref: '#/components/parameters/metricViewPathParam'
    get:
      summary: Retrieve the wpt stats for a particular feature.
      operationId: listFeatureWPTMetrics
      parameters:
        - $ref: '#/components/parameters/startAtParam'
        - $ref: '#/components/parameters/endAtParam'
        - $ref: '#/components/parameters/paginationTokenParam'
        - $ref: '#/components/parameters/paginationSizeParam'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WPTRunMetricsPage'
        '400':
          description: Bad Input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '429':
          description: Rate Limit
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '500':
          description: Internal Service Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
  /v1/stats/features/browsers/{browser}/feature_counts:
    parameters:
      - $ref: '#/components/parameters/browserPathParam'
    get:
      summary: >
        Returns the count of features supported for a specified browser over time.
        The timestamps for the individual metrics represent the releases of the
        specified browser.
      operationId: listAggregatedFeatureSupport
      parameters:
        - $ref: '#/components/parameters/startAtParam'
        - $ref: '#/components/parameters/endAtParam'
        - $ref: '#/components/parameters/paginationTokenParam'
        - $ref: '#/components/parameters/paginationSizeParam'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrowserReleaseFeatureMetricsPage'
        '400':
          description: Bad Input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '429':
          description: Rate Limit
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '500':
          description: Internal Service Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
  /v1/stats/features/browsers/{browser}/feature_lag_counts:
    parameters:
      - $ref: '#/components/parameters/browserPathParam'
    get:
      summary: >
        Returns the count of features where the specified browser has a feature
        lag compared to other browsers at a given time. The timestamps represent
        releases of the specified browser or one of the comparison browsers.
      operationId: listFeatureLagMetrics
      parameters:
        - $ref: '#/components/parameters/startAtParam'
        - $ref: '#/components/parameters/endAtParam'
        - $ref: '#/components/parameters/paginationTokenParam'
        - $ref: '#/components/parameters/paginationSizeParam'
        - in: query
          name: browsers
          description: >
            A comma-separated list of browsers to check if {browser} is lagging
            behind on features.
          required: true
          schema:
            type: array
            items:
              type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrowserReleaseFeatureMetricsPage'
        '400':
          description: Bad Input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '429':
          description: Rate Limit
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '500':
          description: Internal Service Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
  /v1/stats/wpt/browsers/{browser}/channels/{channel}/{metric_view}:
    parameters:
      - $ref: '#/components/parameters/browserPathParam'
      - $ref: '#/components/parameters/channelPathParam'
      - $ref: '#/components/parameters/metricViewPathParam'
    get:
      summary: >
        Gets aggregated WPT test counts for a specified browser and channel. Optionally filter by feature IDs.
      operationId: listAggregatedWPTMetrics
      parameters:
        - $ref: '#/components/parameters/startAtParam'
        - $ref: '#/components/parameters/endAtParam'
        - $ref: '#/components/parameters/paginationTokenParam'
        - $ref: '#/components/parameters/paginationSizeParam'
        - in: query
          name: featureIds
          description: A comma-separated list of feature IDs to filter results.
          required: false
          schema:
            type: array
            items:
              type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WPTRunMetricsPage'
        '400':
          description: Bad Input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '429':
          description: Rate Limit
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
        '500':
          description: Internal Service Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
components:
  parameters:
    browserPathParam:
      in: path
      name: browser
      description: Browser name
      required: true
      schema:
        type: string
        # List of supported browsers that webstatus.dev currently ingests
        enum:
          - chrome
          - firefox
          - safari
          - edge
    channelPathParam:
      in: path
      name: channel
      description: Browser name
      required: true
      schema:
        type: string
        # List of supported channels that webstatus.dev currently ingests
        enum:
          - stable
          - experimental
    metricViewPathParam:
      in: path
      name: metric_view
      description: Specified metric view of the WPT data.
      required: true
      schema:
        $ref: '#/components/schemas/WPTMetricView'
    startAtParam:
      in: query
      name: startAt
      schema:
        type: string
        format: date
      description: Start date (RFC 3339, section 5.6, for example, 2017-07-21). The date is inclusive.
      required: true
    endAtParam:
      in: query
      name: endAt
      schema:
        type: string
        format: date
      description: End date (RFC 3339, section 5.6, for example, 2017-07-21). The date is exclusive.
      required: true
    paginationTokenParam:
      in: query
      name: page_token
      schema:
        type: string
      description: Pagination token
      required: false
    paginationSizeParam:
      in: query
      name: page_size
      schema:
        type: integer
        maximum: 100
        minimum: 1
        default: 1
      required: false
      description: Number of results to return
  schemas:
    WPTMetricView:
      type: string
      description: The desired view of the WPT Data
      enum:
        - test_counts
        - subtest_counts
    BrowserReleaseFeatureMetric:
      type: object
      properties:
        timestamp:
          type: string
          format: date-time
          description: >
            The timestamp that correlates to an event that may influence the
            count of features for a browser. This may be the release of the
            browser itself (when a browser may support a new set of features),
            or the release of another browser (when another browser supports
            a feature but our specified browser is now lagging behind with a new
            feature). Refer to the individual endpoint for more context on the
            use of this component.
        count:
          type: integer
          description: Total count of features.
          format: int64
      required:
        # For now, only require timestamp in case the definition
        # of the metric needs to change. Similar to WPTRunMetric.
        - timestamp
    BrowserReleaseFeatureMetricsPage:
      type: object
      properties:
        metadata:
          $ref: '#/components/schemas/PageMetadata'
        data:
          type: array
          items:
            $ref: '#/components/schemas/BrowserReleaseFeatureMetric'
      required:
        - data
    WPTRunMetric:
      type: object
      properties:
        run_timestamp:
          type: string
          format: date-time
          description: The start timestamp of the run.
        total_tests_count:
          type: integer
          description: Total number of tests
          format: int64
        test_pass_count:
          type: integer
          description: Number of passing tests
          format: int64
      required:
        - run_timestamp
    WPTRunMetricsPage:
      type: object
      properties:
        metadata:
          $ref: '#/components/schemas/PageMetadata'
        data:
          type: array
          items:
            $ref: '#/components/schemas/WPTRunMetric'
      required:
        - data
    WPTFeatureData:
      type: object
      properties:
        score:
          type: number
          format: double
        metadata:
          type: object
          description: >
            Contains optional metadata about the metric. This key-value pair is to be considered unstable and can change
            at any moment. If a field here becomes mature, we can add it to the main WPTFeatureData definition.
          additionalProperties: true
    BrowserImplementation:
      type: object
      properties:
        status:
          type: string
          enum:
            - unavailable
            - available
          # Go enum names
          x-enum-varnames:
            - Unavailable
            - Available
        date:
          type: string
          format: date
          description: The date on which the feature was implemented in a browser. (RFC 3339, section 5.6, for example, 2017-07-21)
    PageMetadata:
      type: object
      properties:
        next_page_token:
          type: string
    PageMetadataWithTotal:
      type: object
      properties:
        next_page_token:
          type: string
        total:
          type: integer
          format: int64 # Currently, 'count(*)' from spanner comes as int64 https://cloud.google.com/spanner/docs/reference/standard-sql/data-types
      required:
        - total
    FeaturePage:
      type: object
      properties:
        metadata:
          $ref: '#/components/schemas/PageMetadataWithTotal'
        data:
          type: array
          items:
            $ref: '#/components/schemas/Feature'
      required:
        - data
        - metadata
    FeatureWPTSnapshots:
      type: object
      properties:
        stable:
          type: object
          description: >
            Contains snapshot of the stable WPT data. The keys for the
            object comes from the different cases in
            https://github.com/web-platform-tests/wpt.fyi/blob/fb5bae7c6d04563864ef1c28a263a0a8d6637c4e/shared/product_spec.go#L71-L104
          additionalProperties:
            $ref: '#/components/schemas/WPTFeatureData'
        experimental:
          type: object
          description: >
            Contains snapshot of the experimental WPT data. The keys for the
            object comes from the different cases in
            https://github.com/web-platform-tests/wpt.fyi/blob/fb5bae7c6d04563864ef1c28a263a0a8d6637c4e/shared/product_spec.go#L71-L104
          additionalProperties:
            $ref: '#/components/schemas/WPTFeatureData'
    BaselineInfo:
      type: object
      description: Contains baseline information for a feature.
      properties:
        status:
          type: string
          enum:
            - limited
            - newly
            - widely
        low_date:
          type: string
          format: date
        high_date:
          type: string
          format: date
    FeatureSpecInfo:
      type: object
      properties:
        links:
          type: array
          items:
            $ref: '#/components/schemas/SpecLink'
    SpecLink:
      type: object
      properties:
        link:
          type: string
    FeatureMetadata:
      type: object
      properties:
        can_i_use:
          $ref: '#/components/schemas/CanIUseInfo'
        description:
          type: string
    CanIUseInfo:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/CanIUseItem'
    CanIUseItem:
      properties:
        id:
          type: string
    Feature:
      type: object
      properties:
        feature_id:
          type: string
        name:
          type: string
          description: >
            Short name that is intended to be human friendly.
            Comes from FeatureData's 'name' field in
            https://github.com/web-platform-dx/web-features/blob/main/schemas/defs.schema.json
        spec:
          $ref: '#/components/schemas/FeatureSpecInfo'
        browser_implementations:
          type: object
          description: >
            Describes the implementation status of the feature. The keys for the object come
            from https://github.com/web-platform-dx/web-features/blob/8ab08d00b9bdb505af37c435204eb6fe819dfaab/schemas/defs.schema.json#L102-L122
          additionalProperties:
            $ref: '#/components/schemas/BrowserImplementation'
        baseline:
          $ref: '#/components/schemas/BaselineInfo'
        usage:
          type: number
          format: float
          description: >
            Latest snapshot of the usage metric for the given feature.
          minimum: 0.0
          maximum: 100.0
        wpt:
          $ref: '#/components/schemas/FeatureWPTSnapshots'
      required:
        - feature_id
        - name
        - baseline_status
    BasicErrorModel:
      type: object
      required:
        - message
        - code
      properties:
        message:
          type: string
        code:
          type: integer
          minimum: 100
          maximum: 600
    ExtendedErrorModel:
      allOf: # Combines the BasicErrorModel and the inline model
        - $ref: '#/components/schemas/BasicErrorModel'
        - type: object
          required:
            - rootCause
          properties:
            rootCause:
              type: string