Attribute Macro request 

#[request]

Available on crate feature api only.

Generates OutgoingRequest and IncomingRequest implementations.

The OutgoingRequest impl is feature-gated behind cfg(feature = "client"). The IncomingRequest impl is feature-gated behind cfg(feature = "server").

The generated code expects the Request type to implement Metadata, alongside a Response type that implements OutgoingResponse (for cfg(feature = "server")) and / or IncomingResponse (for cfg(feature = "client")).

The Content-Type header of the OutgoingRequest is unset for endpoints using the GET method, and defaults to application/json for all other methods, except if the raw_body attribute is set on a field, in which case it defaults to application/octet-stream.

By default, the type this macro is used on gets a #[non_exhaustive] attribute. This behavior can be controlled by setting the ruma_unstable_exhaustive_types compile-time cfg setting as --cfg=ruma_unstable_exhaustive_types using RUSTFLAGS or .cargo/config.toml (under [build] -> rustflags = ["..."]). When that setting is activated, the attribute is not applied so the type is exhaustive.

Container Attributes

• #[request(error = ERROR_TYPE)]: Override the EndpointError associated type of the OutgoingRequest and IncomingRequest implementations. The default error type is MatrixError.

Field Attributes

To declare which part of the request a field belongs to:

• #[ruma_api(header = HEADER_NAME)]: Fields with this attribute will be treated as HTTP headers on the request. The value must implement ToString and FromStr. Generally this is a String. The attribute value shown above as HEADER_NAME must be a const expression of the type http::header::HeaderName, like one of the constants from http::header, e.g. CONTENT_TYPE. During deserialization of the request, if the field is an Option and parsing the header fails, the error will be ignored and the value will be None.
• #[ruma_api(path)]: Fields with this attribute will be inserted into the matching path component of the request URL. If there are multiple of these fields, the order in which they are declared must match the order in which they occur in the request path.
• #[ruma_api(query)]: Fields with this attribute will be inserting into the URL’s query string.
• #[ruma_api(query_all)]: Instead of individual query fields, one query_all field, of any type that can be (de)serialized by serde_html_form, can be used for cases where multiple endpoints should share a query fields type, the query fields are better expressed as an enum rather than a struct, or the endpoint supports arbitrary query parameters.
• No attribute: Fields without an attribute are part of the body. They can use #[serde] attributes to customize (de)serialization.
• #[ruma_api(body)]: Use this if multiple endpoints should share a request body type, or the request body is better expressed as an enum rather than a struct. The value of the field will be used as the JSON body (rather than being a field in the request body object).
• #[ruma_api(raw_body)]: Like body in that the field annotated with it represents the entire request body, but this attribute is for endpoints where the body can be anything, not just JSON. The field type must be Vec<u8>.

Examples

pub mod do_a_thing {
    use ruma_common::{api::request, OwnedRoomId};

    // metadata! { ... };

    #[request]
    pub struct Request {
        #[ruma_api(path)]
        pub room_id: OwnedRoomId,

        #[ruma_api(query)]
        pub bar: String,

        #[serde(default)]
        pub foo: String,
    }

    // #[response]
    // pub struct Response { ... }
}

pub mod upload_file {
    use http::header::CONTENT_TYPE;
    use ruma_common::api::request;

    // metadata! { ... };

    #[request]
    pub struct Request {
        #[ruma_api(path)]
        pub file_name: String,

        #[ruma_api(header = CONTENT_TYPE)]
        pub content_type: String,

        #[ruma_api(raw_body)]
        pub file: Vec<u8>,
    }

    // #[response]
    // pub struct Response { ... }
}

⚠ If this is the only documentation you see, please navigate to the docs for ruma_common::api::request, where actual documentation can be found.