2019-01-26 00:11:23 +08:00
# backend-core
2019-01-27 09:53:34 +08:00
Beep backend handling core relational information that is not updated often.
## Quickstart
```
cockroach start --insecure
echo "create database core;" | cockroach sql --insecure
migrate -database cockroach://root@localhost:26257/core?sslmode=disable -source file://migrations goto 1
go build & & ./core
```
2019-02-18 23:43:00 +08:00
## Environment variables
2019-02-06 11:38:10 +08:00
2019-02-18 23:43:00 +08:00
Supply environment variables by either exporting them or editing ```.env```.
2019-02-06 11:38:10 +08:00
2019-02-18 23:43:00 +08:00
| ENV | Description | Default |
2019-02-06 11:38:10 +08:00
| ---- | ----------- | ------- |
2019-02-18 23:43:00 +08:00
| LISTEN | Host and port number to listen on | :8080 |
| POSTGRES | URL of Postgres | postgresql://root@localhost:26257/core?sslmode=disable |
2019-02-06 11:38:10 +08:00
2019-01-27 09:53:34 +08:00
## API
2019-07-02 23:01:44 +08:00
Unless otherwise noted, bodies and responses are with `Content-Type: application/json` . Endpoints marked with a ```*``` require a populated `X-User-Claim` header from `backend-auth` .
2019-01-27 09:53:34 +08:00
2019-11-05 03:29:12 +08:00
| Contents |
| --------------------------------------------------------- |
| [Create User ](#Create-User ) |
| [Get Users by Phone ](#Get-Users-by-Phone ) |
| [Get User by ID ](#Get-User-by-ID ) |
| [Get User by Username ](#Get-User-by-Username ) |
| [Update User ](#Update-User ) |
| [Create Conversation ](#Create-Conversation ) |
| [Delete Conversation ](#Delete-Conversation ) |
| [Update Conversation ](#Update-Conversation ) |
| [Get Conversations ](#Get-Conversations ) |
| [Get Conversation ](#Get-Conversation ) |
| [Pin Conversation ](#Pin-Conversation ) |
| [Unpin Conversation ](#Unpin-Conversation ) |
2019-01-27 09:53:34 +08:00
| [Create Conversation Member ](#Create-Conversation-Member ) |
2019-11-05 03:29:12 +08:00
| [Get Conversation Members ](#Get-Conversation-Members ) |
| [Create Contact ](#Create-Contact ) |
| [Get Contacts ](#Get-Contacts ) |
| [Subscribe Contact ](#Subscribe-Contact ) |
| [Subscribe Conversation ](#Subscribe-Conversation ) |
| [Subscribe User ](#Subscribe-User ) |
| [Subscribe Member ](#Subscribe-Member ) |
2019-01-27 09:53:34 +08:00
---
### Create User
```
POST /user
```
Create a new user.
#### Body
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
2019-06-19 11:05:34 +08:00
| username | String | Username of the added user. Must be unique. | ✓ |
| bio | String | Bio of the added user | ✓ |
2019-06-21 11:14:07 +08:00
| profile_pic | String | URL of added user's profile picture | ✓ |
2019-01-27 09:53:34 +08:00
| first_name | String | First name of the added user. | ✓ |
| last_name | String | Last name of the added user. | ✓ |
| phone_number | String | Phone number of the added user. Shouldn't be needed but makes life easier. | X |
#### Success Response (200 OK)
Created user object.
```json
{
"id": "< id > ",
2019-06-18 18:53:04 +08:00
"username": "< username > ",
2019-06-19 11:05:34 +08:00
"bio": "< bio > ",
2019-06-21 11:14:07 +08:00
"profile_pic: "< profile_pic > ",
2019-01-27 09:53:34 +08:00
"first_name": "< first_name > ",
"last_name": "< last_name > ",
"phone_number": "< phone_number > "
}
```
#### Errors
| Code | Description |
| ---- | ----------- |
| 400 | Error parsing submitted body, or fields first_name or last_name have a length of 0. |
| 500 | Error occurred inserting entry into database. |
---
### Get Users by Phone
```
GET /user
```
Get user(s) associated with the supplied phone number.
#### Querystring
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| phone_number | String | Phone number to be queried. | ✓ |
#### Success Response (200 OK)
List of users.
```json
[
{
"id": "< id > ",
2019-06-18 18:53:04 +08:00
"username": "< username > ",
2019-06-19 11:05:34 +08:00
"bio": "< bio > ",
2019-06-21 11:14:07 +08:00
"profile_pic": "< profile_pic > ",
2019-01-27 09:53:34 +08:00
"first_name": "< first_name > ",
"last_name": "< last_name > "
},
...
]
```
#### Errors
| Code | Description |
| ---- | ----------- |
| 400 | Supplied phone_number is absent/an invalid phone number. |
| 500 | Error occurred retrieving entries from database. |
---
2019-06-18 18:53:04 +08:00
### Get User by ID
2019-01-27 09:53:34 +08:00
```
2019-02-24 04:01:34 +08:00
GET /user/id/:user
2019-01-27 09:53:34 +08:00
```
Get a specific user by ID.
#### URL Params
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| user | String | User's ID. | ✓ |
#### Success Response (200 OK)
User object.
```json
{
"id": "< id > ",
2019-06-18 18:53:04 +08:00
"username": "< username > ",
2019-06-19 11:05:34 +08:00
"bio": "< bio > ",
2019-06-21 11:14:07 +08:00
"profile_pic": "< profile_pic > ",
2019-01-27 09:53:34 +08:00
"first_name": "< first_name > ",
"last_name": "< last_name > ",
"phone_number": "< phone_number > "
}
```
#### Errors
| Code | Description |
| ---- | ----------- |
| 404 | User with supplied ID could not be found in database |
| 500 | Error occurred retrieving entries from database. |
---
2019-06-18 18:53:04 +08:00
### Get User by Username
```
GET /user/username/:username
```
Get a specific user by username.
#### URL Params
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| username | String | User's username. | ✓ |
#### Success Response (200 OK)
User object.
```json
{
"id": "< id > ",
"username": "< username > ",
2019-06-19 11:05:34 +08:00
"bio": "< bio > ",
2019-06-21 11:14:07 +08:00
"profile_pic": "< profile_pic > ",
2019-06-18 18:53:04 +08:00
"first_name": "< first_name > ",
"last_name": "< last_name > ",
"phone_number": "< phone_number > "
}
```
#### Errors
| Code | Description |
| ---- | ----------- |
| 404 | User with supplied username could not be found in database |
| 500 | Error occurred retrieving entries from database. |
---
2019-06-21 11:14:07 +08:00
### Update User
```
PATCH /user
```
Update an existing user. User ID is taken from header supplied by `backend-auth` . If one does not wish to update a field, leave it the value acquire from Get-User.
#### Body
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| username | String | Updated username. | X |
| bio | String | Updated bio. | X |
| profile_pic | String | Updated URL of profile picture. | X |
| first_name | String | Updated first name. | X |
| last_name | String | Updated last name | X |
#### Success (200 OK)
Empty body.
#### Errors
| Code | Description |
| ---- | ----------- |
| 400 | Error parsing body/User with username already exists. |
| 500 | Error occurred updating database. |
---
2019-02-24 04:01:34 +08:00
### Create Conversation*
2019-01-27 09:53:34 +08:00
```
2019-02-24 04:01:34 +08:00
POST /user/conversation
2019-01-27 09:53:34 +08:00
```
Create a new conversation for a user.
#### Body
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| title | String | Title of the conversation | X |
2019-07-02 23:01:44 +08:00
| dm | Boolean | Whether the conversation is a DM or not | X |
2019-07-02 23:31:37 +08:00
| picture | String | URL of the group's picture | X |
2019-01-27 09:53:34 +08:00
#### Success Response (200 OK)
Conversation object.
```json
{
"id": "< id > ",
2019-07-02 23:31:37 +08:00
"title": "< title > ",
"picture": "< picture > "
2019-01-27 09:53:34 +08:00
}
```
#### Errors
| Code | Description |
| ---- | ----------- |
2019-02-24 04:01:34 +08:00
| 400 | Error occurred parsing the supplied body/Invalid `X-User-Claim` header |
2019-01-27 09:53:34 +08:00
| 404 | User with supplied ID could not be found in database. |
| 500 | Error occurred inserting entries into the database. |
---
2019-02-24 04:01:34 +08:00
### Delete Conversation*
2019-01-27 09:53:34 +08:00
```
2019-02-24 04:01:34 +08:00
DELETE /user/conversation/:conversation
2019-01-27 09:53:34 +08:00
```
Delete the specified conversation.
#### URL Params
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| conversation | String | Conversation's ID. | ✓ |
#### Success Response (200 OK)
Empty body.
#### Errors
| Code | Description |
| ---- | ----------- |
2019-02-24 04:01:34 +08:00
| 400 | Invalid `X-User-Claim` header. |
2019-01-27 09:53:34 +08:00
| 404 | User/Conversation with supplied ID could not be found in database. |
| 500 | Error occurred deleting entries from the database. |
---
2019-02-24 04:01:34 +08:00
### Update Conversation*
2019-01-27 09:53:34 +08:00
```
2019-02-24 04:01:34 +08:00
PATCH /user/conversation/:conversation
2019-01-27 09:53:34 +08:00
```
Update a conversation's details (mainly just title for now).
#### URL Params
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| conversation | String | Conversation's ID. | ✓ |
#### Body
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| title | String | New title of the conversation. | X |
2019-07-02 23:31:37 +08:00
| picture | String | New URL of the group's picture | X |
2019-01-27 09:53:34 +08:00
#### Success Response (200 OK)
Empty Body. (TODO: Updated conversation)
#### Errors
| Code | Description |
| ---- | ----------- |
2019-02-24 04:01:34 +08:00
| 400 | Error occurred parsing the supplied body/Invalid `X-User-Claim` header. |
2019-01-27 09:53:34 +08:00
| 404 | User/Conversation with supplied ID could not be found in database. |
| 500 | Error occurred updating entries in the database. |
---
2019-02-24 04:01:34 +08:00
### Get Conversations*
2019-01-27 09:53:34 +08:00
```
2019-02-24 04:01:34 +08:00
GET /user/conversation
2019-01-27 09:53:34 +08:00
```
Get the conversations of the specified user.
#### Success Response (200 OK)
List of conversations.
```json
[
{
"id": "< id > ",
"title": "< title > "
2019-08-11 11:06:19 +08:00
"picture": "< picture > ",
"pinned: "< pinned:bool > "
2019-01-27 09:53:34 +08:00
},
...
]
```
#### Errors
| Code | Description |
| ---- | ----------- |
2019-02-24 04:01:34 +08:00
| 400 | Invalid `X-User-Claim` header. |
2019-01-27 09:53:34 +08:00
| 500 | Error occurred updating entries in the database. |
---
2019-02-24 04:01:34 +08:00
### Get Conversation*
2019-01-27 09:53:34 +08:00
```
2019-02-24 04:01:34 +08:00
GET /user/conversation/:conversation
2019-01-27 09:53:34 +08:00
```
Get a specific conversation of a specific user.
#### URL Params
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| conversation | String | Conversation's ID. | ✓ |
#### Success Response (200 OK)
Conversation object.
```json
{
"id": "< id > ",
2019-07-02 23:31:37 +08:00
"title": "< title > ",
2019-08-11 11:06:19 +08:00
"picture": "< picture > ",
"pinned: "< pinned:bool > "
2019-01-27 09:53:34 +08:00
}
```
#### Errors
| Code | Description |
| ---- | ----------- |
2019-02-24 04:01:34 +08:00
| 400 | Invalid `X-User-Claim` header. |
| 404 | Conversation with supplied ID could not be found in database. |
2019-01-27 09:53:34 +08:00
| 500 | Error occurred retrieving entries from the database. |
---
2019-08-11 11:06:19 +08:00
### Pin Conversation
```
POST /user/conversation/:conversation/pin
```
Mark the specified conversation as pinned.
#### URL Params
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| conversation | String | Conversation's ID. | ✓ |
#### Success Response (200 OK)
Blank body.
#### Errors
| Code | Description |
| ---- | ----------- |
| 400 | Invalid `X-User-Claim` header. |
| 404 | Conversation with supplied ID could not be found in database. |
| 500 | Error occurred editing entry in the database. |
---
2019-11-05 03:29:12 +08:00
### Unpin Conversation
```
DELETE /user/conversation/:conversation/pin
```
Unmark the specified conversation as pinned.
#### URL Params
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| conversation | String | Conversation's ID. | ✓ |
#### Success Response (200 OK)
Blank body.
#### Errors
| Code | Description |
| ---- | ----------- |
| 400 | Invalid `X-User-Claim` header. |
| 404 | Conversation with supplied ID could not be found in database. |
| 500 | Error occurred editing entry in the database. |
---
2019-02-24 04:01:34 +08:00
### Create Conversation Member*
2019-01-27 09:53:34 +08:00
```
2019-02-24 04:01:34 +08:00
POST /user/conversation/:conversation/member
2019-01-27 09:53:34 +08:00
```
2019-02-24 04:01:34 +08:00
Add a member to the specified conversation.
2019-01-27 09:53:34 +08:00
#### URL Params
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| conversation | String | Conversation's ID. | ✓ |
#### Body
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| id | String | ID of the user to be added. | ✓ |
#### Success Response (200 OK)
2019-07-03 11:03:44 +08:00
The conversation ID of the conversation the user is added to.
2019-01-27 09:53:34 +08:00
#### Errors
| Code | Description |
| ---- | ----------- |
2019-02-24 04:01:34 +08:00
| 400 | Error occurred parsing the supplied body/The length of the ID supplied in the body is less than 1/Invalid `X-User-Claim` header. |
2019-01-27 09:53:34 +08:00
| 404 | User/Conversation with supplied ID could not be found in database. |
| 500 | Error occurred updating entries in the database. |
---
2019-02-24 04:01:34 +08:00
### Get Conversation Members*
2019-01-27 09:53:34 +08:00
```
2019-02-24 04:01:34 +08:00
GET /user/conversation/:conversation/member
2019-01-27 09:53:34 +08:00
```
2019-02-24 04:01:34 +08:00
Get the members of the specified conversation.
2019-01-27 09:53:34 +08:00
#### URL Params
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| conversation | String | Conversation's ID. | ✓ |
#### Success (200 OK)
List of user objects in conversation.
```json
[
{
"id": "< id > ",
2019-06-21 11:14:07 +08:00
"username": "< username > ",
"bio": "< bio > ",
"profile_pic": "< profile_pic > ",
2019-01-27 09:53:34 +08:00
"first_name": "< first_name > ",
2019-02-17 22:55:27 +08:00
"last_name": "< last_name > ",
"phone_number": "< phone_number > "
2019-01-27 09:53:34 +08:00
},
...
]
```
#### Errors
| Code | Description |
| ---- | ----------- |
2019-02-24 04:01:34 +08:00
| 400 | Invalid `X-User-Claim` header. |
2019-01-27 09:53:34 +08:00
| 500 | Error occurred retrieving entries from the database. |
---
2019-02-24 04:01:34 +08:00
### Create Contact*
2019-01-27 09:53:34 +08:00
```
2019-02-24 04:01:34 +08:00
POST /user/contact
2019-01-27 09:53:34 +08:00
```
2019-02-24 04:01:34 +08:00
Add a new contact.
2019-01-27 09:53:34 +08:00
#### Body
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
2019-02-17 20:47:08 +08:00
| phone_number | String | New contact's phone number. A blank user object will be created if no such ID exists in the database. | ✓ |
2019-01-27 09:53:34 +08:00
#### Success Response (200 OK)
Empty body
#### Errors
| Code | Description |
| ---- | ----------- |
2019-02-24 04:01:34 +08:00
| 400 | Error occurred parsing the supplied body/The length of the ID supplied in the body is less than 1 or equal to the user's ID/Invalid `X-User-Claim` header. |
2019-01-27 09:53:34 +08:00
| 500 | Error occurred updating entries in the database. |
---
### Get Contacts
```
2019-02-24 04:01:34 +08:00
GET /user/contact
2019-01-27 09:53:34 +08:00
```
2019-02-24 04:01:34 +08:00
Get the user's contacts.
2019-01-27 09:53:34 +08:00
#### Success (200 OK)
List of user objects in user's contacts.
```json
[
{
"id": "< id > ",
2019-06-19 11:05:34 +08:00
"username": "< username > ",
"bio": "< bio > ",
2019-06-21 11:14:07 +08:00
"profile_pic": "< profile_pic " ,
2019-01-27 09:53:34 +08:00
"first_name": "< first_name > ",
"last_name": "< last_name > "
},
...
]
```
#### Errors
| Code | Description |
| ---- | ----------- |
2019-02-24 04:01:34 +08:00
| 400 | Invalid `X-User-Claim` header. |
2019-01-27 09:53:34 +08:00
| 500 | Error occurred retrieving entries from the database. |
2019-10-06 23:20:06 +08:00
---
### Subscribe Contact
```
GET /user/subscribe/contact
```
Subscribe to an Eventsource stream giving update in changes in state of the contacts database.
#### Success (200 OK)
An Eventsource stream. Each event (stringified json) will be of the following format:
```json
{
"type": "< add | update > ",
"data": {
"usera": "< user id > ",
"userb": "< user id > "
}
}
```
The json in the data field is also stringified.
---
### Subscribe Conversation
```
GET /user/subscribe/conversation
```
Subscribe to an Eventsource stream giving update in changes in state of the conversations database.
#### Success (200 OK)
An Eventsource stream. Each event (stringified json) will be of the following format:
```json
{
"type": "< add | update | delete > ",
"data": {
"id": "< conversation id > ",
"title": "< string > ",
"dm": "< bool > ",
"picture": "< string > ",
"pinned": "< bool > "
}
}
```
The json in the data field is also stringified.
---
### Subscribe User
```
GET /user/subscribe/user
```
Subscribe to an Eventsource stream giving update in changes in state of the users database.
#### Success (200 OK)
An Eventsource stream. Each event (stringified json) will be of the following format:
```json
{
"type": "< add | update > ",
"data": {
"id": "< user id > ",
"username": "< string > ",
"bio": "< string > ",
"profile_pic": "< string > ",
"last_name": "< string > ",
"phone_number": "< string > "
}
}
```
The json in the data field is also stringified.
---
### Subscribe Member
```
GET /user/subscribe/conversation/:conversation/member
```
Subscribe to an Eventsource stream giving update in changes in state of the conversation members database.
#### URL Params
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| conversation | String | Conversation's ID. | ✓ |
#### Success (200 OK)
An Eventsource stream. Each event (stringified json) will be of the following format:
```json
{
"type": "< add | update > ",
"data": {
"user": "< user id > ",
"conversation": "< conversation id > ",
"pinned": "< bool > "
}
}
```
The json in the data field is also stringified.
---