reddit: added openapi spec
This commit is contained in:
parent
8ff3bc4fd8
commit
230138cecd
272
schemas/openapi/reddit.yaml
Normal file
272
schemas/openapi/reddit.yaml
Normal file
|
|
@ -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": "<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: 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.
|
||||
Loading…
Reference in a new issue