Skip to content

Commit 8fa8839

Browse files
CodeF0xCodeF0x
committed
docs: more concise and better documented readme
1 parent 5e34aee commit 8fa8839

File tree

1 file changed

+119
-123
lines changed

1 file changed

+119
-123
lines changed

‎readme.md‎

Lines changed: 119 additions & 123 deletions
Original file line numberDiff line numberDiff line change
@@ -1,201 +1,197 @@
1-
> Warning: You should probably not use this in production or with any data that is sensitive as the authentication
2-
> system
3-
> is made very amateurish.
1+
Absolutely! Below is an enhanced version of your documentation, incorporating your additional requests:
42

5-
# Cira - a minimalistic ticket system backend
3+
---
64

7-
Cira is a minimalistic ticket system backend for small and simple projects.
8-
You could even use it as an overcomplicated todo app.
5+
# Cira - A Minimalistic Ticket System Backend
96

10-
The only thing it does is to provide an api.
11-
The rest is up to you.
12-
Create a native desktop or smartphone app, or keep in the web as most ticket boards to.
13-
You decide, the possibilities are endless.
7+
Cira is a minimalistic backend for managing tickets in small projects. It provides essential APIs to handle ticket creation, updates, deletion, labeling, assignment, and filtering.
148

15-
## Features
9+
## Overview
10+
Cira offers foundational API functionalities for managing tickets including:
11+
- Creation and deletion of tickets
12+
- Updating existing tickets
13+
- Grouping tickets by labels
14+
- Assigning tickets to users
15+
- Filtering tickets by various criteria
16+
- User authentication via bearer tokens
1617

17-
Cira gives you the foundation to:
18+
## Setup & Usage
1819

19-
- create and delete tickets
20-
- update tickets after creation
21-
- group tickets by labels
22-
- assign tickets to users
23-
- filter tickets by labels, assignee, status and labels
24-
- authentication with bearer tokens
20+
### Prerequisites
21+
Ensure you have installed the following tools:
22+
- [Rust](https://rust-lang.org)
23+
- [Git](https://git-scm.com/)
24+
- [Diesel](https://diesel.rs)
25+
- [SQLite](https://www.sqlite.org/)
2526

26-
## Run Locally
27+
### Running Locally
2728

28-
Simply clone the repository, set up the database and compile the application locally.
29-
Then start it.
30-
You are required to have installed: [the rust programming language](https://rust-lang.org),
31-
[git](https://git-scm.com/), [diesel](https://diesel.rs), [sqlite](https://www.sqlite.org/)
29+
1. **Clone the repository**:
30+
```bash
31+
git clone https://github.com/CodeF0x/cira.git
32+
cd cira
33+
```
34+
2. **Install Diesel CLI for SQLite** and set up database:
35+
```bash
36+
cargo install diesel_cli --no-default-features --features "sqlite"
37+
diesel setup
38+
```
39+
3. **Build and run**:
40+
```bash
41+
cargo build --release
42+
./target/release/cira
43+
```
3244

33-
```bash
34-
git clone https://github.com/CodeF0x/cira.git
35-
cd cira
36-
cargo install diesel_cli --no-default-features --features "sqlite"
37-
diesel setup
38-
cargo build --release
39-
./target/release/cira
40-
```
41-
42-
If you're on Debian and get `error: linking with 'cc' failed: exit status: 1`, make sure to have `build-essential`
43-
installed. Same goes for other distros (build-essential might be called different / have an equivalent).
44-
45-
If this error accours while installing `diesel_cli`, try `sudo apt install -y libsqlite3-dev libpq-dev libmysqlclient-dev`.
45+
**Note**: Make sure to update both `HASH_SECRET` and `JWT_SECRET` in the `.env` file with cryptographically secure values!
4646

47-
There are some default values set in the .env file, you can adjust them as you wish.
48-
Keep in mind to change the code as well.
49-
> ⚠️ Be sure to update both `HASH_SECRET` and `JWT_SECRET` to something cryptographically safe!
47+
### Troubleshooting
5048

51-
If everything went well and there is no output after running the last command, cira is listening on port `8080`.
49+
If you encounter errors during installation or setup:
50+
- On Debian, if you get a `linking with 'cc' failed: exit status: 1` error, ensure `build-essential` is installed.
51+
- For issues while installing Diesel CLI, try running: `sudo apt install -y libsqlite3-dev libpq-dev libmysqlclient-dev`.
5252

53-
You can also launch it in a screen or in a container, so it runs without an active shell session.
53+
---
5454

55-
## Running Tests
55+
## API Documentation
5656

57-
To run tests, set up a fake database that is independent of the actual production database.
58-
You need to have installed [diesel](https://diesel.rs), [sqlite](https://www.sqlite.org/) and [rust](https://rust-lang.org).
57+
### General Information
58+
- **Authorization**: Every endpoint requires a Bearer Token for authentication except the endpoints related to user login and signup (`/api/login` and `/api/signup`).
5959

60-
```bash
61-
diesel migration run --database-url test-backend.sqlite
62-
cargo test
63-
```
64-
65-
## API Reference
60+
### Ticket Management
6661

67-
#### Create a new ticket
62+
#### Create a New Ticket
6863

6964
```http
70-
POST /api/tickets
65+
POST /api/tickets
7166
```
7267

73-
Your payload must be valid JSON and contain the following properties:
68+
**Payload**:
7469

7570
| Property | Type | Description |
7671
|:----------------|:----------------|:------------------------------------------------------------------------------|
77-
| `title` | `string` | **Required**. The title of your ticket |
78-
| `body` | `string` | **Required**. The body of your ticket |
79-
| `labels` | `Array<string>` | **Required**. Labels of your ticket |
80-
| `status` | `string` | **Required**. The status of your ticket (set it to "Open") |
81-
| `assigned_user` | `id \| null` | **Optional**. A user the ticket should be assigned to. Can be omitted or null |
72+
| `title` | `string` | **Required**. Title of the ticket |
73+
| `body` | `string` | **Required**. Body content of the ticket |
74+
| `labels` | `Array<string>` | **Required**. Labels for categorizing the ticket |
75+
| `status` | `string` | **Required**. Status (e.g., 'Open') |
76+
| `assigned_user` | `id \| null` | **Optional**. ID of user assigned to this ticket or `null`. |
8277

83-
Possible Status options:
78+
**Status Options**:
8479

85-
- `Open`
86-
- `Closed`
80+
- Open
81+
- Closed
8782

88-
Possible Label options:
83+
**Label Options**:
8984

90-
- `Feature`
91-
- `Bug`
92-
- `WontFix`
93-
- `Done`
94-
- `InProgress`
85+
- Feature
86+
- Bug
87+
- WontFix
88+
- Done
89+
- InProgress
9590

96-
Creates a new ticket and returns it.
91+
#### Get All Tickets
9792

98-
#### Get tickets
93+
```http
94+
GET /api/tickets
95+
```
96+
97+
Retrieves all tickets.
98+
99+
#### Delete a Ticket
99100

100101
```http
101-
GET /api/tickets
102+
DELETE /api/tickets/{id}
102103
```
103104

104-
Get all tickets.
105+
**Path Parameters**:
105106

106-
#### Delete ticket
107+
| Parameter | Type | Description |
108+
|:----------|:-------|:-----------------------------------|
109+
| `id` | number | **Required**. ID of the ticket |
110+
111+
#### Edit a Ticket
107112

108113
```http
109-
DELETE /api/tickets/{id}
114+
PUT /api/tickets/{id}
110115
```
111116

112-
URL parameters:
117+
**Path Parameters**: (Same as Delete Ticket)
113118

114-
| Property | Type | Description |
115-
|:---------|:---------|:-----------------------------------|
116-
| `id` | `number` | **Required**. The id of the ticket |
119+
**Payload**: (Same structure as Create a New Ticket)
117120

118-
Deletes a ticket and returns it.
121+
### User Authentication
119122

120-
#### Edit a ticket
123+
#### Sign Up
121124

122125
```http
123-
PUT /api/tickets/{id}
126+
POST /api/signup
124127
```
125128

126-
URL parameters:
129+
**Payload**:
127130

128-
| Property | Type | Description |
129-
|:---------|:---------|:-----------------------------------|
130-
| `id` | `number` | **Required**. The id of the ticket |
131+
| Property | Type | Description |
132+
|:---------------|:-------|:---------------------------------------|
133+
| `display_name` | string | **Required**. Display name |
134+
| `email` | string | **Required**. Email address |
135+
| `password` | string | **Required**. Password |
131136

132-
Your payload must be valid JSON and contain the following properties:
137+
#### Login
133138

134-
| Property | Type | Description |
135-
|:----------------|:----------------|:------------------------------------------------------------------------------|
136-
| `title` | `string` | **Required**. The title of your ticket |
137-
| `body` | `string` | **Required**. The body of your ticket |
138-
| `labels` | `Array<string>` | **Required**. Labels of your ticket |
139-
| `status` | `string` | **Required**. The status of your ticket (set it to "Open") |
140-
| `assigned_user` | `id \| null` | **Optional**. A user the ticket should be assigned to. Can be omitted or null |
139+
```http
140+
POST /api/login
141+
```
141142

142-
Possible Status options:
143+
**Payload**:
143144

144-
- `Open`
145-
- `Closed`
145+
| Property | Type | Description |
146+
|:----------|:-------|:---------------------------------------|
147+
| `email` | string | **Required**. Email address |
148+
| `password` | string | **Required**. Password |
146149

147-
Possible Label options:
150+
Returns a bearer token upon successful login.
148151

149-
- `Feature`
150-
- `Bug`
151-
- `WontFix`
152-
- `Done`
153-
- `InProgress`
152+
#### Logout
154153

155-
Updates a ticket and returns it.
154+
```http
155+
POST /api/logout
156+
```
156157

157-
#### Sign up
158+
Logs out the user by invalidating their current token.
158159

159-
```
160-
POST /api/signup
161-
```
160+
### User Management
162161

163-
Your payload must be valid JSON and contain the following properties:
162+
#### Get All Users
164163

165-
| Property | Type | Description |
166-
|:---------------|:---------|:---------------------------------------|
167-
| `display_name` | `string` | **Required**. The user's display name |
168-
| `email` | `string` | **Required**. The user's email address |
169-
| `password` | `string` | **Required**. The user's password |
164+
```http
165+
GET /api/users
166+
```
170167

171-
Create a new user and return it.
168+
Retrieves all users in a simplified format (`id`, `email`, `display_name`).
172169

173-
#### Filter tickets
170+
### Filter Tickets
174171

175172
```http
176-
POST /api/filter
173+
POST /api/filter
177174
```
178175

179-
Your payload must be valid JSON and contain the following properties:
176+
**Payload**:
180177

181178
| Property | Type | Description |
182179
|:----------------|:------------------------|:----------------------------------------------------------------|
183180
| `title` | `string \| null` | **Optional**. Title to search for. Can be omitted or null |
184181
| `labels` | `Array<string> \| null` | **Optional**. Labels to search for. Can be omitted or null |
185182
| `status` | `string \| null` | **Optional**. Status to search for. Can be omitted or null |
186-
| `assigned_user` | `id \| null` | **Optional**. Assignee id to search for. Can be omitted or null |
183+
| `assigned_user` | `id \| null` | **Optional**. Assignee ID to search for. Can be omitted or null |
187184

188-
Lets you filter for tickets and return results.
185+
Returns filtered results.
186+
187+
---
189188

190189
## Contributing
191190

192-
Contributions are always welcome!
191+
Contributions in any form (issues, PRs, feedback) are welcome!
193192

194-
Either by submitting issues, pull requests or just general constructive feedback in the form of issues,
195-
emails or direct messages on Telegram.
193+
---
196194

197195
## License
198196

199197
[MIT](https://choosealicense.com/licenses/mit/)
200-
201-
MIT or "I do not care what you do with this as long as you don't claim it to be your own"-license.

0 commit comments

Comments
 (0)