openapi.yml

openapi: '3.0.3'
info:
  title: Firefox API Proxy
  version: '0.3'
  license:
    name: ISC
    url: https://opensource.org/licenses/ISC
servers:
  - url: https://firefox-api-proxy.readitlater.com
    description: Production environment
  - url: https://firefox-api-proxy.getpocket.dev
    description: Development environment
  - url: http://localhost:4028
    description: Local default port

#common components referenced across multiple paths
components:
  # Common schema definitions
  schemas:
    Error:
      type: object
      properties:
        id:
          type: string
          description: A unique identifier for this particular instance of the error
        status:
          type: string
          description: HTTP status code string associated with the response
        title:
          type: string
          description: A short human readable summary of the error
        detail:
          type: string
          description: A more detailed explanation of the error intended for human debugging
        source:
          type: object
          description: An object containing references to the source of the error
          properties:
            parameters:
              type: string
              description: String indicating which URI query parameter caused the error
            graphQLError:
              type: string
              description: An upstream GraphQLError. These are intended for human consumption. The upstream graph is not expected to provide a stable API for these, and they will change without warning. Do not parse these in Firefox.
    ErrorResponse:
      type: object
      required:
        - errors
      properties:
        errors:
          description: An array of error objects
          type: array
          items:
            oneOf:
              - $ref: '#/components/schemas/Error'
    Save:
      type: object
      required:
        - __typename
        - id
        - givenUrl
      properties:
        __typename:
          type: string
          description: Constant identifier for Saves, allowing them to be differentiated when multiple types are returned together.
          enum:
            - Save
        id:
          type: string
          description: The Saved Item ID.
        resolvedUrl:
          type: string
          nullable: true
          description: Resolved URL for a saved item. This includes following any redirects and any parser normalization.
        givenUrl:
          type: string
          description: The URL the user saved to their list.
        title:
          type: string
          nullable: true
          description: The title of the saved item as resolved by the parser.
        excerpt:
          type: string
          nullable: true
          description: An excerpt from the saved item as resolved by the parser.
        domain:
          type: string
          nullable: true
          description: The Domain of the saved item
        wordCount:
          type: number
          nullable: true
          description: Numeric string, word count of the item. May be 0 if parsing fails
        timeToRead:
          type: number
          nullable: true
          description: Approximate minutes to read the item, based on word_count
        topImageUrl:
          type: string
          nullable: true
          description: Primary image from the saved item as resolved by the parser.
    PendingSave:
      type: object
      required:
        - id
        - givenUrl
        - __typename
      properties:
        __typename:
          type: string
          description: Constant identifier for PendingSave, allowing them to be differentiated when multiple types are returned together.
          enum:
            - PendingSave
        id:
          type: string
          description: The Saved Item ID.
        givenUrl:
          type: string
          description: The URL the user saved to their list.
    Recommendation:
      type: object
      description: These items contain similar content to saves, but have been through a curation process and have more guaranteed data.
      required:
        - __typename
        - tileId
        - url
        - title
        - excerpt
        - publisher
        - imageUrl
      properties:
        __typename:
          type: string
          description: Constant identifier for Recommendation type objects.
          enum:
            - Recommendation
        recommendationId:
          type: string
          description: String identifier for the Recommendation. This value is expected to be different on each request.
        tileId:
          type: number
          deprecated: true
          description: Numerical identifier for the Recommendation. This is specifically a number for Fx client and Mozilla data pipeline compatibility. This property will continue to be present because Firefox clients depend on it, but downstream users should use the recommendation id instead when available.
        url:
          type: string
          description: The URL the Recommendation.
        title:
          type: string
          description: The title of the Recommendation.
        excerpt:
          type: string
          description: An excerpt from the Recommendation.
        publisher:
          type: string
          description: The publisher of the Recommendation.
        imageUrl:
          type: string
          description: The primary image for a Recommendation.
        timeToRead:
          type: integer
          description: Article read time in minutes

    LegacyFeedItem:
      type: object
      required:
        - id
        - title
        - url
        - excerpt
        - domain
        - image_src
        - raw_image_src
      properties:
        id:
          type: integer
        title:
          type: string
        url:
          type: string
        excerpt:
          type: string
        domain:
          type: string
        image_src:
          type: string
        raw_image_src:
          type: string
        time_to_read:
          type: integer

    LegacySettings:
      type: object
      properties:
        spocsPerNewTabs:
          type: number
        domainAffinityParameterSets:
          type: object
        timeSegments:
          type: array
          items:
            type: object
            required:
              - id
              - startTime
              - endTime
              - weightPosition
            properties:
              id:
                type: string
              startTime:
                type: integer
              endTime:
                type: integer
              weightPosition:
                type: number
        recsExpireTime:
          type: integer
        version:
          type: string

  # securitySchemes roughly map to authentication middleware
  securitySchemes:
    # The following schemes prefixed with "WS" all constitute a `WebSession` auth.
    # These are all required together for requests that require this auth type.
    WSUserAuth:
      type: apiKey
      in: cookie
      name: a95b4b6
      description: A portion of `WebSession` legacy auth. A hash of the user's ID.
    WSSessionAuth:
      type: apiKey
      in: cookie
      name: d4a79ec
      description: A portion of `WebSession` legacy auth. A hash of the session.
    WSLookupAuth:
      type: apiKey
      in: cookie
      name: 159e76e
      description: A portion of `WebSession` legacy auth. Session lookup.
    WSConsumerKeyAuth:
      type: apiKey
      in: query
      name: consumer_key
      description: A portion of `WebSession` legacy auth.
    # Originally tried to support this via headers and will continue to support
    # this alternative, however I suspect this may be causing issues. _ is not
    # valid character in headers. Many services allow this through, and this works
    # the overwhelming majority of the time. However, there have been client reports
    # of rejecting requests due to missing consumer_key, and I suspect some edge case
    # could be removing this.
    #
    # Avoiding confusion around renaming, and just preferring query params first.
    WSConsumerKeyAuthAlias:
      type: apiKey
      in: header
      name: consumer_key
      description: A portion of `WebSession` legacy auth. This isn't actually a valid header (_ is not permitted), prefer query param.

paths:
  /desktop/v1/recommendations:
    get:
      summary: Gets a list of Recommendations for a Locale and Region. This operation is performed anonymously and requires no auth.
      description: Supports Fx desktop version 114 and up.
      operationId: getRecommendations
      # Intentionally blank security. No auth required.
      security:
        - WSConsumerKeyAuth: []
        - WSConsumerKeyAuthAlias: []
      parameters:
        - name: count
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            # Do not exceed maxPageSize https://github.com/Pocket/list-api/blob/main/src/config/index.ts#L107
            maximum: 30
            default: 30
          description: The number of items to return.
        - name: locale
          in: query
          required: true
          description: This locale string is Fx domain language, and built from Fx expectations. Parameter values are not case sensitive.
          schema:
            type: string
            enum: [
                # relevant docs: https://docs.google.com/document/d/1omclr-eETJ7zAWTMI7mvvsc3_-ns2Iiho4jPEfrmZfo

                # fr, es, it are served through this API in Firefox 114,
                # and we plan to migrate all NewTab markets in Firefox 116:
                fr,
                fr-FR,
                es,
                es-ES,
                it,
                it-IT,
                en,
                en-CA,
                en-GB,
                en-US,
                de,
                de-DE,
                de-AT,
                de-CH,
              ]
        - name: region
          in: query
          required: false
          description: This region string is Fx domain language, and built from Fx expectations. Parameter values are not case sensitive. See [Firefox Home & New Tab Regional Differences](https://mozilla-hub.atlassian.net/wiki/spaces/FPS/pages/80448805/Regional+Differences).
          schema:
            type: string
        - name: enableRankingByRegion
          in: query
          required: false
          description: Returns recommendations specific to the region if set to 1.
          schema:
            type: integer
            enum: [0, 1]
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: array
                    items:
                      oneOf:
                        - $ref: '#/components/schemas/Recommendation'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: This proxy service encountered an unexpected error.
        '502':
          description: Services downstream from this proxy encountered an unexpected error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '504':
          description: Requests to downstream services timed out.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v3/firefox/global-recs:
    get:
      deprecated: true
      summary: Used by older versions of Firefox to get a list of Recommendations for a Locale and Region. This operation is performed anonymously and requires no auth.
      description: Supports Fx desktop version 115 and below.
      operationId: getGlobalRecs
      # Intentionally blank security. No auth required.
      security:
        - WSConsumerKeyAuth: []
        - WSConsumerKeyAuthAlias: []
      parameters:
        - in: query
          name: version
          description: API version
          required: true
          schema:
            type: integer
            minimum: 3
            maximum: 3
            default: 3
        - in: query
          name: locale_lang
          description: Firefox locale
          required: true
          schema:
            type: string
            default: en-US
        - in: query
          name: region
          description: Firefox region
          required: false
          schema:
            type: string
        - in: query
          name: count
          description: Maximum number of items to return
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 50
            default: 20
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                  - status
                  - spocs
                  - settings
                  - recommendations
                properties:
                  status:
                    type: integer
                    enum:
                      - 1
                  spocs:
                    type: array
                  settings:
                    $ref: '#/components/schemas/LegacySettings'
                  recommendations:
                    type: array
                    items:
                      $ref: '#/components/schemas/LegacyFeedItem'
        '404':
          description: Invalid request parameters. Originally this was a 400 but to allow for caching via https://cloud.google.com/cdn/docs/using-negative-caching it is now a 404.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: This proxy service encountered an unexpected error.
        '502':
          description: Services downstream from this proxy encountered an unexpected error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '504':
          description: Requests to downstream services timed out.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /desktop/v1/recent-saves:
    get:
      summary: Gets a list of the most recent saves for a specific user.
      description: Supports Fx desktop version 113 and up.
      operationId: getRecentSaves
      security:
        # require all WS (WebSession) security schemes together
        - WSUserAuth: []
          WSSessionAuth: []
          WSLookupAuth: []
          WSConsumerKeyAuth: []
        - WSUserAuth: []
          WSSessionAuth: []
          WSLookupAuth: []
          WSConsumerKeyAuthAlias: []
      parameters:
        - name: count
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            # Do not exceed maxPageSize https://github.com/Pocket/list-api/blob/main/src/config/index.ts#L107
            # starting small, always easy to increase max but difficult to shrink
            maximum: 20
            default: 10
          description: The number of items to return.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: array
                    items:
                      oneOf:
                        - $ref: '#/components/schemas/Save'
                        - $ref: '#/components/schemas/PendingSave'
        '404':
          description: Invalid request parameters. Originally this was a 400 but to allow for caching via https://cloud.google.com/cdn/docs/using-negative-caching it is now a 404.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authorization is missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: This proxy service encountered an unexpected error.
        '502':
          description: Services downstream from this proxy encountered an unexpected error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '504':
          description: Requests to downstream services timed out.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'