Skip to content

Commit 4e2be3b

Browse files
jslvtrjslvtr
committed
📝 (Flask-Smorest) Make final REST API project endpoints easier to read
1 parent e7cc856 commit 4e2be3b

File tree

1 file changed

+53
-27
lines changed
  • docs/docs/01_course_intro/04_what_is_rest_api

1 file changed

+53
-27
lines changed

‎docs/docs/01_course_intro/04_what_is_rest_api/README.md

Lines changed: 53 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -121,33 +121,59 @@ In this course we'll build a REST API to expose interactions with stores, items,
121121
- Create tags and link them to items; and search for items with specific tags.
122122
- Add user authentication to the client apps using the API.
123123

124-
The API will have these endpoints:
125-
126-
- Users
127-
- `POST /register` to create user accounts given an `email` and `password`.
128-
- `POST /login` to get a JWT given an `email` and `password`.
129-
- `POST /logout` to revoke a JWT.
130-
- `POST /refresh` to get a fresh JWT given a refresh JWT.
131-
- `GET /user/{user_id}` (dev-only) to get info about a user given their ID.
132-
- `DELETE /user/{user_id}` (dev-only) to delete a user given their ID.
133-
- Stores
134-
- `GET /stores` to get a list of all stores.
135-
- `POST /stores` to create a store.
136-
- `GET /stores/{id}` to get a single store, given its unique id.
137-
- `DELETE /stores/{id}` to delete a store, given its unique id.
138-
- Items
139-
- `GET /items` to get a list of all items in all stores.
140-
- `POST /items` to create a new item, given its name and price in the body of the request.
141-
- `GET /items/{id}` to get information about a specific item, given its unique id.
142-
- `PUT /items/{id}` to update an item given its unique id. The item name or price can be given in the body of the request.
143-
- `DELETE /items/{id}` to delete an item given its unique id.
144-
- Tags
145-
- `GET /stores/{id}/tags` to get a list of tags in a store.
146-
- `POST /stores/{id}/tags` to create a new tag.
147-
- `POST /items/{id}/tags` to link an item in a store with a tag from the same store. This will take a list of tags in the body of the request so clients can link one or more tags at the same time.
148-
- `DELETE /items/{item_id}/tags/{tag_id}` to unlink a tag from an item.
149-
- `GET /tags/{id}` to get information about a tag given its unique id.
150-
- `DELETE /tags/{id}` to delete a tag, which must have no associated items.
124+
The API will have the endpoints shown below.
125+
126+
:::info What do the locks mean?
127+
It's usually important in APIs that only certain people have access to certain endpoints. For example, paying customers may have access to certain endpoints while free users may not.
128+
129+
We'll deal with user authentication in a later section, but that's what the locks (🔒) mean below.
130+
131+
- One 🔒 means the user will need to have authenticated within the last few days to make a request.
132+
- Two 🔒🔒 means the user will need to have authenticated within the last few minutes to make a request.
133+
- No locks means anybody can make a request.
134+
:::
135+
136+
### Users
137+
138+
| Method | Endpoint | Description |
139+
| -------------- | ----------------- | ----------------------------------------------------- |
140+
| `POST` | `/register` | Create user accounts given an `email` and `password`. |
141+
| `POST` | `/login` | Get a JWT given an `email` and `password`. |
142+
| 🔒 <br/> `POST` | `/logout` | Revoke a JWT. |
143+
| 🔒 <br/> `POST` | `/refresh` | Get a fresh JWT given a refresh JWT. |
144+
| `GET` | `/user/{user_id}` | (dev-only) Get info about a user given their ID. |
145+
| `DELETE` | `/user/{user_id}` | (dev-only) Delete a user given their ID. |
146+
147+
148+
### Stores
149+
150+
| Method | Endpoint | Description |
151+
| ------ | -------------- | ---------------------------------------- |
152+
| `GET` | `/stores` | Get a list of all stores. |
153+
| `POST` | `/stores` | Create a store. |
154+
| `GET` | `/stores/{id}` | Get a single store, given its unique id. |
155+
| `POST` | `/stores/{id}` | Delete a store, given its unique id. |
156+
157+
### Items
158+
159+
| Method | Endpoint | Description |
160+
| ---------------- | ------------- | --------------------------------------------------------------------------------------------------- |
161+
| 🔒 <br/> `GET` | `/items` | Get a list of all items in all stores. |
162+
| 🔒🔒 <br/> `POST` | `/items` | Create a new item, given its name and price in the body of the request. |
163+
| 🔒 <br/> `GET` | `/items/{id}` | Get information about a specific item, given its unique id. |
164+
| `PUT` | `/items/{id}` | Update an item given its unique id. The item name or price can be given in the body of the request. |
165+
| 🔒 <br/> `DELETE` | `/items/{id}` | Delete an item given its unique id. |
166+
167+
### Tags
168+
169+
| Method | Endpoint | Description |
170+
| -------- | ----------------------- | ------------------------------------------------------- |
171+
| `GET` | `/stores/{id}/tags` | Get a list of tags in a store. |
172+
| `POST` | `/stores/{id}/tags` | Create a new tag. |
173+
| `POST` | `/items/{id}/tags/{id}` | Link an item in a store with a tag from the same store. |
174+
| `DELETE` | `/items/{id}/tags/{id}` | Unlink a tag from an item. |
175+
| `GET` | `/tags/{id}` | Get information about a tag given its unique id. |
176+
| `DELETE` | `/tags/{id}` | Delete a tag, which must have no associated items. |
151177

152178
As you can see, we've got a lot to build!
153179

0 commit comments

Comments
 (0)