adhalianna / tracke.rs Goto Github PK

Multiple user stories require much more specific and correct errors returned by the API. The first step in dealing with that will be creation of some new error types that will be used in return types in multiple parts and layers of the server.

Acceptance criteria:

• A single task can belong only to a single tasks tracker at a time. (This is unlike tags - a single task can have multiple or none tags assigned).
• There must exist for each user a default task tracker that cannot be removed by the user and to which all the tasks without a relation to any other tracker are assigned.
• All the task trackers have names and can be renamed. The constraints on the names of the trackers should be the same as on the task titles. Both PATCH and PUT requests should be supported for the rename operation.
• A user can use the API to query, sort and filter tasks within the scope of a single tracker using the same query parameters that can be used to query within the scope of all the user's tasks
• Task trackers must have a globally unique ID independent of its name that should be used in URLs to identify them as a resource
• All trackers which are not the default task tracker for a given user can be deleted with a DELETE request which also results in deleting all the tasks belonging to the selected tracker.
• Attempting to DELETE the default task tracker results in an error with status code 403 ("Forbidden") and a message: "the specified task tracker is considered the default task tracker for the user and as such it cannot be removed".
• Tasks which are created with no task tracker ID provided belong to the default task tracker. To change the relation a different task tracker ID can be provided during the task update or creation.
• Filtering the tasks using task trackers should be faster than when tags are used to limit the results. This should be achieved using at least well defined foreign keys on the schemas defining trackers and tasks in the database.

To be compliant with the HATEOAS requirement, besides returning the resources, the API should also return applicable links to other paths. To do so we could implement a common structure of responses that contains an additional "links" field. While at it it would be useful to have the responses better documented. At the moment the responses which include additional Location header do not get documentation generated by aide.

Acceptance criteria:

• Trackers must have a field listing all users (by email) who can add and modify tasks within a given tracker.
• A user who has been granted collaboration rights to a specific tracker by another user can view the tracker and tasks within it. This user cannot however modify the tracker, they can only modify tasks within the tracker.
• To grant access to a tracker to another user, the owner only has to add the email of that user to the list of users with access to the tracker.
• The owner of the tracker is not mentioned on the list of users who were granted the access.
• When a user who does not own a tracker but has access to it fetches the tracker the email of the owner should be included in the fields of the response.
• When a user attempts to access a tracker to which they do not have an access an error should be returned with status code 403 ("Forbidden") and a message "no access to the selected tracker". The same error should be returned when the user attempts to fetch a single task belonging to a tracker to which there is no access.

Views are meant to simplify implementing API clients which desire to present the user's trackers in a consistent and defined by the user manner.

Acceptance criteria:

• Views are seen by the API as a resource belonging to a specific user that can be deleted (with DELETE request), updated (with PUT request), and created (POST)
• Views are an aggregation of trackers with query parameters that can be used on those trackers stored alongside. Each entry in a view must have a tracker id and a list of query parameters. Additionally an entry can have a name which is a non-empty UTF-8 string of length up to 256 bytes.
• The query parameters used by a view must be stored and presented by the API as an array of key-value pairs (JSON objects with a single field). The array can be empty. In the database representation the column storing the array should never be null but instead an empty array should be used.
• A view must have a name. Unlike many other resources managed by the API it must create a composite unique key with the user's email. The name must be a non-empty UTF-8 string of length up to 256 bytes.
• When a view is fetched with the API it should include in its response composed, ready links that can be used to fetch then individual trackers.
• A user has access only to their own views.

To proceed with user story #39 it would be sweet to use SendGrid API but the API key for that service happens to be the first thing in the project that should be a secret environment variable and with that included keeping the env files in the repo no longer sounds like a good idea.

Related to user story in issue #41.

The table for trackers should be defined in the schema along with the mapping to it model in the models crate.

Create in the migrations a test user who has a couple of tasks and can be used to test endpoints. This way the API around tasks can be tested even when the API for account creation is far from being designed.

If a virus overtakes one of user's authorized clients we do not want that client to enable more clients. If a user's client is overtaken by a virus not much can be saved but this will at least protect the server from abuse.

Acceptance criteria:

• User can add arbitrary tasks to a list or a task tracker associated with his account
• The tasks must include a title which can be an arbitrary UTF-8 encoded text of length up to 256 bytes. If the length limit is exceeded the API should respond using HTTP code 400.
• The tasks do not have to have unique titles, they should be distinguishable by a different id which is returned by the API in the response to POST, PUT and GET requests. The id can but does not have to be provided in the POST requests.
• To complete a task a the user should send a PATCH request with minimal payload containing just a boolean field declaring whether the task should be considered completed or not.
• A task can be deleted by sending a DELETE request to the path unique for the given task.
• The date of completion should be present in the database representation of a completed task and it should be returned when a completed task is queried.
• When a task is marked uncompleted the field with completion date in the database should be filled with null. The database should only store the most recent completion date if the task is in the "completed" state.
• A deleted task should be removed from the relational database.
• A task can obtain several optional fields which include:
  • A soft deadline - represented as a timestamp or a date but stored as timestamp. The timestamp should be interpreted as a date when the hour, minute (etc.) segment is filled with zero values
  • A hard deadline - with representation and interpretation the same as for the soft deadline
  • A description - arbitrary UTF-8 text of size (length) up to 4 KiB
  • Tags - stored and represented as an array of UTF-8 strings of length up to 256 bytes each
• The size/length limits of string typed fields should be verified and enforced by the API server before the attempt to insert the task into the database is made. Those constraints do not have to be expressed as constraints on columns in the SQL database. They exist primarily to limit the memory usage
• To fetch a single task the user should be using the task's ID in the URL path
• A user should not be able to query other user's tasks by their task ids
• A user should be able to request:
  • All their uncompleted tasks
  • All their completed tasks
  • Tasks with selected tags and in the desired state
  • Tasks containing a given phrase in their title (case insensitive)
  • Tasks matching a given regex pattern with their title. The regex must be protected from potential abuse. As a measure of protection the regex should be compiled on the server which can discard overly complex regexes (see the documentation of the regex crate for Rust) and by providing a statement timeout on the SQL query as described in this mailing list.

The user story #37 requires that the documentation uses tags to group the endpoints according to their usage.

Acceptance criteria

• To start a new session a user must have an account and use a log-in API
  • A bad email or password provided to the API result in displaying an error: "email or password not correct". The user should not be informed which part was not correct.
• To register an account a user must provide an email and a password
  • User's email must be unique across the system. If an email is already used by other user the API should return an error containing a message "email already taken by another account" and status code 409 ("Conflict").
  • Passwords must consist of at least 8 characters with at least one letter, one digit and one character from set: !?#$%^&*@-+=. The API should return an error containing a message: "password not strong enough: use at least 8 characters including 1 letter, 1 digit and 1 character from set !?#$%^&*@-+="
  • User must include in the POST body a field specifying whether he agrees to the terms of service. Explicit acceptance of the ToS is required to create an account.
  • Part of the registration process should include verifying the provided email by accessing an activation link sent via email message. The link should be available for confirmation for a limited time of 10 minutes since its creation. Using an expired link must cause an error with HTTP code 410 ("Gone"). Expiration of the link implies that the user must start the registration process over. The potential user must be able to use the same password and email when he starts registration again after the confirmation (account activation) link has expired.
  • Until the registration is completed with the use of confirmation (account activation) link the user cannot log into his account and the account is not marked as active in the database.
• Password should be stored in the database using bcrypt format (library)
• The log-in and registration APIs should not be susceptible to SQL injections
• The timestamp of activation link generation should be stored in the database as well as the timestamp of completed registrations.

To complete the user story #39 the server should use and force HTTPS connection during the registration process.

Acceptance criteria:

• Each task must have an optional field for the universally unique list ID.
• By default the list (if available) should be fetched with a task it is attached to on GET requests fetching the task.
• If a task does not have a list attached a link to list creation should be provided with the task. Otherwise it should provide links for list update (PUT), list removal (DELETE), list fetching (GET), or list creation (POST).
• The order of items in the list should be preserved and well defined. The indexes (starting from 1) should be used in the API paths that allow update (PUT), creation (POST) or removal (DELETE) of a specific list item.
• When a new list item is created it should be returned to the user after POST request with a corrected or added index number. The index numbers should always be sequential (no gaps allowed). The API does not have to support reordering (swapping items when a user updates an item to have a different index number). PUT updates with changed index number should in such situation error with status 409 ("Conflict").
• When an item from a middle of the list is removed the indexes should be reassigned to preserve the order.
• The list item must be a data type that has an information about its state (completed or not completed), index number (within the list) and a UTF-8 text of length up to 256 bytes. The text cannot be an empty string.
• The API for marking items within the list as completed or not should reflect the API for marking tasks completed as closely as possible. It should use the same HTTP verbs, the same or analogous field names and/or the same query parameters (if applicable).

So far I have been using Postman to issue requests to API but this approach is rather uncomfortable. I would prefer something that I can edit from my IDE so that I do not have to jump between windows of different applications and so I would like to try out Hurl.

Acceptance Criteria:

• The OAuth2 Client Credentials flow should be implemented. The API server should work as an OAuth2 server for this flow.
• The application's API should include GET paths to a list of all connected to the user's account applications which is private to the user.
• The authorized by the Client Credential flow application should have all the same rights as the user.
• The API recognizes only a single role of a user and it sees the applications using Client Credentials flow as the user. It does not support multiple scopes in terms of the Client Credentials flow.

Following the newtype pattern some new string types should be defined. This is so that the new types control the OAS documentation generated for them which will allow very easily injecting the information about the max lengths of fields as well as defining some validation rules which would be verified during de-serialization by serde. (Good OAS is required by the user story with issue number #37). This max length parameter could be and most likely should be a const generic parameter for the types.

The goal is to set paths in place rather than to implement the full flow.

This is related to two of most important at the moment user stories #40 and #41

The goal is to design and prototype the endpoints used by the API directly in code. The endpoints can respond with anything at the moment. It is most important that the paths and methods have an initial design.

Acceptance criteria:

• Every route (path) handled by the API must be present in the documentation
• Every type that has constraints or format more specific than the data types supported by the JSON format must be described in the documentation and the expected format/constraints/structure must be mentioned
• The documentation must be in the form of the OpenAPI Specification (OAS) of version at least 3.0
• The routes must be grouped (tagged) in such a way that at least the login, registration and task management APIs are separated
• The server should also provide a service which renders the OAS documentation in a visual form using either Swagger UI or Redoc