287 lines
7.5 KiB
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.
|