From 230138cecd6ad2b2cafc81767e10bb34f0df2c4e Mon Sep 17 00:00:00 2001 From: Tigor Hutasuhut Date: Sun, 11 Aug 2024 16:25:11 +0700 Subject: [PATCH] reddit: added openapi spec --- schemas/openapi/reddit.yaml | 272 ++++++++++++++++++++++++++++++++++++ 1 file changed, 272 insertions(+) create mode 100644 schemas/openapi/reddit.yaml diff --git a/schemas/openapi/reddit.yaml b/schemas/openapi/reddit.yaml new file mode 100644 index 0000000..4fa4341 --- /dev/null +++ b/schemas/openapi/reddit.yaml @@ -0,0 +1,272 @@ +openapi: 3.0.3 +info: + title: Reddit JSON Listing API + description: JSON api listing for Subreddits and Users. + 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": "", + "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: getSubredditListing + responses: + "200": + description: success + content: + application/json: + schema: + $ref: "#/components/schemas/ListingResponse" + +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: + oneOf: + - $ref: "#/components/schemas/T1" + - $ref: "#/components/schemas/T3" + T1: + type: object + description: |- + This is listed because this item type is a possibility. + + `t1` item type is unwanted for fetching image posts since + it only contains comment data. + properties: + kind: + type: string + enum: + - t1 + T3: + type: object + description: |- + `t3` item type is a post (link) data. + + This is the item type to look for image posts. + + Not all fields are listed here, only fields that are relevant are + listed to reduce deserializing errors. + properties: + kind: + type: string + enum: + - t3 + data: + $ref: "#/components/schemas/T3Data" + + T3Data: + type: object + required: + - subreddit + - title + - name + 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.