Documentation Powered by ReDoc

Chat App API (1.3)

Download OpenAPI specification:Download

E-mail: alex@alexkrantz.com License: GNU AGPL v3.0

Introduction

Manage the entirety of the chat application without a user interface

Authentication

ApiKey

JWT authentication token from login route

Security scheme type: API Key
Header parameter name: Authorization

ResetPasswordToken

The password reset JWT from the reset email. Generated after the user initializes the password reset flow.

Security scheme type: API Key
Header parameter name: Authorization

EmailVerificationToken

The email verification JWT from the verification email. Generated after the users registers.

Security scheme type: API Key
Query parameter name: token

authentication

User login and logout routes

logins in a user

Generates an authentication token given a valid username and password.

Request Body schema: application/json
username
string

Username to login as

password
string 64 characters

SHA256 hex digest of password associated with username

Responses

200

authentication token along with success status

400

bad input parameter

401

bad username or password

post /api/auth/login
/api/auth/login

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "username": "alex",
  • "password": "sha256-hex-digest"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "success",
  • "data":
    {
    }
}

logs out a user

Revokes an authentication token for a user

Authorizations:
ApiKey

Responses

200

successfully revoked token

401

bad username or password

get /api/auth/logout
/api/auth/logout

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "success"
}

request password reset

Initiates the process for resetting a user's password which includes sending an email with a token to authenticate the resetting of a password.

query Parameters
username
required
string
Example: username=alex

Username to reset password for

Responses

200

successfully initiated flow

400

bad input parameter

get /api/auth/forgot-password
/api/auth/forgot-password

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "success"
}

reset a user's password

Complete the reset password flow. Overwrites the current password of the user, but does not revoke any valid authentication tokens.

Authorizations:
ResetPasswordToken
Request Body schema: application/json
password
string 64 characters

SHA256 hex digest of new password

Responses

200

successfully reset password

400

bad input parameter

401

bad authentication token

post /api/auth/reset-password
/api/auth/reset-password

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "password": "sha256-hex-digest"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "success"
}

verify a user's email

Mark a user as verified after verifying the token send from the email.

Authorizations:
EmailVerificationToken

Responses

200

successfully reset password

400

bad input parameter

401

bad authentication token

get /api/auth/verify-email
/api/auth/verify-email

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "success"
}

users

User modification routes

search for users

Fuzzy search for users by username to get name

Authorizations:
ApiKey
query Parameters
username
required
string
Example: username=al

Username to search on

Responses

200

list of users found

400

bad input parameter

401

bad authentication token

get /api/users
/api/users

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "success",
  • "data":
    [
    ]
}

register a user

Create a user with given name, email, username and password

Request Body schema: application/json
username
string

Username to login as

password
string 64 characters

SHA256 hex digest of password associated with username

email
string [ 5 .. 254 ] characters

Email to be associated with user

name
string

Name associated with user

Responses

200

successfully created user

400

bad input parameter

409

conflicting value with existing user

post /api/users
/api/users

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "username": "alex",
  • "password": "sha256-hex-digest",
  • "email": "a@el.x",
  • "name": "Alex"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "success"
}

describe a user

Get a user's information by their username

Authorizations:
ApiKey
path Parameters
user
required
string
Example: alex

Username to describe

Responses

200

user information

400

bad input parameter

401

bad authentication token

get /api/users/{user}
/api/users/{user}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "success",
  • "data":
    {
    }
}

update a user

Update a user's name, password, or email by their username

Authorizations:
ApiKey
path Parameters
user
required
string
Example: alex

Username to update

Request Body schema: application/json
name
string

new name for user

email
string [ 5 .. 254 ] characters

new email for user

password
string 64 characters

new SHA256 hex digest of password

Responses

200

successfully updated user's information

400

bad input parameter

401

bad authentication token

403

authenticated but not allowed to modify

put /api/users/{user}
/api/users/{user}

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "name": "Krantz",
  • "email": "al@e.x",
  • "password": "sha256-hex-digest"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "success"
}

delete a user

Delete a user and all their information by username

Authorizations:
ApiKey
path Parameters
user
required
string
Example: alex

Username to delete

Responses

200

successfully deleted user

400

bad input parameter

401

bad authentication token

403

authenticated but not allowed to modify

delete /api/users/{user}
/api/users/{user}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "success"
}

chats

Chat management routes

list user's chats

Get a list of all the chats a user is in. Data returned includes users in the chat, the most recent message, and the name of the chat.

Authorizations:
ApiKey

Responses

200

list of chats associated with user

400

bad input parameter

401

bad authentication token

get /api/chats
/api/chats

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "success",
  • "data":
    [
    ]
}

create a chat

Create a new chat with the specified users and initial message. A name must also be passed to the chat.

Authorizations:
ApiKey
Request Body schema: application/json
name
string

Display name of the chat

users
Array of strings

Users to be added to the chat

message
string

Initial message to be sent

Responses

200

successfully created user

400

bad input parameter

401

bad authentication token

post /api/chats
/api/chats

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "name": "Super Awesome Chat",
  • "users":
    [
    ],
  • "message": "Some message sent to the chat"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "success"
}

describe a chat

Get the users in the chat, the most recent message, and the name of the chat by the uuid.

Authorizations:
ApiKey
path Parameters
chat
required
string <uuid>
Example: 3e17b51b-01db-4b20-b1f5-95fd054376b7

uuid of chat

Responses

200

information about the request chat

400

bad input parameter

401

bad authentication token

403

authentication but not allowed to read

get /api/chats/{chat}
/api/chats/{chat}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "success",
  • "data":
    [
    ]
}

update a user

Update a chat's name or the users in it. Not all body parameters are required and can be mixed and matched. Keep in mind that 'mode' and 'user' must be sent together otherwise a 400 response will be generated

Authorizations:
ApiKey
path Parameters
chat
required
string <uuid>
Example: 3e17b51b-01db-4b20-b1f5-95fd054376b7

uuid of chat

Request Body schema: application/json
name
string

new name for the chat

mode
string
Enum: "add" "delete"

operation for the modification of users

user
string

user to modify

Responses

200

successfully updated user's information

400

bad input parameter

401

bad authentication token

403

authenticated but not allowed to modify

put /api/chats/{chat}
/api/chats/{chat}

Request samples

Content type
application/json
Example
change chat name
Copy
 Expand all Collapse all
{
  • "name": "New Name"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "success"
}

delete a chat

Delete a user and all their information by username

Authorizations:
ApiKey
path Parameters
chat
required
string <uuid>
Example: 3e17b51b-01db-4b20-b1f5-95fd054376b7

uuid of chat

Responses

200

successfully deleted chat

400

bad input parameter

401

bad authentication token

403

authenticated but not allowed to modify

delete /api/chats/{chat}
/api/chats/{chat}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "success"
}

messages

Message management routes within chats

list messages in chat

Get a list of messages sent in a chat. By default, it splits the response into pages of 100 messages each. Though the page and number of items per page can be modified through query parameters.

Authorizations:
ApiKey
path Parameters
chat
required
string <uuid>
Example: 3e17b51b-01db-4b20-b1f5-95fd054376b7

uuid of chat

query Parameters
page
number
Example: page=1

page to view; default: 0

per_page
number
Example: per_page=100

number of messages to show per page; default: 100

Responses

200

list of messages in a chat

400

bad input parameter

401

bad authentication token

403

authenticated but not allowed to modify

get /api/chats/{chat}/messages
/api/chats/{chat}/messages

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "success",
  • "data":
    {
    }
}

send a message

Send a message to the specified chat.

Authorizations:
ApiKey
path Parameters
chat
required
string <uuid>
Example: 3e17b51b-01db-4b20-b1f5-95fd054376b7

uuid of chat

Request Body schema: application/json
type
string

type of message

message
message
string

message to send

Responses

200

successfully sent message

400

bad input parameter

401

bad authentication token

403

authenticated but not allowed to modify

post /api/chats/{chat}/messages
/api/chats/{chat}/messages

Request samples

Content type
application/json
Example
message
Copy
 Expand all Collapse all
{
  • "type": "message",
  • "message": "Hello"
}

Response samples

Content type
application/json
Example
standard message
Copy
 Expand all Collapse all
{
  • "status": "success"
}

describe a message

Get all data about a specific message in a chat. Retrieved by index of message

Authorizations:
ApiKey
path Parameters
chat
required
string <uuid>
Example: 3e17b51b-01db-4b20-b1f5-95fd054376b7

uuid of chat

message
required
number
Example: 1

index of message

Responses

200

successfully retrieved message data

400

bad input parameter

401

bad authentication token

403

authentication but not allowed to read

get /api/chats/{chat}/messages/{message}
/api/chats/{chat}/messages/{message}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "sender":
    {
    },
  • "file":
    {
    },
  • "message": "Some sent message",
  • "timestamp": 1566456966279980300
}

update a sent message

Modify the content of an already sent message

Authorizations:
ApiKey
path Parameters
chat
required
string <uuid>
Example: 3e17b51b-01db-4b20-b1f5-95fd054376b7

uuid of chat

message
required
number
Example: 1

index of message

Request Body schema: application/json
message
string

new message content

Responses

200

successfully updated message's information

400

bad input parameter

401

bad authentication token

403

authenticated but not allowed to modify

put /api/chats/{chat}/messages/{message}
/api/chats/{chat}/messages/{message}

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "message": "Some new message"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "success"
}

delete a message

Delete a message from a chat

Authorizations:
ApiKey
path Parameters
chat
required
string <uuid>
Example: 3e17b51b-01db-4b20-b1f5-95fd054376b7

uuid of chat

message
required
number
Example: 1

index of message

Responses

200

successfully deleted message

400

bad input parameter

401

bad authentication token

403

authenticated but not allowed to modify

delete /api/chats/{chat}/messages/{message}
/api/chats/{chat}/messages/{message}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "success"
}

files

File and image message types

download a file/image

Download a file or image from a message in a chat

Authorizations:
ApiKey
path Parameters
file
required
string <uuid>
Example: d1ed2962-aef1-4bcf-a6b6-8f9836366b1f

UUID of the file

Responses

200

file or image

400

bad input parameter

401

bad authentication token

403

authenticated but not allowed to read

get /api/files/{file}
/api/files/{file}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "error",
  • "reason": "path parameter 'file' must be present"
}

upload a file

Upload a file to be associated with a message

Authorizations:
ApiKey
Request Body schema: multipart/form-data
file
string <binary>

Responses

200

successfully uploaded file/image

400

bad input parameter

401

bad authentication token

403

authenticated but not allowed to write

post /api/files/{file}
/api/files/{file}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "status": "success"
}