Bluemage/schemas/openapi/reddit.yaml

267 lines
6.9 KiB
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.