Bluemage/schemas/openapi/reddit.yaml

openapi: 3.0.3
info:
  title: Reddit JSON Listing API
  description: |-
    JSON api listing for Subreddits and Users.

    Request must have `User-Agent` header set to custom values and not empty.
  version: v1
servers:
  - url: https://reddit.com
    description: Reddit
tags:
  - name: Listing
    description: API listing
paths:
  /{type}/{name}.json:
    get:
      tags:
        - Listing
      summary: Get Subreddit Listings
      description: |-
        Fetches subreddit listing.

        If the subreddit name does not exist (case insensitive),
        this endpoint will redirect to `/subreddits/search.json?q={name}`
        with this kind of response body:

        ```json
        {
            "kind": "Listing",
            "data": {
                "after": null,
                "dist": 0,
                "modhash": "<hash>",
                "geo_filter": "",
                "children": [],
                "before": null
            }
        }
        ```

        Currently, Best way to check wether the subreddit exists or not
        is the `data.after` and `data.before` is null, and `data.children` array is empty.

        To get the proper casing of Subreddit name, take the
        first element in `data.children` and takes it subreddit name.

        So target this: `data.children[0].data.subreddit` to get proper
        subreddit name.

        To get the proper casing of a user name, target `data.children[0].data.author`.

        In the `data.children[].data` there are two possible `kind` values:
          - `t1`
          - `t3`

        `t1` represents data is a comment data, while `t3` is a Link (Post) data.

        What we want the most is `t3` type of data. So `t1` type of data should
        be skipped.
      parameters:
        - in: path
          name: type
          schema:
            type: string
            enum:
              - r
              - user
          required: true
          description: |-
            The type of listing to fetch.

              * `r` fetches subreddit listing.
              * `user` fetches user listing (comments and posts).
        - in: path
          name: name
          schema:
            type: string
          required: true
          description: |-
            The subreddit / username to fetch.
        - in: query
          name: after
          schema:
            type: string
          description: |-
            `after` can be filled with post `name`.

            Easiest to find this value is in the `response body` on `data.after`.

            `after` tells Reddit to look up posts after this value.

            `after` cannot be used together with `before`.
        - in: query
          name: before
          schema:
            type: string
          description: |-
            like `after` query param, but reversed direction.

            Cannot be used together with `after`.
        - in: query
          name: limit
          schema:
            type: integer
            minimum: 0
            maximum: 100
          description: |-
            The number of posts to fetch.

            If unset, defaults to `25`.

            Maximum value to fetch is `100`.
          example: 25
      operationId: getListing
      responses:
        "200":
          description: success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListingResponse"
        "429":
          description: Too many requests
          content:
            application/json:
              schema:
                type: object
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                type: object

components:
  schemas:
    ListingResponse:
      type: object
      required:
        - kind
        - data
      properties:
        kind:
          type: string
          enum:
            - Listing
        data:
          $ref: "#/components/schemas/ListingData"
    ListingData:
      type: object
      required:
        - after
        - dist
        - modhash
        - geo_filter
        - children
        - before
      properties:
        after:
          type: string
          nullable: true
          example: t3_1ep7k5l
          description: |-
            To get next post, use this value as `after`
            in request query.

            `null` if there's no more posts.
        dist:
          type: integer
          example: 25
          description: |-
            The number of posts fetched.
        modhash:
          type: string
          description: hash of the transaction request
          example: tcxu4bdbnvdbd6206ae0b13557bc8a626e33178f5e2de97c5e
        geo_filter:
          type: string
          nullable: true
          description: Not really known. AFAIK, Always returns null or empty string.
        children:
          type: array
          items:
            $ref: "#/components/schemas/ListingChildData"
    ListingChildData:
      type: object
      required:
        - kind
        - data
      properties:
        kind:
          type: string
          enum:
            - t1
            - t3
        data:
          $ref: "#/components/schemas/ChildData"
    ChildData:
      type: object
      required:
        - subreddit
        - title
        - name
        - author
      properties:
        subreddit:
          type: string
          example: wallpaper
        author_fullname:
          type: string
          example: t2_u9xzkv0h7
        author:
          type: string
          example: foo
        title:
          type: string
          example: Frost
        thumbnail_height:
          type: integer
          example: 140
          nullable: true
        name:
          type: string
          example: t3_1d61g18
          description: unique identifier for this post.
        thumbnail_width:
          type: integer
          example: 140
          nullable: true
        is_reddit_media_domain:
          type: boolean
        thumbnail:
          type: string
          example: https://b.thumbs.redditmedia.com/TXGRPZ_6RbcF8_TQmyvXxNjaXr5bs4NZxfFCc-betlc.jpg
        post_hint:
          type: string
          example: image
        is_self:
          description: |-
            Indicates if post is targeting to the post itself when followed.

            If looking for image posts, this should be `false`.
          type: boolean
        created:
          type: integer
          format: int64
          example: 1717289447
        domain:
          type: string
          example: i.redd.it
        url_overridden_by_dest:
          type: string
          example: https://i.redd.it/qtm2jhl1324d1.png
        over_18:
          type: boolean
        is_video:
          type: boolean
          description: |-
            Indicates if post is a video.

            If looking for image posts, this should be `false`.
        url:
          type: string
          example: https://i.redd.it/un4qe8c2jqj91.png
          description: target url of the post.