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
              - chromium_usage_asc
              - chromium_usage_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/features/{feature_id}/stats/usage/chromium/daily_stats:
    parameters:
      - name: feature_id
        in: path
        description: Feature ID
        required: true
        schema:
          type: string
    get:
      summary: Get Chromium daily usage metrics for a given feature
      operationId: listChromiumDailyUsageStats
      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/ChromiumDailyStatsPage'
        '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}/missing_one_implementation_counts:
    parameters:
      - $ref: '#/components/parameters/browserPathParam'
    get:
      summary: >
        Returns the count of features that are supported by all of the specified
        comparison browsers but not supported by the specified target browser,
        as of each browser's (target browser or comparison browser) release
        date.
      operationId: listMissingOneImplemenationCounts
      parameters:
        - $ref: '#/components/parameters/startAtParam'
        - $ref: '#/components/parameters/endAtParam'
        - $ref: '#/components/parameters/paginationTokenParam'
        - $ref: '#/components/parameters/paginationSizeParam'
        - in: query
          name: browser
          description: >
            A list of browsers to check if {browser} is lagging behind on
            features. The list is provided by specifying repeating query parameters.
            Example: ?browser=fooBrowser&browser=bazBrowser
          required: true
          schema:
            type: array
            items:
              $ref: '#/components/schemas/SupportedBrowsers'
      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: featureId
          description: >
            A list of feature IDs to filter results. TThe list is provided by
            specifying repeating query parameters.
            Example: ?featureId=id1&featureId=id2
          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'
  /v1/saved-searches:
    get:
      summary: List saved searches
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SavedSearchPage'
  /v1/saved-searches/{search_id}:
    parameters:
      - name: search_id
        in: path
        description: Saved Search ID
        required: true
        schema:
          type: string
    get:
      summary: Get saved search
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SavedSearchResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicErrorModel'
components:
  parameters:
    browserPathParam:
      in: path
      name: browser
      description: Browser name
      required: true
      schema:
        $ref: '#/components/schemas/SupportedBrowsers'
    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:
    SupportedBrowsers:
      type: string
      description: List of supported browsers that webstatus.dev currently ingests
      enum:
        - chrome
        - firefox
        - safari
        - edge
    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
    ChromiumUsageStat:
      type: object
      properties:
        timestamp:
          type: string
          format: date-time
          description: The usage timestamp
        usage:
          type: number
          description: >
            Snapshot of the usage metric for the given feature
          format: double
          minimum: 0.0
          maximum: 100.0
      required:
        - timestamp
    WPTRunMetricsPage:
      type: object
      properties:
        metadata:
          $ref: '#/components/schemas/PageMetadata'
        data:
          type: array
          items:
            $ref: '#/components/schemas/WPTRunMetric'
      required:
        - data
    ChromiumDailyStatsPage:
      type: object
      properties:
        metadata:
          $ref: '#/components/schemas/PageMetadata'
        data:
          type: array
          items:
            $ref: '#/components/schemas/ChromiumUsageStat'
      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)
        version:
          type: string
          description: The browser version in which the feature became available.
    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
    GenericUpdatableUniqueModel:
      type: object
      properties:
        id:
          type: string
        updated_at:
          type: string
          format: date-time
        created_at:
          type: string
          format: date-time
      required:
        - id
        - created_at
    SavedSearch:
      type: object
      properties:
        name:
          type: string
        query:
          type: string
      required:
        - name
        - query
    SavedSearchResponse:
      allOf:
        - $ref: '#/components/schemas/GenericUpdatableUniqueModel'
        - $ref: '#/components/schemas/SavedSearch'
        - type: object
          properties:
            subscription_status:
              type: string
              description: |
                The subscription status for a saved search for a user.
                This field is only populated when the request is authenticated.
              enum:
                - none
                - active
            owner_status:
              type: string
              description: |
                The owner status for a saved search for a user.
                This field is only populated when the request is authenticated.
              enum:
                - none
                - admin
    SavedSearchPage:
      type: object
      properties:
        metadata:
          $ref: '#/components/schemas/PageMetadata'
        data:
          type: array
          items:
            $ref: '#/components/schemas/SavedSearchResponse'
    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:
          $ref: '#/components/schemas/BrowserUsage'
        wpt:
          $ref: '#/components/schemas/FeatureWPTSnapshots'
      required:
        - feature_id
        - name
        - baseline_status
    BrowserUsage:
      type: object
      properties:
        chromium:
          $ref: '#/components/schemas/ChromiumUsageInfo'
    ChromiumUsageInfo:
      type: object
      properties:
        daily:
          type: number
          format: double
          description: >
            Latest snapshot of the usage metric for the given feature.
          minimum: 0.0
          maximum: 100.0
    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