384 lines
11 KiB
YAML
384 lines
11 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: Attemps 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:
|
|
post:
|
|
tags:
|
|
- Auth Endpoints
|
|
summary: Logs out a user, making their access token invalid.
|
|
requestBody:
|
|
$ref: '#/components/requestBodies/TokenRequest'
|
|
responses:
|
|
200:
|
|
description: You have successfully logged out, and your token is now 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'
|
|
401:
|
|
$ref: '#/components/responses/InvalidToken'
|
|
500:
|
|
$ref: '#/components/responses/ServerError'
|
|
|
|
/users/{username}:
|
|
get:
|
|
tags:
|
|
- User Endpoints
|
|
summary: Get the 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:
|
|
post:
|
|
tags:
|
|
- User Endpoints
|
|
- Posts Endpoints
|
|
parameters:
|
|
- name: username
|
|
required: true
|
|
in: path
|
|
schema:
|
|
type: string
|
|
summary: Get the list of posts a user has created/submitted.
|
|
requestBody:
|
|
$ref: '#/components/requestBodies/Listing'
|
|
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:
|
|
post:
|
|
tags:
|
|
- User Endpoints
|
|
- Comments Endpoints
|
|
parameters:
|
|
- name: username
|
|
required: true
|
|
in: path
|
|
schema:
|
|
type: string
|
|
summary: Get the list of comments a user has submitted.
|
|
requestBody:
|
|
$ref: '#/components/requestBodies/Listing'
|
|
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'
|
|
|
|
components:
|
|
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
|
|
TokenRequest:
|
|
description: The access token to identify a user.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
required:
|
|
- token
|
|
properties:
|
|
token:
|
|
description: The access token.
|
|
type: string
|
|
Listing:
|
|
description: Query particular data sorted by date and time.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Listing'
|
|
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
|
|
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 description.
|
|
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 uusername 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
|
|
Token:
|
|
required:
|
|
- token
|
|
type: object
|
|
properties:
|
|
token:
|
|
description: The access token value.
|
|
type: string
|
|
Post:
|
|
type: object
|
|
required:
|
|
- id
|
|
- user_id
|
|
- title
|
|
- upvotes
|
|
- downvotes
|
|
- 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
|
|
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
|
|
Listing:
|
|
type: object
|
|
properties:
|
|
after:
|
|
description: Filter items to only return those after this date and time.
|
|
type: string
|
|
format: 'date-time'
|
|
default: 2020-01-01T00:00:00.000z
|
|
before:
|
|
description: Filter items to only return those before this date and time.
|
|
type: string
|
|
format: 'date-time'
|
|
default: 2030-01-01T00:00:00.000z
|
|
count:
|
|
description: The number of items already seen in this listing. Items will always be sorted by newest first.
|
|
type: integer
|
|
minimum: 0
|
|
default: 0
|
|
limit:
|
|
description: The maximum number of items to provide. Can be used in conjunction with 'count' to paginate.
|
|
type: integer
|
|
maximum: 100
|
|
minimum: 0
|
|
default: 10
|
|
example:
|
|
after: 2020-01-01T00:00:00.000z
|
|
before: 2030-01-01T00:00:00.000z
|
|
count: 0
|
|
limit: 10 |