Struct seamless::api::Api

pub struct Api { /* fields omitted */ }

The entry point; you can create an instance of this and then add API routes to it using Self::add(). You can then get information about the routes that have been added using Self::info(), or handle an http::Request using Self::handle().

Implementations

impl Api

pub fn new() -> Api

Instantiate a new API.

pub fn new_with_base_path<S: Into<String>>(base_path: S) -> Api

Instantiate a new API that will handle requests that begin with the provided base path.

For example, if the provided base_path is "/foo/bar", and a route with the path "hi" is added, then an incoming http::Request with the path "/foo/bar/hi" will match it.

pub fn add<P: Into<String>>(&mut self, path: P) -> RouteBuilder<'_>

Add a new route to the API. You must provide a path to make this route available at, and are given back a RouteBuilder which can be used to give the route a handler and a description.

Examples

// This route expects a JSON formatted string to be provided, and echoes it straight back.
api.add("some/route/name")
   .description("This route takes some Foo's in and returns some Bar's")
   .handler(|body: Json<String>| async move { Ok::<_,std::convert::Infallible>(body.json) });

// This route delegates to an async fn to sum some values, so we can infer more types in the
// handler.
api.add("another.route")
   .description("This route takes an array of values and sums them")
   .handler(|body: Json<_>| sum(body.json));

async fn sum(ns: Vec<u64>) -> Result<u64, Infallible> {
    Ok(ns.into_iter().sum())
}

pub async fn handle(
    &self,
    req: Request<Vec<u8>>
) -> Result<Response<Vec<u8>>, RouteError<ApiError>>

Match an incoming http::Request against our API routes and run the relevant handler if a matching one is found. We'll get back bytes representing a JSON response back if all goes ok, else we'll get back a RouteError, which will either be RouteError::NotFound if no matching route was found, or a RouteError::Err if a matching route was found, but that handler emitted an error.

pub fn info(&self) -> Vec<RouteInfo>

Return information about the API routes that have been defined so far.