backend-core

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

Environment variables

Supply environment variables by either exporting them or editing .env.

ENV	Description	Default
LISTEN	Host and port number to listen on	:8080
POSTGRES	URL of Postgres	postgresql://root@localhost:26257/core?sslmode=disable

API

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.

Contents
Create User
Get Users by Phone
Get User by ID
Get User by Username
Update User
Create Conversation
Delete Conversation
Update Conversation
Get Conversations
Get Conversation
Pin Conversation
Unpin Conversation
Create Conversation Member
Get Conversation Members
Create Contact
Get Contacts
Subscribe Contact
Subscribe Conversation
Subscribe User
Subscribe Member

---

Create User

POST /user

Create a new user.

Body

Name	Type	Description	Required
username	String	Username of the added user. Must be unique.	✓
bio	String	Bio of the added user	✓
profile_pic	String	URL of added user's profile picture	✓
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.

{
  "id": "<id>",
  "username": "<username>",
  "bio": "<bio>",
  "profile_pic: "<profile_pic>",
  "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.

[
  {
    "id": "<id>",
    "username": "<username>",
    "bio": "<bio>",
    "profile_pic": "<profile_pic>",
    "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.

---

Get User by ID

GET /user/id/:user

Get a specific user by ID.

URL Params

Name	Type	Description	Required
user	String	User's ID.	✓

Success Response (200 OK)

User object.

{
  "id": "<id>",
  "username": "<username>",
  "bio": "<bio>",
  "profile_pic": "<profile_pic>",
  "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.

---

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.

{
  "id": "<id>",
  "username": "<username>",
  "bio": "<bio>",
  "profile_pic": "<profile_pic>",
  "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.

---

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.

---

Create Conversation*

POST /user/conversation

Create a new conversation for a user.

Body

Name	Type	Description	Required
title	String	Title of the conversation	X
dm	Boolean	Whether the conversation is a DM or not	X
picture	String	URL of the group's picture	X

Success Response (200 OK)

Conversation object.

{
  "id": "<id>",
  "title": "<title>",
  "picture": "<picture>"
}

Errors

Code	Description
400	Error occurred parsing the supplied body/Invalid X-User-Claim header
404	User with supplied ID could not be found in database.
500	Error occurred inserting entries into the database.

---

Delete Conversation*

DELETE /user/conversation/:conversation

Delete the specified conversation.

URL Params

Name	Type	Description	Required
conversation	String	Conversation's ID.	✓

Success Response (200 OK)

Empty body.

Errors

Code	Description
400	Invalid X-User-Claim header.
404	User/Conversation with supplied ID could not be found in database.
500	Error occurred deleting entries from the database.

---

Update Conversation*

PATCH /user/conversation/:conversation

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
picture	String	New URL of the group's picture	X

Success Response (200 OK)

Empty Body. (TODO: Updated conversation)

Errors

Code	Description
400	Error occurred parsing the supplied body/Invalid X-User-Claim header.
404	User/Conversation with supplied ID could not be found in database.
500	Error occurred updating entries in the database.

---

Get Conversations*

GET /user/conversation

Get the conversations of the specified user.

Success Response (200 OK)

List of conversations.

[
  {
    "id": "<id>",
    "title": "<title>"
    "picture": "<picture>",
    "pinned: "<pinned:bool>"
  },
  ...
]

Errors

Code	Description
400	Invalid X-User-Claim header.
500	Error occurred updating entries in the database.

---

Get Conversation*

GET /user/conversation/:conversation

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.

{
  "id": "<id>",
  "title": "<title>",
  "picture": "<picture>",
  "pinned: "<pinned:bool>"
}

Errors

Code	Description
400	Invalid X-User-Claim header.
404	Conversation with supplied ID could not be found in database.
500	Error occurred retrieving entries from the database.

---

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.

---

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.

---

Create Conversation Member*

POST /user/conversation/:conversation/member

Add a member to the specified conversation.

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)

The conversation ID of the conversation the user is added to.

Errors

Code	Description
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.
404	User/Conversation with supplied ID could not be found in database.
500	Error occurred updating entries in the database.

---

Get Conversation Members*

GET /user/conversation/:conversation/member

Get the members of the specified conversation.

URL Params

Name	Type	Description	Required
conversation	String	Conversation's ID.	✓

Success (200 OK)

List of user objects in conversation.

[
  {
    "id": "<id>",
    "username": "<username>",
    "bio": "<bio>",
    "profile_pic": "<profile_pic>",
    "first_name": "<first_name>",
    "last_name": "<last_name>",
    "phone_number": "<phone_number>"
  },
  ...
]

Errors

Code	Description
400	Invalid X-User-Claim header.
500	Error occurred retrieving entries from the database.

---

Create Contact*

POST /user/contact

Add a new contact.

Body

Name	Type	Description	Required
phone_number	String	New contact's phone number. A blank user object will be created if no such ID exists in the database.	✓

Success Response (200 OK)

Empty body

Errors

Code	Description
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.
500	Error occurred updating entries in the database.

---

Get Contacts

GET /user/contact

Get the user's contacts.

Success (200 OK)

List of user objects in user's contacts.

[
  {
    "id": "<id>",
    "username": "<username>",
    "bio": "<bio>",
    "profile_pic": "<profile_pic",
    "first_name": "<first_name>",
    "last_name": "<last_name>"
  },
  ...
]

Errors

Code	Description
400	Invalid X-User-Claim header.
500	Error occurred retrieving entries from the database.

---

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:

{
  "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:

{
  "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:

{
  "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:

{
  "type": "<add|update>",
  "data": {
    "user": "<user id>",
    "conversation": "<conversation id>",
    "pinned": "<bool>"
  }
}

The json in the data field is also stringified.

---