From 4e2be3b4788c6ec3080869919dd7a9eee03bdf47 Mon Sep 17 00:00:00 2001 From: Jose Salvatierra Date: Wed, 25 May 2022 10:56:36 +0100 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20(Flask-Smorest)=20Make=20final?= =?UTF-8?q?=20REST=20API=20project=20endpoints=20easier=20to=20read?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../04_what_is_rest_api/README.md | 80 ++++++++++++------- 1 file changed, 53 insertions(+), 27 deletions(-) diff --git a/docs/docs/01_course_intro/04_what_is_rest_api/README.md b/docs/docs/01_course_intro/04_what_is_rest_api/README.md index b60aed9c..e6dc20b4 100644 --- a/docs/docs/01_course_intro/04_what_is_rest_api/README.md +++ b/docs/docs/01_course_intro/04_what_is_rest_api/README.md @@ -121,33 +121,59 @@ In this course we'll build a REST API to expose interactions with stores, items, - Create tags and link them to items; and search for items with specific tags. - Add user authentication to the client apps using the API. -The API will have these endpoints: - -- Users - - `POST /register` to create user accounts given an `email` and `password`. - - `POST /login` to get a JWT given an `email` and `password`. - - `POST /logout` to revoke a JWT. - - `POST /refresh` to get a fresh JWT given a refresh JWT. - - `GET /user/{user_id}` (dev-only) to get info about a user given their ID. - - `DELETE /user/{user_id}` (dev-only) to delete a user given their ID. -- Stores - - `GET /stores` to get a list of all stores. - - `POST /stores` to create a store. - - `GET /stores/{id}` to get a single store, given its unique id. - - `DELETE /stores/{id}` to delete a store, given its unique id. -- Items - - `GET /items` to get a list of all items in all stores. - - `POST /items` to create a new item, given its name and price in the body of the request. - - `GET /items/{id}` to get information about a specific item, given its unique id. - - `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. - - `DELETE /items/{id}` to delete an item given its unique id. -- Tags - - `GET /stores/{id}/tags` to get a list of tags in a store. - - `POST /stores/{id}/tags` to create a new tag. - - `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. - - `DELETE /items/{item_id}/tags/{tag_id}` to unlink a tag from an item. - - `GET /tags/{id}` to get information about a tag given its unique id. - - `DELETE /tags/{id}` to delete a tag, which must have no associated items. +The API will have the endpoints shown below. + +:::info What do the locks mean? +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. + +We'll deal with user authentication in a later section, but that's what the locks (🔒) mean below. + +- One 🔒 means the user will need to have authenticated within the last few days to make a request. +- Two 🔒🔒 means the user will need to have authenticated within the last few minutes to make a request. +- No locks means anybody can make a request. +::: + +### Users + +| Method | Endpoint | Description | +| -------------- | ----------------- | ----------------------------------------------------- | +| `POST` | `/register` | Create user accounts given an `email` and `password`. | +| `POST` | `/login` | Get a JWT given an `email` and `password`. | +| 🔒
`POST` | `/logout` | Revoke a JWT. | +| 🔒
`POST` | `/refresh` | Get a fresh JWT given a refresh JWT. | +| `GET` | `/user/{user_id}` | (dev-only) Get info about a user given their ID. | +| `DELETE` | `/user/{user_id}` | (dev-only) Delete a user given their ID. | + + +### Stores + +| Method | Endpoint | Description | +| ------ | -------------- | ---------------------------------------- | +| `GET` | `/stores` | Get a list of all stores. | +| `POST` | `/stores` | Create a store. | +| `GET` | `/stores/{id}` | Get a single store, given its unique id. | +| `POST` | `/stores/{id}` | Delete a store, given its unique id. | + +### Items + +| Method | Endpoint | Description | +| ---------------- | ------------- | --------------------------------------------------------------------------------------------------- | +| 🔒
`GET` | `/items` | Get a list of all items in all stores. | +| 🔒🔒
`POST` | `/items` | Create a new item, given its name and price in the body of the request. | +| 🔒
`GET` | `/items/{id}` | Get information about a specific item, given its unique id. | +| `PUT` | `/items/{id}` | Update an item given its unique id. The item name or price can be given in the body of the request. | +| 🔒
`DELETE` | `/items/{id}` | Delete an item given its unique id. | + +### Tags + +| Method | Endpoint | Description | +| -------- | ----------------------- | ------------------------------------------------------- | +| `GET` | `/stores/{id}/tags` | Get a list of tags in a store. | +| `POST` | `/stores/{id}/tags` | Create a new tag. | +| `POST` | `/items/{id}/tags/{id}` | Link an item in a store with a tag from the same store. | +| `DELETE` | `/items/{id}/tags/{id}` | Unlink a tag from an item. | +| `GET` | `/tags/{id}` | Get information about a tag given its unique id. | +| `DELETE` | `/tags/{id}` | Delete a tag, which must have no associated items. | As you can see, we've got a lot to build!