# Api Design
This docuement contains all planned API endpoints. It is based on the architecture defined in [Architecture Overview](https://miro.com/app/board/o9J_lOMp4ho=/).

**Base path:** <server-path>/<version>

**NOTE:** This file contains additional TODOs and thoughts about the implementation which need to be discussed in detail.

**DISCLAIMER:** As the communication between the users will most probably be implemented by using an external serivce (Google) endpoints regarding this matter were not defined.

## Roles
The following roles are supported:

- Administrator
- Editor
- User (default)

## Topic Regulations
Topics are the key part of the application representing subjects, themes as well as concern and issues the users can discuss about.

---
### Get all topics
This endpoint is mainly used by the client applications giving the users an overview of the exisiting topics.

> TODO: If it is possible to create and mark topics as drafts those may only be returned for authorized users (e.g. editors).

GET /topics

<details>
<summary>See query parameters and responses</summary>

#### Query Parameters

Paramter type | Parameter name | Description | Default value | Is optional | Additional note
|------|----------|-------------|------|------|------|
| PATH | ```count``` | The number of records to return. | TBA | True | Maximum value is X.

---
#### Success Responses

| Http status | Response Description | Response content
|----------|-------------|--------------
| 200 | List of topic objects | ```{"status":"success", "data":{...}}```
---
#### Error Responses

| Http status | Response Description | Response content
|----------|-------------|--------------
| 401 | User is not authorized to execute this action. | ```{"status":"error", "data":{}}```
</details>

---
### Create new topic
This endpoint may only be used by authorized users (Administrator, Editors).

POST /topics

<details>
<summary>See query parameters and responses</summary>

#### Query Parameters

| Paramter type | Parameter name | Description | Default value | Is optional | Additional note
|----------|----------|-------------|------|------|------|
| BODY | ```topic``` | A topic object. | - | False | -

---
#### Success Responses

| Http status | Response Description | Response content
|----------|-------------|--------------
| 200 | UUID of the create topic | ```{"status":"success", "data":{"id":"f780ba37-9355-4824-b295-62c7eaa68b93"}}```

---
#### Error Responses

| Http status | Response Description | Response content
|----------|-------------|--------------
| 401 | User is not authorized to execute this action. | ```{"status":"error", "data":{}}```
</details>

---
### Match user for topic
This endpoint creates a match between two users for a topic (if possible).

POST /topics/{topicId}/{userId}

<details>
<summary>See query parameters and responses</summary>

#### Query Parameters

| Paramter type | Parameter name | Description | Default value | Is optional | Additional note
|----------|----------|-------------|------|------|------|
| PATH | ```topicId``` | Identifies the topic within which a match show be made. | - | False | -
| PATH | ```userId``` | Identifies the user which should be matched. | - | False | -

---
#### Success Responses

> TODO: It needs to be defined what happends with the first user that wants to be matched/ what todo if an uneven number of users that want a match for a topic.

> This also depends on the implementation of the communication between the users.
>> a) If the matching request was successfull a token (or a comparable asset), which enables the calling user to communicate with their match could be returned. Also the user matched has to be informed.
b) If there currently is no possible match it should also be returned as an success informing the user that the match is 'in progress' (system is waiting for another match request for the specified topic).

| Http status | Response Description | Response content
|----------|-------------|--------------
| 200 | TBA | ```{"status":"success", "data":{...}}```

---
#### Error Responses
| Http status | Response Description | Response content
|----------|-------------|--------------
| 401 | User is not authorized to execute this action. | ```{"status":"error", "data":{}}```
| 400 | Returned if given Id is not valid. | ```{"status":"error", "data":{}}```
| 404 | Returned if given Id is not found. | ```{"status":"error", "data":{}}```
</details>

---
### Delete topic
This endpoint may only be used by authorized users (Administrator, Editors).

> TODO: Here (as well as for all delete endpoints) it needs to be evaluated if a topic should be deleted from the database or just be marked as deleted (and deleted after X time units). This is important regarding the data related to the topic entries.

DELETE /topics/{topicId}

<details>
<summary>See query parameters and responses</summary>

#### Query Parameters

| Paramter type | Parameter name | Description | Default value | Is optional | Additional note
|----------|----------|-------------|------|------|------|
| PATH | ```topicId``` | Identifies the topic within should be deleted. | - | False | -

---
#### Success Responses

| Http status | Response Description | Response content
|----------|-------------|--------------
| 200 | TBA | ```{"status":"success", "data":{...}}```

---
#### Error Responses

| Http status | Response Description | Response content
|----------|-------------|--------------
| 401 | User is not authorized to execute this action. | ```{"status":"error", "data":{}}```
| 400 | Returned if given Id is not valid. | ```{"status":"error", "data":{}}```
| 404 | Returned if given Id is not found. | ```{"status":"error", "data":{}}```
</details>

---
### Update topic
This endpoint may only be used by authorized users (Administrator, Editors).

> TODO: Mind that a topic could potenially be change while users are in an active discussion (Notify users about the change? Active a rematch if users wishes to?).

UPDATE /topics/{topicId}

<details>
<summary>See query parameters and responses</summary>

#### Query Parameters

| Paramter type | Parameter name | Description | Default value | Is optional | Additional note
|----------|----------|-------------|------|------|------|
| PATH | ```topicId``` | Identifies the topic within should be updated. | - | False | -
| BODY | ```topic``` | Updated topic instance. | - | False | -

---
#### Success Responses

| Http status | Response Description | Response content
|----------|-------------|--------------
| 200 | TBA | ```{"status":"success", "data":{...}}```

---
#### Error Responses

| Http status | Response Description | Response content
|----------|-------------|--------------
| 401 | User is not authorized to execute this action. | ```{"status":"error", "data":{}}```
| 400 | Returned if given Id is not valid. | ```{"status":"error", "data":{}}```
| 404 | Returned if given Id is not found. | ```{"status":"error", "data":{}}```
</details>

## User

### Query a specific user

GET /users/{userId}

<details>
<summary>See query parameters and responses</summary>

#### Query Parameters

Paramter type | Parameter name | Description | Default value | Is optional | Additional note
|------|----------|-------------|------|------|------|
| PATH | ```userId``` | Identifies the specific user. | - | False | -

---
#### Success Responses

| Http status | Response Description | Response content
|----------|-------------|--------------
| 200 | Get a specific user object | ```{"status":"success", "data":{...}}```
---
#### Error Responses

| Http status | Response Description | Response content
|----------|-------------|--------------
| 401 | User is not authorized to execute this action. | ```{"status":"error", "data":{}}```
| 400 | Returned if given Id is not valid. | ```{"status":"error", "data":{}}```
| 404 | Returned if given Id is not found. | ```{"status":"error", "data":{}}```
</details>

---

### Query a list of user

GET /users

<details>
<summary>See query parameters and responses</summary>

#### Query Parameters

Paramter type | Parameter name | Description | Default value | Is optional | Additional note
|------|----------|-------------|------|------|------|
| PATH | ```count``` | The number of records to return. | TBA | True | Maximum value is X.

---
#### Success Responses

| Http status | Response Description | Response content
|----------|-------------|--------------
| 200 | List of user objects | ```{"status":"success", "data":{...}}```
---
#### Error Responses

| Http status | Response Description | Response content
|----------|-------------|--------------
| 401 | | ```{"status":"error", "data":{}}```
</details>

---
### Create new user

POST /users

<details>
<summary>See query parameters and responses</summary>

#### Query Parameters

| Paramter type | Parameter name | Description | Default value | Is optional | Additional note
|----------|----------|-------------|------|------|------|
| BODY | ```user``` | A user object. | - | F | -

---
#### Success Responses

| Http status | Response Description | Response content
|----------|-------------|--------------
| 200 | UUID of the create user | ```{"status":"success", "data":{"id":"ef2c0004-8bcb-11eb-8dcd-0242ac130003", "created":1616496317}}```
---
#### Error Responses

| Http status | Response Description | Response content
|----------|-------------|--------------
| 401 | | ```{ error : "Authorization failed" }```
</details>

---
### Update User

UPDATE /users/{userId}

<details>
<summary>See query parameters and responses</summary>

#### Query Parameters

Paramter type | Parameter name | Description | Default value | Is optional | Additional note
|------|----------|-------------|------|------|------|
| PATH | ```userId``` | Identifies the specific user. | - | False | -
| BODY | ```user``` | Updated user instance. | - | False | -

---
#### Success Responses

| Http status | Response Description | Response content
|----------|:-------------:|:--------------
| 200 | UUID of the user | ```{"status":"success", "data":{"id":"ef2c0004-8bcb-11eb-8dcd-0242ac130003", "updated":true}}```
---
#### Error Responses

| Http status | Response Description | Response content
|----------|-------------|--------------
| 401 | User is not authorized to execute this action. | ```{"status":"error", "data":{}}```
| 400 | Returned if given Id is not valid. | ```{"status":"error", "data":{}}```
| 404 | Returned if given Id is not found. | ```{"status":"error", "data":{}}```
</details>

---
### Delete User

DELETE /users/{userId}

<details>
<summary>See query parameters and responses</summary>

#### Query Parameters

Paramter type | Parameter name | Description | Default value | Is optional | Additional note
|------|----------|-------------|------|------|------|
| PATH | ```userId``` | Identifies the specific user. | - | False | -

---
#### Success Responses

| Http status | Response Description | Response content
|----------|:-------------:|:--------------
| 200 | UUID of the user | ```{"status":"success", "data":{"id":"ef2c0004-8bcb-11eb-8dcd-0242ac130003", "deleted":true}}```
---
#### Error Responses

| Http status | Response Description | Response content
|----------|-------------|--------------
| 401 | User is not authorized to execute this action. | ```{"status":"error", "data":{}}```
| 400 | Returned if given Id is not valid. | ```{"status":"error", "data":{}}```
| 404 | Returned if given Id is not found. | ```{"status":"error", "data":{}}```
</details>

## Resources
- [Best Practices in API Design](https://swagger.io/resources/articles/best-practices-in-api-design/)
- [Documenting APIs: A guide for technical writers and engineers](https://idratherbewriting.com/learnapidoc/)