mirror of
https://github.com/wassname/talk.git
synced 2026-07-02 04:43:02 +08:00
Riley Davis
532 lines
13 KiB
YAML
532 lines
13 KiB
YAML
swagger: '2.0'
|
|
info:
|
|
title: Talk API
|
|
description: A commenting platform from The Coral Project. https://coralproject.net
|
|
version: "0.0.1"
|
|
host: talk-stg.coralproject.net
|
|
schemes:
|
|
- https
|
|
basePath: /api/v1
|
|
consumes:
|
|
- application/json
|
|
produces:
|
|
- application/json
|
|
|
|
paths:
|
|
/comments:
|
|
get:
|
|
tags:
|
|
- Comments
|
|
parameters:
|
|
- name: status
|
|
in: query
|
|
description: Performs a search based on the comment's status.
|
|
type: string
|
|
enum:
|
|
- flag
|
|
- name: action_type
|
|
in: query
|
|
description: Performs a search based on the actions that have been added to it.
|
|
type: string
|
|
enum:
|
|
- rejected
|
|
- accepted
|
|
- new
|
|
responses:
|
|
200:
|
|
description: Comments matching the query.
|
|
schema:
|
|
type: array
|
|
items:
|
|
- $ref: '#/definitions/Comment'
|
|
500:
|
|
description: An error occured.
|
|
schema:
|
|
$ref: '#/definitions/Error'
|
|
post:
|
|
tags:
|
|
- Comments
|
|
parameters:
|
|
- name: body
|
|
in: body
|
|
description: The comment to create.
|
|
schema:
|
|
$ref: '#/definitions/Comment'
|
|
responses:
|
|
201:
|
|
description: The comment that was created.
|
|
schema:
|
|
$ref: '#/definitions/Comment'
|
|
500:
|
|
description: An error occured.
|
|
schema:
|
|
$ref: '#/definitions/Error'
|
|
/comments/{comment_id}:
|
|
get:
|
|
tags:
|
|
- Comments
|
|
parameters:
|
|
- name: comment_id
|
|
in: path
|
|
description: The id of the comment to retrieve.
|
|
type: string
|
|
required: true
|
|
responses:
|
|
200:
|
|
description: The comment was found.
|
|
schema:
|
|
$ref: '#/definitions/Comment'
|
|
404:
|
|
description: The comment was not found.
|
|
500:
|
|
description: An error occured.
|
|
schema:
|
|
$ref: '#/definitions/Error'
|
|
delete:
|
|
tags:
|
|
- Comments
|
|
parameters:
|
|
- name: comment_id
|
|
in: path
|
|
description: The id of the comment to delete.
|
|
type: string
|
|
required: true
|
|
responses:
|
|
204:
|
|
description: The comment was deleted.
|
|
500:
|
|
description: An error occured.
|
|
schema:
|
|
$ref: '#/definitions/Error'
|
|
/comments/{comment_id}/status:
|
|
put:
|
|
tags:
|
|
- Comments
|
|
- Moderation
|
|
parameters:
|
|
- name: comment_id
|
|
in: path
|
|
description: The id of the comment to retrieve.
|
|
type: string
|
|
required: true
|
|
- name: body
|
|
in: body
|
|
description: The status to update to.
|
|
required: true
|
|
schema:
|
|
type: object
|
|
properties:
|
|
status:
|
|
type: string
|
|
description: The status to update to.
|
|
responses:
|
|
204:
|
|
description: The comment status was updated.
|
|
500:
|
|
description: An error occured.
|
|
schema:
|
|
$ref: '#/definitions/Error'
|
|
/comments/{comment_id}/actions:
|
|
post:
|
|
tags:
|
|
- Comments
|
|
- Actions
|
|
parameters:
|
|
- name: comment_id
|
|
in: path
|
|
description: The id of the comment to retrieve.
|
|
type: string
|
|
required: true
|
|
- name: body
|
|
in: body
|
|
description: The action to add.
|
|
required: true
|
|
schema:
|
|
type: object
|
|
properties:
|
|
action_type:
|
|
type: string
|
|
description: The action to add
|
|
responses:
|
|
201:
|
|
description: The action created.
|
|
schema:
|
|
$ref: '#/definitions/Action'
|
|
500:
|
|
description: An error occured.
|
|
schema:
|
|
$ref: '#/definitions/Error'
|
|
/actions/{action_id}:
|
|
delete:
|
|
tags:
|
|
- Actions
|
|
parameters:
|
|
- name: action_id
|
|
in: path
|
|
description: The id of the action to delete.
|
|
type: string
|
|
required: true
|
|
responses:
|
|
204:
|
|
description: The action was deleted.
|
|
500:
|
|
description: An error occured.
|
|
schema:
|
|
$ref: '#/definitions/Error'
|
|
/auth:
|
|
get:
|
|
tags:
|
|
- Auth
|
|
description: Retrieves the current authentication credentials.
|
|
responses:
|
|
200:
|
|
description: The current user.
|
|
schema:
|
|
$ref: '#/definitions/User'
|
|
500:
|
|
description: An error occured.
|
|
schema:
|
|
$ref: '#/definitions/Error'
|
|
delete:
|
|
tags:
|
|
- Auth
|
|
description: Logs out the current authenticated user.
|
|
responses:
|
|
204:
|
|
description: The current user has been logged out.
|
|
500:
|
|
description: An error occured.
|
|
schema:
|
|
$ref: '#/definitions/Error'
|
|
/auth/local:
|
|
post:
|
|
tags:
|
|
- Auth
|
|
parameters:
|
|
- name: body
|
|
in: body
|
|
required: true
|
|
description: The login credentials.
|
|
schema:
|
|
type: object
|
|
properties:
|
|
email:
|
|
type: string
|
|
description: The email address of the current user.
|
|
password:
|
|
type: string
|
|
description: The password of the current user.
|
|
responses:
|
|
200:
|
|
description: The user has authenticated sucesfully.
|
|
schema:
|
|
$ref: '#/definitions/User'
|
|
401:
|
|
description: The authentication error.
|
|
schema:
|
|
$ref: '#/definitions/Error'
|
|
500:
|
|
description: An error occured.
|
|
schema:
|
|
$ref: '#/definitions/Error'
|
|
/auth/facebook:
|
|
get:
|
|
tags:
|
|
- Auth
|
|
responses:
|
|
302:
|
|
description: Redirects the user to perform external facebook authentication.
|
|
500:
|
|
description: An error occured.
|
|
schema:
|
|
$ref: '#/definitions/Error'
|
|
/queue/comments/pending:
|
|
get:
|
|
tags:
|
|
- Comments
|
|
- Moderation
|
|
responses:
|
|
200:
|
|
description: The comments that are not moderated.
|
|
schema:
|
|
type: array
|
|
items:
|
|
- $ref: '#/definitions/Comment'
|
|
500:
|
|
description: An error occured.
|
|
schema:
|
|
$ref: '#/definitions/Error'
|
|
/assets:
|
|
get:
|
|
parameters:
|
|
- name: limit
|
|
in: query
|
|
type: number
|
|
format: int32
|
|
description: Limit the listing results
|
|
- name: skip
|
|
in: query
|
|
type: number
|
|
format: int32
|
|
description: Skip the listing results
|
|
- name: sort
|
|
in: query
|
|
enum:
|
|
- asc
|
|
- desc
|
|
type: string
|
|
description: Sorting method
|
|
- name: field
|
|
in: query
|
|
type: string
|
|
description: Field to sort by.
|
|
responses:
|
|
200:
|
|
description: Assets listed.
|
|
schema:
|
|
type: object
|
|
properties:
|
|
count:
|
|
type: number
|
|
description: Total number of assets found.
|
|
result:
|
|
type: array
|
|
items:
|
|
$ref: '#/definitions/Asset'
|
|
|
|
/assets/{asset_id}:
|
|
get:
|
|
parameters:
|
|
- name: asset_id
|
|
in: path
|
|
required: true
|
|
type: string
|
|
format: uuid
|
|
responses:
|
|
200:
|
|
description: The requested asset.
|
|
schema:
|
|
$ref: '#/definitions/Asset'
|
|
404:
|
|
description: The asset was not found.
|
|
500:
|
|
description: An error occured.
|
|
schema:
|
|
$ref: '#/definitions/Error'
|
|
|
|
|
|
/assets/{asset_id}/scrape:
|
|
post:
|
|
parameters:
|
|
- name: asset_id
|
|
in: path
|
|
required: true
|
|
type: string
|
|
format: uuid
|
|
responses:
|
|
201:
|
|
description: The job that was created.
|
|
schema:
|
|
$ref: '#/definitions/Job'
|
|
404:
|
|
description: The asset was not found.
|
|
500:
|
|
description: An error occured.
|
|
schema:
|
|
$ref: '#/definitions/Error'
|
|
|
|
/assets/{asset_id}/settings:
|
|
put:
|
|
parameters:
|
|
- name: asset_id
|
|
in: path
|
|
required: true
|
|
type: string
|
|
format: uuid
|
|
- name: body
|
|
in: body
|
|
required: true
|
|
schema:
|
|
$ref: '#/definitions/Settings'
|
|
responses:
|
|
204:
|
|
description: The asset settings were updated.
|
|
404:
|
|
description: The asset was not found.
|
|
500:
|
|
description: An error occured.
|
|
schema:
|
|
$ref: '#/definitions/Error'
|
|
|
|
/stream:
|
|
get:
|
|
tags:
|
|
- Actions
|
|
- Assets
|
|
- Comments
|
|
- Users
|
|
parameters:
|
|
- name: asset_url
|
|
in: query
|
|
description: The asset url to get the comment stream from.
|
|
type: string
|
|
format: url
|
|
responses:
|
|
200:
|
|
description: The comment stream.
|
|
schema:
|
|
type: object
|
|
properties:
|
|
assets:
|
|
type: array
|
|
items:
|
|
- $ref: '#/definitions/Asset'
|
|
comments:
|
|
type: array
|
|
items:
|
|
- $ref: '#/definitions/Comment'
|
|
users:
|
|
type: array
|
|
items:
|
|
- $ref: '#/definitions/User'
|
|
actions:
|
|
type: array
|
|
items:
|
|
- $ref: '#/definitions/Actions'
|
|
500:
|
|
description: An error occured.
|
|
schema:
|
|
$ref: '#/definitions/Error'
|
|
/settings:
|
|
get:
|
|
responses:
|
|
200:
|
|
description: The settings.
|
|
schema:
|
|
$ref: '#/definitions/Settings'
|
|
500:
|
|
description: An error occured.
|
|
schema:
|
|
$ref: '#/definitions/Error'
|
|
put:
|
|
responses:
|
|
204:
|
|
description: The settings were updated.
|
|
500:
|
|
description: An error occured.
|
|
schema:
|
|
$ref: '#/definitions/Error'
|
|
definitions:
|
|
Error:
|
|
type: object
|
|
properties:
|
|
message:
|
|
type: string
|
|
description: The error that occured.
|
|
Item:
|
|
type: object
|
|
ModerationAction:
|
|
type: string
|
|
Comment:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: Unique identifier
|
|
body:
|
|
type: string
|
|
description: Description of comment
|
|
created_at:
|
|
type: string
|
|
format: date-time
|
|
description: Display name of comment
|
|
updated_at:
|
|
type: string
|
|
format: date-time
|
|
description: Display name of comment
|
|
author_id:
|
|
type: string
|
|
description: User who posted the comment
|
|
parent_id:
|
|
type: string
|
|
description: Display name of comment
|
|
asset_id:
|
|
type: string
|
|
description: Display name of comment
|
|
Actions:
|
|
type: object
|
|
properties:
|
|
item_id:
|
|
type: string
|
|
item_type:
|
|
type: string # comment, user...
|
|
type:
|
|
type: string # flagged, likes, upvotes...
|
|
count:
|
|
type: integer
|
|
current_user:
|
|
type: boolean
|
|
Action:
|
|
type: object
|
|
properties:
|
|
type:
|
|
type: string
|
|
user_id:
|
|
type: string
|
|
moderation:
|
|
type: string
|
|
enum:
|
|
- pre
|
|
- post
|
|
created_at:
|
|
type: string
|
|
format: date-time
|
|
description: Creation Date-Time
|
|
updated_at:
|
|
type: string
|
|
format: date-time
|
|
description: Updated Date-Time
|
|
Asset:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: The uuid.v4 id of the asset.
|
|
url:
|
|
type: string
|
|
description: The url where the asset is found.
|
|
type:
|
|
type: string
|
|
description: What kind of asset it is.
|
|
default: article
|
|
headline:
|
|
type: string
|
|
description: The headline of the asset, inferred on initial load.
|
|
summary:
|
|
type: string
|
|
description: A summary of the asset, inferred on initial load.
|
|
section:
|
|
type: string
|
|
description: The section the asset is in.
|
|
subsection:
|
|
type: string
|
|
description: The subsection that the asset is in.
|
|
authors:
|
|
type: string
|
|
description: An array of the authors for this asset.
|
|
publication_date:
|
|
type: string
|
|
format: datetime
|
|
description: When this asset was published.
|
|
User:
|
|
type: object
|
|
Settings:
|
|
type: object
|
|
Job:
|
|
type: object
|
|
properties:
|
|
id:
|
|
format: number
|
|
state:
|
|
format: string
|