673 lines
20 KiB
YAML
673 lines
20 KiB
YAML
openapi: 3.0.3
|
|
info:
|
|
title: Project Ham API Specification
|
|
version: 0.0.1
|
|
contact:
|
|
name: Project Maintainer
|
|
email: me@hamzantal.pw
|
|
license:
|
|
name: MIT
|
|
paths:
|
|
/auth/login:
|
|
post:
|
|
tags:
|
|
- Auth Endpoints
|
|
summary: Attempts to log in a user with credentials, and returns an access token.
|
|
requestBody:
|
|
$ref: '#/components/requestBodies/AuthCredentials'
|
|
responses:
|
|
200:
|
|
description: You have been successfully logged in, and you can use the token to interact with the web server.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Token'
|
|
400:
|
|
$ref: '#/components/responses/MalformedBody'
|
|
401:
|
|
$ref: '#/components/responses/InvalidCredentials'
|
|
500:
|
|
$ref: '#/components/responses/ServerError'
|
|
/auth/logout:
|
|
get:
|
|
tags:
|
|
- Auth Endpoints
|
|
summary: Logs out a user, making their access token invalid.
|
|
security:
|
|
- token: [ ]
|
|
responses:
|
|
200:
|
|
description: You have successfully logged out, and the token used to authenticate the request is now revoked/invalid.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
400:
|
|
$ref: '#/components/responses/MalformedBody'
|
|
401:
|
|
$ref: '#/components/responses/InvalidToken'
|
|
500:
|
|
$ref: '#/components/responses/ServerError'
|
|
/auth/register:
|
|
post:
|
|
tags:
|
|
- Auth Endpoints
|
|
summary: Creates a new user account that can be used to participate with the website.
|
|
requestBody:
|
|
description: The information for the new user.
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/RegisteredUser'
|
|
responses:
|
|
200:
|
|
description: Your account has successfully been created, and you can now log in.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
400:
|
|
$ref: '#/components/responses/MalformedBody'
|
|
422:
|
|
$ref: '#/components/responses/Unprocessable'
|
|
500:
|
|
$ref: '#/components/responses/ServerError'
|
|
|
|
/users/{username}:
|
|
get:
|
|
tags:
|
|
- User Endpoints
|
|
summary: Get information for a user.
|
|
parameters:
|
|
- name: username
|
|
required: true
|
|
in: path
|
|
schema:
|
|
type: string
|
|
responses:
|
|
200:
|
|
description: Public information for the requested user.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/User'
|
|
/users/{username}/posts:
|
|
get:
|
|
tags:
|
|
- User Endpoints
|
|
- Post Endpoints
|
|
parameters:
|
|
- name: username
|
|
required: true
|
|
in: path
|
|
schema:
|
|
type: string
|
|
- $ref: '#/components/parameters/AfterParam'
|
|
- $ref: '#/components/parameters/BeforeParam'
|
|
- $ref: '#/components/parameters/LimitParam'
|
|
- $ref: '#/components/parameters/CountParam'
|
|
summary: Get a list of posts a user has created/submitted.
|
|
responses:
|
|
200:
|
|
description: A list of posts filtered and formatted.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/Post'
|
|
400:
|
|
$ref: '#/components/responses/MalformedBody'
|
|
422:
|
|
$ref: '#/components/responses/Unprocessable'
|
|
500:
|
|
$ref: '#/components/responses/ServerError'
|
|
/users/{username}/comments:
|
|
get:
|
|
tags:
|
|
- User Endpoints
|
|
- Comment Endpoints
|
|
parameters:
|
|
- name: username
|
|
required: true
|
|
in: path
|
|
schema:
|
|
type: string
|
|
- $ref: '#/components/parameters/AfterParam'
|
|
- $ref: '#/components/parameters/BeforeParam'
|
|
- $ref: '#/components/parameters/LimitParam'
|
|
- $ref: '#/components/parameters/CountParam'
|
|
summary: Get a list of paginated comments a user has submitted.
|
|
responses:
|
|
200:
|
|
description: A list of comments filtered and formatted.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/Comment'
|
|
400:
|
|
$ref: '#/components/responses/MalformedBody'
|
|
422:
|
|
$ref: '#/components/responses/Unprocessable'
|
|
500:
|
|
$ref: '#/components/responses/ServerError'
|
|
|
|
/posts:
|
|
get:
|
|
tags:
|
|
- Post Endpoints
|
|
summary: Get a list of paginated posts.
|
|
description: The items retrieved will always show newest first.
|
|
parameters:
|
|
- name: filter
|
|
in: query
|
|
description: Filter posts by content in title and description
|
|
schema:
|
|
type: string
|
|
- $ref: '#/components/parameters/AfterParam'
|
|
- $ref: '#/components/parameters/BeforeParam'
|
|
- $ref: '#/components/parameters/LimitParam'
|
|
- $ref: '#/components/parameters/CountParam'
|
|
responses:
|
|
'200':
|
|
description: A list of posts filtered and formatted.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/Post'
|
|
400:
|
|
$ref: '#/components/responses/MalformedBody'
|
|
422:
|
|
$ref: '#/components/responses/Unprocessable'
|
|
500:
|
|
$ref: '#/components/responses/ServerError'
|
|
/posts/new:
|
|
post:
|
|
tags:
|
|
- Post Endpoints
|
|
security:
|
|
- token: [ ]
|
|
summary: Submit a new comment.
|
|
description: This endpoint will take information that new comments require, a post ID, and ssubmits a comment to a post.
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
required:
|
|
- content
|
|
- parent
|
|
properties:
|
|
title:
|
|
description: The title of the post created
|
|
type: string
|
|
description:
|
|
description: The body text of a post, optional.
|
|
example:
|
|
title: I use arch BTW.
|
|
description: Ladies, I'm waiting.
|
|
responses:
|
|
200:
|
|
description: The created post ID
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
400:
|
|
$ref: '#/components/responses/MalformedBody'
|
|
401:
|
|
$ref: '#/components/responses/InvalidToken'
|
|
422:
|
|
$ref: '#/components/responses/Unprocessable'
|
|
500:
|
|
$ref: '#/components/responses/ServerError'
|
|
/post/{id}:
|
|
get:
|
|
tags:
|
|
- Post Endpoints
|
|
summary: Get information for a post.
|
|
description: Returns the post information and all comments for a particular post.
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
required: true
|
|
description: The post ID to retrieve information about
|
|
schema:
|
|
type: string
|
|
responses:
|
|
200:
|
|
description: Information regarding a post
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
allOf:
|
|
- $ref: '#/components/schemas/Post'
|
|
- type: object
|
|
required:
|
|
- comments
|
|
properties:
|
|
comments:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/Comment'
|
|
404:
|
|
$ref: '#/components/responses/NotFound'
|
|
500:
|
|
$ref: '#/components/responses/ServerError'
|
|
/post/{id}/upvote:
|
|
post:
|
|
tags:
|
|
- Post Endpoints
|
|
summary: Upvote a post.
|
|
description: Add an upvote to a specified post. If you have already upvoted a point, it is retracted.
|
|
security:
|
|
- token: []
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
required: true
|
|
description: The post ID to upvote.
|
|
schema:
|
|
type: string
|
|
responses:
|
|
200:
|
|
description: Your upvote has successfully been registered.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
401:
|
|
$ref: '#/components/responses/InvalidToken'
|
|
404:
|
|
$ref: '#/components/responses/NotFound'
|
|
500:
|
|
$ref: '#/components/responses/ServerError'
|
|
/post/{id}/downvote:
|
|
post:
|
|
tags:
|
|
- Post Endpoints
|
|
summary: Downvote a post
|
|
description: Add an downvote to a specified post. If you have already downvoted a point, it is retracted.
|
|
security:
|
|
- token: []
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
required: true
|
|
description: The post ID to downvote.
|
|
schema:
|
|
type: string
|
|
responses:
|
|
200:
|
|
description: Your downvote has successfully been registered.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
401:
|
|
$ref: '#/components/responses/InvalidToken'
|
|
404:
|
|
$ref: '#/components/responses/NotFound'
|
|
500:
|
|
$ref: '#/components/responses/ServerError'
|
|
|
|
/comment/new:
|
|
post:
|
|
tags:
|
|
- Comment Endpoints
|
|
security:
|
|
- token: [ ]
|
|
summary: Submit a comment.
|
|
description: This endpoint will take information that new posts require and then create a new entry that will be submitted to the website.
|
|
requestBody:
|
|
description: Submit a new post with this endpoint.
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
required:
|
|
- content
|
|
- post_id
|
|
properties:
|
|
content:
|
|
description: The message of the comment
|
|
type: string
|
|
post_id:
|
|
description: The id of the post the comment belongs to.
|
|
parent_id:
|
|
description: The parent comment. If not provided, interpreted as a top-level comment.
|
|
example:
|
|
content: No one cares about arch!
|
|
post_id: a1b2c3d4
|
|
responses:
|
|
200:
|
|
description: The created comment ID
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
400:
|
|
$ref: '#/components/responses/MalformedBody'
|
|
401:
|
|
$ref: '#/components/responses/InvalidToken'
|
|
422:
|
|
$ref: '#/components/responses/Unprocessable'
|
|
500:
|
|
$ref: '#/components/responses/ServerError'
|
|
/comment/{id}/upvote:
|
|
post:
|
|
tags:
|
|
- Comment Endpoints
|
|
summary: Upvote a comment.
|
|
description: Add an upvote to a specified comment. If you have already upvoted a point, it is retracted.
|
|
security:
|
|
- token: []
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
required: true
|
|
description: The comment ID to upvote.
|
|
schema:
|
|
type: string
|
|
responses:
|
|
200:
|
|
description: Your upvote has successfully been registered.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
401:
|
|
$ref: '#/components/responses/InvalidToken'
|
|
404:
|
|
$ref: '#/components/responses/NotFound'
|
|
500:
|
|
$ref: '#/components/responses/ServerError'
|
|
/comment/{id}/downvote:
|
|
post:
|
|
tags:
|
|
- Comment Endpoints
|
|
summary: Downvote a comment
|
|
description: Add an downvote to a specified comment. If you have already downvoted a point, it is retracted.
|
|
security:
|
|
- token: []
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
required: true
|
|
description: The comment ID to downvote.
|
|
schema:
|
|
type: string
|
|
responses:
|
|
200:
|
|
description: Your downvote has successfully been registered.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
401:
|
|
$ref: '#/components/responses/InvalidToken'
|
|
404:
|
|
$ref: '#/components/responses/NotFound'
|
|
500:
|
|
$ref: '#/components/responses/ServerError'
|
|
components:
|
|
parameters:
|
|
AfterParam:
|
|
name: after
|
|
in: query
|
|
description: Date after which to return items.
|
|
schema:
|
|
type: string
|
|
format: 'date-time'
|
|
example: 2020-01-01T00:00:00.000z
|
|
BeforeParam:
|
|
name: before
|
|
in: query
|
|
description: Date before which to return items.
|
|
schema:
|
|
type: string
|
|
format: 'date-time'
|
|
example: 2030-01-01T00:00:00.000z
|
|
LimitParam:
|
|
name: limit
|
|
in: query
|
|
description: Maximum number of items to return
|
|
schema:
|
|
type: integer
|
|
maximum: 100
|
|
minimum: 0
|
|
CountParam:
|
|
name: count
|
|
in: query
|
|
description: The number of items already seen in this listing. Items will always be sorted by newest first.
|
|
schema:
|
|
type: integer
|
|
default: 0
|
|
minimum: 0
|
|
|
|
requestBodies:
|
|
AuthCredentials:
|
|
description: User credentials.
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
required:
|
|
- username
|
|
- password
|
|
type: object
|
|
properties:
|
|
username:
|
|
description: The username of the user.
|
|
type: string
|
|
password:
|
|
description: The password of the user.
|
|
type: string
|
|
responses:
|
|
MalformedBody:
|
|
description: The information in your body is incomplete, or your JSON format is invalid.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
example:
|
|
reason: Invalid request body provided.
|
|
code: 400
|
|
InvalidCredentials:
|
|
description: The credentials you have provided are incorrect.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
example:
|
|
reason: The username or password provided are incorrect.
|
|
code: 401
|
|
InvalidToken:
|
|
description: The access token you provided is invalid or missing.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
example:
|
|
reason: The token provided is invalid.
|
|
code: 401
|
|
NotFound:
|
|
description: The requested resource was not found.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
example:
|
|
reason: The specified resource does not exist.
|
|
code: 404
|
|
Unprocessable:
|
|
description: The request was valid, however some of the parameters have an invalid value.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
example:
|
|
reason: Varies
|
|
code: 422
|
|
ServerError:
|
|
description: The server could not complete a request due to an unknown error. More information may be available in the 'reason' parameter.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
example:
|
|
reason: The internal server reached an unknown state.
|
|
code: 500
|
|
schemas:
|
|
RegisteredUser:
|
|
type: object
|
|
required:
|
|
- username
|
|
- email
|
|
- password
|
|
properties:
|
|
username:
|
|
description: A unique username to identify a user around the website.
|
|
type: string
|
|
minLength: 3
|
|
maxLength: 16
|
|
pattern: "[a-zA-Z0-9 ]{3,16}"
|
|
email:
|
|
description: A unique email used for communication/further identification.
|
|
type: string
|
|
format: email
|
|
password:
|
|
type: string
|
|
format: password
|
|
minLength: 8
|
|
maxLength: 32
|
|
User:
|
|
type: object
|
|
required:
|
|
- id
|
|
- username
|
|
- points
|
|
- date_created
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: The unique ID of the user
|
|
username:
|
|
type: string
|
|
description: The username of the user
|
|
points:
|
|
type: number
|
|
description: The number of points (sum of upvotes and downvotes) of a user
|
|
date_created:
|
|
type: string
|
|
format: 'date-time'
|
|
description: "When the user's account was created"
|
|
Token:
|
|
required:
|
|
- token
|
|
type: object
|
|
properties:
|
|
token:
|
|
description: The access token value.
|
|
type: string
|
|
Post:
|
|
type: object
|
|
required:
|
|
- id
|
|
- user_id
|
|
- title
|
|
- upvotes
|
|
- downvotes
|
|
- comments
|
|
- date_created
|
|
properties:
|
|
id:
|
|
description: The unique ID of a post.
|
|
type: string
|
|
user_id:
|
|
description: The ID of the user who created the post.
|
|
type: string
|
|
title:
|
|
description: The main title of a post.
|
|
type: string
|
|
description:
|
|
description: The body text of a post, optional.
|
|
type: string
|
|
upvotes:
|
|
description: The number of upvotes a post has.
|
|
type: integer
|
|
downvotes:
|
|
description: The number of downvotes a post has.
|
|
type: integer
|
|
comments:
|
|
description: The number of comments available on a post.
|
|
type: integer
|
|
date_created:
|
|
description: The time at which this post was submitted.
|
|
type: string
|
|
format: 'date-time'
|
|
Comment:
|
|
type: object
|
|
required:
|
|
- id
|
|
- user_id
|
|
- post_id
|
|
- content
|
|
- upvotes
|
|
- downvotes
|
|
- date_created
|
|
properties:
|
|
id:
|
|
description: The unique ID of a comment.
|
|
type: string
|
|
user_id:
|
|
description: The ID of the user who posted the comment.
|
|
type: string
|
|
post_id:
|
|
description: The ID of the post this comment is created under.
|
|
type: string
|
|
parent_id:
|
|
description: The ID of the parent comment this comment is created to, if not provided, a top-level comment.
|
|
type: string
|
|
content:
|
|
description: The content/message of a comment.
|
|
type: string
|
|
upvotes:
|
|
description: The number of upvotes a comment has.
|
|
type: integer
|
|
downvotes:
|
|
description: The number of downvotes a comment has.
|
|
type: integer
|
|
date_created:
|
|
description: The time at which this comment was submitted.
|
|
type: string
|
|
format: 'date-time'
|
|
Error:
|
|
required:
|
|
- reason
|
|
- code
|
|
type: object
|
|
properties:
|
|
reason:
|
|
description: The cause of the error message.
|
|
type: string
|
|
code:
|
|
description: The HTTP error code value accompanying the error.
|
|
type: integer
|
|
securitySchemes:
|
|
token:
|
|
type: http
|
|
scheme: bearer
|