Trait Endpoint

source

pub trait Endpoint:
    Send
    + Sync
    + Sized {
    type Response: DeserializeOwned + Send + Sync;

    const REQUEST_BODY_TYPE: RequestType;
    const RESPONSE_BODY_TYPE: ResponseType;

    // Required methods
    fn path(&self) -> String;
    fn method(&self) -> RequestMethod;

    // Provided methods
    fn query(&self) -> Result<Option<String>, ClientError> { ... }
    fn body(&self) -> Result<Option<Vec<u8>>, ClientError> { ... }
    fn url(&self, base: &str) -> Result<Uri, ClientError> { ... }
    fn request(&self, base: &str) -> Result<Request<Vec<u8>>, ClientError> { ... }
    fn exec<'life0, 'life1, 'async_trait>(
        &'life0 self,
        client: &'life1 (impl 'async_trait + Client),
    ) -> Pin<Box<dyn Future<Output = Result<EndpointResult<Self::Response>, ClientError>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait { ... }
    fn with_middleware<M: MiddleWare>(
        self,
        middleware: &M,
    ) -> MutatedEndpoint<'_, Self, M> { ... }
}

Expand description

Represents a remote HTTP endpoint which can be executed using a crate::client::Client.

This trait can be implemented directly, however, users should prefer using the provided rustify_derive macro for generating implementations. An Endpoint consists of:

An action which is combined with the base URL of a Client to form a fully qualified URL.
A method of type RequestType which determines the HTTP method used when a Client executes this endpoint.
A ResponseType type which determines the type of response this Endpoint will return when executed.

The fields of the struct act as a representation of data that will be serialized and sent to the remote server. Where and how each field appears in the final request is determined by how they are tagged with attributes. For example, fields with #[endpoint(query)] will show up as a query parameter and fields with #[endpoint(body)] will show up in the body in the format specified by Endpoint::REQUEST_BODY_TYPE. By default, if no fields are tagged with #[endpoint(body)] or #[endpoint(raw)] then any untagged fields are assumed to be tagged with #[endpoint(body)] (this reduces a large amount of boilerplate). Fields that should be excluded from this behavior can be tagged with #[endpoint(skip)].

It’s worth noting that fields which have the Option type and whose value, at runtime, is Option::None will not be serialized. This avoids defining data parameters which were not specified when the endpoint was created.

A number of useful methods are provided for obtaining information about an endpoint including its URL, HTTP method, and request data. The request method can be used to produce a fully valid HTTP Request that can be used for executing an endpoint without using a built-in Client provided by rustify.

§Example

use rustify::clients::reqwest::Client;
use rustify::endpoint::Endpoint;
use rustify_derive::Endpoint;

#[derive(Endpoint)]
#[endpoint(path = "my/endpoint")]
struct MyEndpoint {}

// Configure a client with a base URL of http://myapi.com
let client = Client::default("http://myapi.com");
     
// Construct a new instance of our Endpoint
let endpoint = MyEndpoint {};

// Execute our Endpoint using the client
// This sends a GET request to http://myapi.com/my/endpoint
// It assumes an empty response
let result = endpoint.exec(&client).await;

Required Associated Constants§

source

const REQUEST_BODY_TYPE: RequestType

The content type of the request body

source

const RESPONSE_BODY_TYPE: ResponseType

The content type of the response body

Required Associated Types§

source

type Response: DeserializeOwned + Send + Sync

The type that the raw response from executing this endpoint will deserialized into. This type is passed on to the EndpointResult and is used to determine the type returned when the parse() method is called.

Required Methods§

source

fn path(&self) -> String

The relative URL path that represents the location of this Endpoint. This is combined with the base URL from a Client instance to create the fully qualified URL.

source