82 lines
4.5 KiB
Markdown
82 lines
4.5 KiB
Markdown
# Overview of the API endpoint routing
|
|
|
|
The common prefix for all API routes is `/api`. All resource IDs are of type UUIDv4. Any routes utilizing pagination have the defaults of 50 for limit and 0 for offset.
|
|
|
|
## Auth
|
|
|
|
Unprotected endpoints:
|
|
|
|
- `POST /auth/signup`: Create a new user with `username` and `password` -> Created user's username and ID
|
|
- `POST /auth/login`: Login to an existing user with `username` and `password` -> Cookie with refresh token and response with access token (including user data if `includeUser` URL parameter is `true`)
|
|
|
|
Endpoints protected with `requireAccessToken` middleware:
|
|
|
|
- `GET /auth/me`: Get own user's data -> `userResponse` DTO (user ID, username, admin status, and timestamps of creation and last update)
|
|
- `POST /auth/logout`: Logout the current user -> Cookie that replaces the refresh token with one that expires immediately
|
|
- `PUT /auth/owner/`: Update password of the current user with `old_password` and `new_password` -> Cookie with a new refresh token and response with access token and updated user data
|
|
- `DELETE /auth/owner/`: Delete the current user (as the owner) with `password` -> HTTP 204 response and cookie that replaces the refresh token with one that expires immediately
|
|
- `GET /auth/admin/all`: As an administrator, list all users stored in the system (adjustable with pagination URL parameters) -> Array of `userResponse` DTOs
|
|
- `DELETE /auth/admin/{userID}`: As an administrator, delete a specific user -> HTTP 204 response
|
|
|
|
Endpoints protected with `requireRefreshToken` and `gorilla/csrf` middlewares:
|
|
|
|
- `GET /auth/cookie/csrf`: Get new CSRF token -> HTTP 204 response with the token set in the `X-CSRF-Token` response header
|
|
- `POST /auth/cookie/refresh`: Perform token rotation (revokes the old refresh token server-side) -> Cookie with new refresh token and response with access token
|
|
|
|
## Notes
|
|
|
|
All notes related endpoints are protected with `requireAccessToken` middleware, which means that `Bearer <JWT_AT>` must be included into the Authorization header of each request. The middleware automatically attaches JWT's user claims into the request's context.
|
|
|
|
- `POST /notes`: Create a new note -> Placeholder contents (`title` and `content`)
|
|
- `GET /notes`: List the metadata of all owned notes -> Array of `data.ListNoteRows` (note ID, owner ID, title, and timestamp of last update)
|
|
- `GET /notes/{noteID}`: Get the full representation of a specific note -> `data.GetFullNoteRow` (metadata + current version's title and content)
|
|
- `DELETE /notes/{noteID}`: Delete a specific note -> HTTP 204 response
|
|
- `GET /notes/{noteID}/versions`: Get version metadata history of a specific note (adjustable with pagination URL parameters) -> Array of `data.GetVersionHistoryRow` (version ID, title, version number, and timestamp of creation)
|
|
- `POST /notes/{noteID}/versions`: Create a new version for a specific note with `title` and `content` -> HTTP 204 response
|
|
- `GET /notes/{noteID}/{versionID}`: Get the full representation of a specific version of a specific note -> `data.GetVersionRow` (metadata + the version's content)
|
|
|
|
# Practical client usage
|
|
|
|
## Auth sequence
|
|
|
|
|
|
|
|
- Store access and CSRF tokens in memory (never in `localStorage`)
|
|
- Automatically handle 401 responses by attempting token refresh
|
|
- Queue pending requests during token refresh, if necessary
|
|
- Clear local tokens on logout (`POST /auth/logout`)
|
|
|
|
## Flow of accessing protected resources
|
|
|
|
|
|
|
|
## Flow of accessing versioned notes
|
|
|
|
|
|
|
|
## Admin resources
|
|
|
|
- Verification of the presence of `isAdmin` tag before rendering
|
|
- Graceful handling of 403 errors
|
|
- Automatic refresh of locally cached users list (if any) after admin actions (e.g. deleting users)
|
|
|
|
## Error cases
|
|
|
|
- Invalid token (401):
|
|
- While using access token -> Automatically attempt refresh
|
|
- While using refresh token -> Redirect to login page
|
|
- Insufficient permissions (403): Don't render the corresponding route
|
|
- Resource not found (404): Render a dedicated 404 view
|
|
|
|
## State management
|
|
|
|
- Authentication state
|
|
- Resource state (current note)
|
|
- Pagination state (current page, page size, and total locally cached items)
|
|
|
|
## Necessary client interceptors
|
|
|
|
- Requests: Add authorization (access token as bearer) or CSRF token header
|
|
- Responses: Handle 401 -> Attempt to automatically rotate the tokens
|
|
- Errors: Handle network errors + [aforementioned](#error-cases) API error formats
|