Attribute Macro rp1::crud

#[crud]

The crud macro

The crud macro is the main entrypoint for RP1. It should be defined on a struct that implements serde::Serialize and diesel::Queryable.

Example

#[rp1::crud(database = "Db", table = "users", auth = false)]
#[derive(Debug, serde::Serialize, diesel::Queryable, validator::Validate)]
struct User {
    #[primary_key]
    pub id: i32,
    #[validate(email)]
    username: String,
    role: String,
    #[generated]
    created_at: chrono::NaiveDateTime,
    #[generated]
    updated_at: chrono::NaiveDateTime,
}

Macro properties

The following properties can be specified on the main crud attribute macro.

• database: Path: Path to the Rocket database struct. This is the struct for which you added the #[database(...)] attribute from rocket_sync_db_pools. By default we assume such a struct is called Db. Note that this value must be provided in string quotes because of parser limitations.
• table: Ident: Name of the table in the diesel schema on which queries should be executed. Take a look at your schema.rs file or take a look in your database. By default this is assumed to be the snake case variant of your struct name.
• schema: Path: The path to your schema definition. By default we assume that this path is crate::schema, but if you changed the path for the schema or if the schema is located in another crate you should specify this property. Note that this value must be provided as a string because of parser limitations.
• module: Ident: The name of the module where the generated code should go. By default we use a name based on the name of the struct and convert it to snake case (so UserPreferrences whould become user_preferrences).
• max_limit: i64: The maximum number of items returned in a listview. By default this is set to 100.
• auth: bool: Whether or not to enable authorization, take a look at the authorization section for more details on this. By default authorization is enabled.
• create: bool: Whether or not to enable the create endpoint, by default this is enabled.
• read: bool: Whether or not to enable the read endpoint, by default this is enabled.
• update: bool: Whether or not to enable the update endpoint, by default this is enabled.
• delete: bool: Whether or not to enable the delete endpoint, by default this is enabled.
• list: bool: Whether or not to enable the list endpoint, by default this is enabled.

Field attributes

There are several field attributes you can add to a field in your struct to indicate some special meaning for that field, these are:

Attribute	Description
#[generated]	Generated fields that cannot be inserted/updated.
#[primary_key]	The primary key that will be used as an id.
#[not_sortable]	Indicates that a field cannot be used to sort.
#[not_filterable]	Indicates that a field cannot be used for filtering.

Authorization

RP1 allows you to modify the behavior of your endpoints based on some auth object. This auth object can be anything that implements the rocket FromRequest trait (see the guards section in the rocket documentation). You should make sure that your FromRequest guard makes sure that the user struct or enum you retrieve is valid and authenticated. Then, implement the CheckPermissions trait. For more details on the CheckPermissions trait, check its documentation.

Generated API endpoints

Once you added the macro to some struct, you should mount the generated routes in your rocket application. To do this, add a call to mount to your rocket::build call. The mountable routes can be retrieved by calling the get_routes function on your struct. The full function call should be something like .mount("/users", User::get_routes()).

In the sections below all urls are relative to this mounted path. So for example when GET /1 is used below, we actually mean GET /users/1.

In general all your requests should include an Accept: application/json to ensure that all responses will be JSON formatted. If you don’t, you may end up getting a HTML response from Rocket.

Create: POST /

Send a post request on the root route to create a new entity. The post body should never include a generated or primary key column. The body may either be JSON (in which case a Content-Type: application/json header should be included) or x-www-form-urlencoded.

Read: GET /:id

To read a single row/entity from the database, you can do a get request to this route. The response will be the JSON encoded data for that row in the body.

Update: POST /:id

To update an entity send a post request to this route. The same constraints as the create route apply.

Delete: DELETE /:id

Send a delete request to this route to delete an entity from the database.

List GET /

Send a get request to the root route to get a list of all available entities. Note that the maximum number of items that the list handler will return is limited. There are several options you can add to the list endpoint for filtering, sorting and pagination.

• Pagination: to paginate, add the ?offset=n&limit=m parameters to your query. Note that the limit is hard capped, so you can never go over the max_limit as set in the macro.
• Sorting: to sort, add a ?sort=[field] query parameter to your query. You may add multiple sort query parameters. By default a column will be sorted in ascending order. To sort in descending order add a - in front of the field name. E.g. ?sort=-created to sort the created field in descending order.
• Filtering: to filter, add ?filter[field]op=value query parameters. The field should be in brackets and the operator should be one of a predefined list shown below. If you add multiple filters all of those conditions will be applied in conjunction (using AND). If you want to use the eq operation you can leave the operator off, in which case you can use ?filter[field]=value. The possible operations are:
  • eq (the default operator if you don’t provide any operator): the results should be filtered such that all values in a specific column equal the given value.
  • ne: the results should be filtered such that all values in a specific column do not match the given value.
  • lt, le, gt, ge: less than, less than or equal to, greater than, and greater than or equal to operations respectively.
  • in: The value should be a comma separated list of values. If one of the values in that matches the value in the column then that row shoul be included. Note that you cannot use in with columns that contain values with commas, as there is no escaping mechanism.