Bluemage/schemas/openapi/reddit.yaml

287 lines
7.5 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
- in: header
name: User-Agent
schema:
type: string
default: bluemage/v1
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
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.