An opinionated library to easily plug RPC style JSON APIs into your existing HTTP framework to enable type safe communication with TypeScript (or similar) clients.
The main USP of this library is that it takes advantage of trait and macro magic to automatically infer the shape of the API (paths, descriptions, and the types of request and response for each route) from just the Rust code you've written, negating the need for external definitions like OpenAPI.
Seamless is a library primarily designed to facilitate communication between a Rust backend
and a TypeScript (or similar) client via JSON. By using this library you get:
- The ablity to use any async framework of your choice without feature flags and such.
- A self describing API that can automatically provide back enough information to generate
a fully typed client in a language like TypeScript. This leans on a [macro@ApiBody] macro
which is placed on structs/enums you'd like to receive or return from the API, along with trait
magic.
- Consistent error handling: You can return whatever domain specific errors you like from handlers,
so long as they implement Into<ApiError>. The provided [macro@ApiError] macro makes this simple.
- The ability to pull in state or guard requests using the [handler::HandlerParam] trait. With this
trait, handlers can ask for whatever parameters they need, and know that they won't run if those
parameters cannot be obtained (for example, an invalid user session was provided).
This library also has limitations, some of them being:
- Streaming of request and response bodies is not supported. Currently the library doesn't expose
means to stream data in and our of handlers for the sake of simplicity (instead, everything comes in
and leaves as a Vec<u8>). This is simple to use, but large data transfers should happen
outside of this library.
- Type information from the [Api::info()] method is tuned towards generating TypeScript client
code, and cannot provide enough detail to generate, for example, a well typed Rust client.
- No support for more complex URL matching (eg to extract query params). I don't intend to support this
use case. Keeping parameters in the body allows us to type them properly; this would be much more
difficult to do with query params. Think of this library as more RPC, less REST.
Below is a basic self contained example of using this library. Please have a look in the examples
folder for more detailed examples.
```rust
use seamless::{ http::{ Request }, api::{ Api, ApiBody, ApiError }, handler::body::{ Json } };
// The API relies on types that have been annotated with ApiBody (request and response
// types) or ApiError (for any errors we might give back). These annotations do some
// reflection to allow us to get information about the shape of the type and doc comments
// added to it, as well as ensuring that they can be Serialized/Deserialized.
/// Provide two numbers to get back the division of them.
struct DivisionInput { a: usize, b: usize }
/// The division of two numbers a and b.
struct DivisionOutput { a: usize, b: usize, /// The division of the first and second number result: usize }
// We can use seamless::ApiError to easily allow an existing
// enum or struct to be returnable from the API if things go wrong.
// ApiErrors must implement Debug and Display. We use thiserror
// here to easily implement Display.
enum MathsError { #[error("Division by zero")] #[api_error(external, code=400)] DivideByZero }
// We instantiate an API and add routes to it like so. The handler function would
// often be an external async fn foo() defined elsewhere (see the examples), but
// for the sake of this example we define it inline.
let mut api = Api::new();
api.add("maths.divide")
.description("Divide two numbers by each other")
.handler(|body: Json
// Once we've added routes to the api, we use it by sending http::Requests to it.
// Below, we give the API a quick test and assert that we get back what we expect when
// we do this:
let req = Request::post("/maths.divide") .body(serdejson::tovec(&DivisionInput { a: 20, b: 10 }).unwrap()) .unwrap(); asserteq!( api.handle(req).await.unwrap().intobody(), serdejson::tovec(&DivisionOutput{ a: 20, b: 10, result: 2 }).unwrap() );
let req = Request::post("/maths.divide") .body(serdejson::tovec(&DivisionInput { a: 10, b: 0 }).unwrap()) .unwrap(); asserteq!( api.handle(req).await.unwraperr().unwraperr(), ApiError { code: 400, internalmessage: "Division by zero".toowned(), externalmessage: "Division by zero".to_owned(), value: None } );
```
Most real life use cases will require some sort of state to be accessible inside a handler.
This library follows an approach a little similar to Rocket. Any type that implements the
[handler::HandlerParam] trait can be passed into handler functions. To pass state in, you can
inject it into the http::Request prior to handing it to this library, and then extract it out
of the request again in the [handler::HandlerParam] implementation.
Note: params implementing the RequestParam trait must come before the one that implements
RequestBody (if any) in the handler function argument list.
Here's an example:
```rust use seamless::{ api::{ Api, ApiBody, ApiError }, handler::{ HandlerParam, body::{ Json } }, };
// Something we want to inject into our handler.
struct State;
// Teach the library how to get hold of State when asked for it.
impl HandlerParam for State {
type Error = ApiError;
async fn handler_param(req: &http::Request<()>) -> Result
let mut api = Api::new();
// Note that we can now ask for State as a parameter to the handler. State
// MUST come before our Json<_> parameter. HandlerParam impls are evaluated
// in the order that arguments appear in the parameter list.
api.add("maths/divide")
.description("Divide two numbers by each other")
.handler(|_state: State, body: Json<_>| divide(body.json));
// When passing a request into our API, remember to inject State so that
// it's available for our HandlerParam trait to extract:
let mut req = http::Request::post("/maths/divide")
.body(serdejson::tovec(&BinaryInput { a: 20, b: 10 }).unwrap())
.unwrap();
req.extensions_mut().insert(State);
// We can now handle the request without issues: assert!(api.handle(req).await.is_ok());
```
At some point, you may want to get information about the shape of the API so that you can go
and generate a typed API client. To do this, use the [Api::info()] function.
Probably the best way to see what shapes this info can take is by looking at api/info.rs.
Here's an example:
```rust
use seamless::{ api::{ Api, ApiBody, ApiError }, handler::body::{ Json }, }; use serde_json::json;
enum MathsError { #[error("Division by zero")] #[api_error(external, code=400)] DivideByZero }
/// Input consisting of two numbers
struct BinaryInput { /// Input 'a' a: usize, /// Input 'b' b: usize }
/// Output containing the original input and result
struct BinaryOutput { a: usize, b: usize, /// The result result: usize }
async fn divide(input: BinaryInput) -> Result
// A small APi with one route: let mut api = Api::new(); api.add("maths/divide") .description("Divide two numbers by each other") .handler(|body: Json<_>| divide(body.json));
// Get info about this API: let info = api.info();
// Here's what this will look like when serialized to JSON: let infojson = json!([ { "name": "maths/divide", "description": "Divide two numbers by each other", "method": "POST", "requesttype": { "description": "Input consisting of two numbers", "shape": { "type": "Object", "keys": { "a": { "description": "Input 'a'", "shape": { "type": "Number" } }, "b": { "description": "Input 'b'", "shape": { "type": "Number" } } } } }, "response_type": { "description": "Output containing the original input and result", "shape": { "type": "Object", "keys": { "a": { "description": "", "shape": { "type": "Number" } }, "b": { "description": "", "shape": { "type": "Number" } }, "result": { "description": "The result", "shape": { "type": "Number" } } } } } } ]);
```