mirror of
https://gitlab.com/tildes/tildes.git
synced 2026-04-25 18:50:52 +02:00
Andrew Shu
440 lines
12 KiB
YAML
440 lines
12 KiB
YAML
openapi: 3.0.0
|
|
info:
|
|
title: Tildes Beta API Schema
|
|
version: Beta
|
|
description: |
|
|
This is the OpenAPI schema for the Tildes Beta API.
|
|
The beta API is subject to change and may not be fully stable.
|
|
Future updates WILL include breaking changes.
|
|
Use at your own risk.
|
|
servers:
|
|
- url: /api/beta
|
|
paths:
|
|
/topics:
|
|
get:
|
|
summary: Get a list of topics
|
|
parameters:
|
|
- $ref: '#/components/parameters/paginationLimit'
|
|
- $ref: '#/components/parameters/paginationBefore'
|
|
- $ref: '#/components/parameters/paginationAfter'
|
|
- in: query
|
|
name: period
|
|
schema:
|
|
type: string
|
|
default: "all"
|
|
required: false
|
|
description: The time period for which to retrieve topics. For example "4h" or "2d".
|
|
- in: query
|
|
name: tag
|
|
schema:
|
|
type: string
|
|
required: false
|
|
description: The tag to filter topics by. If not specified, topics are not filtered on their tags.
|
|
- in: query
|
|
name: order
|
|
schema:
|
|
type: string
|
|
default: "activity"
|
|
enum: ["activity", "votes", "comments", "new", "all_activity"]
|
|
required: false
|
|
description: The sort order for the topics. Defaults to "activity".
|
|
responses:
|
|
"200":
|
|
description: A list of topics
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required:
|
|
- topics
|
|
- pagination
|
|
properties:
|
|
topics:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/Topic'
|
|
pagination:
|
|
$ref: '#/components/schemas/Pagination'
|
|
"400":
|
|
$ref: "#/components/responses/ValidationError"
|
|
|
|
/topic/{topic_id36}:
|
|
get:
|
|
summary: Get a single topic and its comments
|
|
parameters:
|
|
- in: path
|
|
name: topic_id36
|
|
schema:
|
|
type: string
|
|
required: true
|
|
description: The ID36 of the topic to retrieve.
|
|
- in: query
|
|
name: order
|
|
schema:
|
|
type: string
|
|
default: "relevance"
|
|
enum: ["votes", "newest", "posted", "relevance"]
|
|
required: false
|
|
description: The sort order for the comment tree. Defaults to "relevance".
|
|
responses:
|
|
"200":
|
|
description: A single topic and its comments
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required:
|
|
- topic
|
|
- comments
|
|
properties:
|
|
topic:
|
|
$ref: '#/components/schemas/Topic'
|
|
comments:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/Comment'
|
|
"400":
|
|
$ref: "#/components/responses/ValidationError"
|
|
|
|
/user/{username}:
|
|
get:
|
|
summary: Get a user along with their history
|
|
parameters:
|
|
- in: path
|
|
name: username
|
|
schema:
|
|
type: string
|
|
required: true
|
|
description: The username of the user to retrieve.
|
|
- $ref: '#/components/parameters/paginationLimit'
|
|
- $ref: '#/components/parameters/paginationBefore'
|
|
- $ref: '#/components/parameters/paginationAfter'
|
|
responses:
|
|
"200":
|
|
description: Basic user information and their post/comment history
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required:
|
|
- user
|
|
- history
|
|
- pagination
|
|
properties:
|
|
user:
|
|
$ref: '#/components/schemas/User'
|
|
history:
|
|
type: array
|
|
items:
|
|
anyOf:
|
|
- $ref: '#/components/schemas/Topic'
|
|
- $ref: '#/components/schemas/Comment'
|
|
pagination:
|
|
$ref: '#/components/schemas/Pagination'
|
|
"400":
|
|
$ref: "#/components/responses/ValidationError"
|
|
"403":
|
|
$ref: "#/components/responses/AuthorizationError"
|
|
|
|
/user/{username}/comments:
|
|
get:
|
|
summary: Get comments made by a user
|
|
parameters:
|
|
- in: path
|
|
name: username
|
|
schema:
|
|
type: string
|
|
required: true
|
|
description: The username of the user for whom to retrieve comments.
|
|
- $ref: '#/components/parameters/paginationLimit'
|
|
- $ref: '#/components/parameters/paginationBefore'
|
|
- $ref: '#/components/parameters/paginationAfter'
|
|
responses:
|
|
"200":
|
|
description: A list of comments made by the user
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required:
|
|
- comments
|
|
- pagination
|
|
properties:
|
|
comments:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/Comment'
|
|
pagination:
|
|
$ref: '#/components/schemas/Pagination'
|
|
"400":
|
|
$ref: "#/components/responses/ValidationError"
|
|
"403":
|
|
$ref: "#/components/responses/AuthorizationError"
|
|
|
|
/user/{username}/topics:
|
|
get:
|
|
summary: Get topics made by a user
|
|
parameters:
|
|
- in: path
|
|
name: username
|
|
schema:
|
|
type: string
|
|
required: true
|
|
description: The username of the user for whom to retrieve topics.
|
|
- $ref: '#/components/parameters/paginationLimit'
|
|
- $ref: '#/components/parameters/paginationBefore'
|
|
- $ref: '#/components/parameters/paginationAfter'
|
|
responses:
|
|
"200":
|
|
description: A list of topics made by the user
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required:
|
|
- topics
|
|
- pagination
|
|
properties:
|
|
topics:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/Topic'
|
|
pagination:
|
|
$ref: '#/components/schemas/Pagination'
|
|
"400":
|
|
$ref: "#/components/responses/ValidationError"
|
|
"403":
|
|
$ref: "#/components/responses/AuthorizationError"
|
|
|
|
components:
|
|
parameters:
|
|
paginationBefore:
|
|
in: query
|
|
name: before
|
|
schema:
|
|
type: string
|
|
required: false
|
|
description: The ID36 of the first item from the current page, to get items before it. You can only specify either `before` or `after`, not both. In mixed feeds like user profiles, this parameter needs a "t-" or "c-" prefix to indicate topics and comments respectively.
|
|
|
|
paginationAfter:
|
|
in: query
|
|
name: after
|
|
schema:
|
|
type: string
|
|
required: false
|
|
description: The ID36 of the last item from the previous page, to get items after it. You can only specify either `before` or `after`, not both. In mixed feeds like user profiles, this parameter needs a "t-" or "c-" prefix to indicate topics and comments respectively.
|
|
|
|
paginationLimit:
|
|
in: query
|
|
name: limit
|
|
schema:
|
|
type: integer
|
|
minimum: 1
|
|
maximum: 100
|
|
required: false
|
|
description: The maximum number of items to return. The `limit` is itself limited to prevent abuse.
|
|
|
|
responses:
|
|
ValidationError:
|
|
description: OpenAPI request/response validation failed
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/Error"
|
|
AuthorizationError:
|
|
description: You are not authorized to perform this action
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/Error"
|
|
|
|
schemas:
|
|
Topic:
|
|
type: object
|
|
required:
|
|
- id
|
|
- title
|
|
- text_html
|
|
- url
|
|
- comments_url
|
|
- group
|
|
- content_metadata
|
|
- created_at
|
|
- edited_at
|
|
- posted_by_user
|
|
- vote_count
|
|
- comment_count
|
|
- new_comment_count
|
|
- voted
|
|
- bookmarked
|
|
- ignored
|
|
- official
|
|
- tags
|
|
- last_visit_time
|
|
properties:
|
|
id:
|
|
type: string
|
|
title:
|
|
type: string
|
|
text_html:
|
|
type: string
|
|
nullable: true
|
|
url:
|
|
type: string
|
|
nullable: true
|
|
comments_url:
|
|
type: string
|
|
source_site_name:
|
|
type: string
|
|
nullable: true
|
|
source_site_icon:
|
|
type: string
|
|
nullable: true
|
|
group:
|
|
type: string
|
|
content_metadata:
|
|
type: array
|
|
items:
|
|
type: string
|
|
created_at:
|
|
type: string
|
|
edited_at:
|
|
type: string
|
|
nullable: true
|
|
posted_by_user:
|
|
type: string
|
|
vote_count:
|
|
type: integer
|
|
comment_count:
|
|
type: integer
|
|
new_comment_count:
|
|
type: integer
|
|
nullable: true
|
|
voted:
|
|
type: boolean
|
|
nullable: true
|
|
bookmarked:
|
|
type: boolean
|
|
nullable: true
|
|
ignored:
|
|
type: boolean
|
|
nullable: true
|
|
official:
|
|
type: boolean
|
|
tags:
|
|
type: array
|
|
items:
|
|
type: string
|
|
last_visit_time:
|
|
type: string
|
|
nullable: true
|
|
|
|
Comment:
|
|
type: object
|
|
required:
|
|
- id
|
|
- topic_id
|
|
- author
|
|
- rendered_html
|
|
- created_at
|
|
- edited_at
|
|
- votes
|
|
- is_removed
|
|
- is_deleted
|
|
- exemplary
|
|
- voted
|
|
- bookmarked
|
|
properties:
|
|
id:
|
|
type: string
|
|
topic_id:
|
|
type: string
|
|
author:
|
|
type: string
|
|
nullable: true
|
|
rendered_html:
|
|
type: string
|
|
nullable: true
|
|
created_at:
|
|
type: string
|
|
edited_at:
|
|
type: string
|
|
nullable: true
|
|
votes:
|
|
type: integer
|
|
is_removed:
|
|
type: boolean
|
|
is_deleted:
|
|
type: boolean
|
|
exemplary:
|
|
type: boolean
|
|
nullable: true
|
|
collapsed:
|
|
type: boolean
|
|
nullable: true
|
|
collapsed_individual:
|
|
type: boolean
|
|
nullable: true
|
|
is_op:
|
|
type: boolean
|
|
nullable: true
|
|
is_me:
|
|
type: boolean
|
|
nullable: true
|
|
is_new:
|
|
type: boolean
|
|
nullable: true
|
|
voted:
|
|
type: boolean
|
|
nullable: true
|
|
bookmarked:
|
|
type: boolean
|
|
nullable: true
|
|
depth:
|
|
type: integer
|
|
children:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/Comment'
|
|
|
|
User:
|
|
type: object
|
|
required:
|
|
- username
|
|
properties:
|
|
username:
|
|
type: string
|
|
|
|
Pagination:
|
|
type: object
|
|
required:
|
|
- num_items
|
|
- next_link
|
|
- prev_link
|
|
properties:
|
|
num_items:
|
|
type: integer
|
|
description: The number of items returned in this response.
|
|
next_link:
|
|
type: string
|
|
nullable: true
|
|
prev_link:
|
|
type: string
|
|
nullable: true
|
|
|
|
Error:
|
|
type: object
|
|
required:
|
|
- message
|
|
properties:
|
|
field:
|
|
type: string
|
|
message:
|
|
type: string
|
|
exception:
|
|
type: string
|