jmgilman / rustify

A Rust library for interacting with HTTP API endpoints

rustify

A Rust library for interacting with HTTP API endpoints

Rustify is a small library written in Rust which eases the burden of scaffolding HTTP APIs. It provides an Endpoint trait along with a macro helper which allows templating various remote endpoints. Both asynchronous and synchrounous clients are offered for executing requests against endpoints with the option of implementing custom clients using the Client trait.

Rustify provides support for serializing requests and deserializing responses. Raw requests and responses in the form of bytes are also supported. The library also contains many helpers for dealing with requests like support for middleware and wrapping API responses.

Installation

Add rustify as a dependency to your cargo.toml:

[dependencies]
rustify = "0.6.0"
rustify_derive = "0.5.2"

Usage

Basic

use rustify::{Client, Endpoint};
use rustify_derive::Endpoint;

// Defines an API endpoint at /test/path that takes no inputs and returns an
// empty response.
#[derive(Endpoint)]
#[endpoint(path = "test/path")]
struct Test {}

let endpoint = Test {};
let client = Client::default("http://api.com"); // Configures base address of http://api.com
let result = endpoint.exec(&client).await; // Sends GET request to http://api.com/test/path

assert!(result.is_ok());

Request Body

use derive_builder::Builder;
use rustify::{Client, Endpoint};
use rustify_derive::Endpoint;

// Defines an API endpoint at /test/path/{name} that takes one input for
// creating the url and two inputs for building the request body. The content
// type of the request body defaults to JSON, however, it can be modified by
// passing the `request_type` parameter to the endpoint configuration.
//
// Note: The `#[endpoint(body)]` attribute tags are technically optional in the
// below example. If no `body` attribute is found anywhere then rustify defaults
// to serializing all "untagged" fields as part of the body. Fields can be opted
// out of this behavior by tagging them with #[endpoint(skip)].
#[derive(Builder, Endpoint)]
#[endpoint(path = "test/path/{self.name}", method = "POST", builder = "true")]
#[builder(setter(into))] // Improves the building process
struct Test {
    #[endpoint(skip)] // This field shouldn't be serialized anywhere
    pub name: String, // Used to create a dynamic URL
    #[endpoint(body)] // Instructs rustify to serialize this field as part of the body
    pub age: i32,
    #[endpoint(body)]
    pub role: String,
}

// Setting `builder` to true creates a `builder()` method on our struct that
// returns the TestBuilder type created by `derive_builder`.
let endpoint = Test::builder()
        .name("jmgilman")
        .age(42)
        .role("CEO")
        .build()
        .unwrap();
let client = Client::default("http://api.com");
let result = endpoint.exec(&client).await; // Sends POST request to http://api.com/test/path/jmgilman

assert!(result.is_ok());

Query Parameters

use derive_builder::Builder;
use rustify::{Client, Endpoint};
use rustify_derive::Endpoint;

// Defines a similar API endpoint as in the previous example but adds an
// optional query parameter to the request. Additionally, this example opts to
// not specify the `#[endpoint(body)]` attributes to make use of the default
// behavior covered in the previous example.
#[derive(Builder, Endpoint)]
#[endpoint(path = "test/path/{self.name}", method = "POST", builder = "true")]
#[builder(setter(into, strip_option), default)] // Improves building process
struct Test {
    #[endpoint(skip)]
    pub name: String,
    #[endpoint(query)]
    pub scope: Option<String>, // Note: serialization is skipped when this field is None
    pub age: i32, // Serialized into the request body
    pub role: String, // Serialized into the request body
}

let endpoint = Test::builder()
        .name("jmgilman")
        .scope("global")
        .age(42)
        .role("CEO")
        .build()
        .unwrap();
let client = Client::default("http://api.com");
let result = endpoint.exec(&client).await; // Sends POST request to http://api.com/test/path/jmgilman?scope=global

assert!(result.is_ok());

Responses

use rustify::{Client, Endpoint};
use rustify_derive::Endpoint;

// Defines an API endpoint at /test/path that takes a single byte array which
// will be used as the request body (no serialization occurs). The endpoint
// returns a `TestResponse` which contains the result of the operation.
#[derive(Endpoint)]
#[endpoint(path = "test/path", response = "TestResponse")]
struct Test {
    #[endpoint(raw)] // Indicates this field contains the raw request body
    pub file: Vec<u8>
}

#[derive(Deserialize)]
struct TestResponse {
    pub success: bool,
}

let endpoint = Test {
    file: b"contents".to_vec(),
};
let client = Client::default("http://api.com");
let result = endpoint.exec(&client).await;

assert!(result.is_ok());

let response = result.unwrap().parse().unwrap(); // Returns the parsed `TestResponse`
dbg!(response.success);

Examples

You can find example usage in the examples directory. They can be run with cargo:

cargo run --package rustify --example reqres1
cargo run --package rustify --example reqres2

The vaultrs crate is built upon rustify and serves as as good reference.

Features

The following features are available for this crate:

• blocking: Enables the blocking variants of Clients as well as the blocking exec() functions in Endpoints.

Error Handling

All errors generated by this crate are wrapped in the ClientError enum provided by the crate.

Testing

See the the tests directory for tests. Run tests with cargo test.

Contributing

Check out the issues for items needing attention or submit your own and then:

1. Fork it (https://github.com/jmgilman/rustify/fork)
2. Create your feature branch (git checkout -b feature/fooBar)
3. Commit your changes (git commit -am 'Add some fooBar')
4. Push to the branch (git push origin feature/fooBar)
5. Create a new Pull Request

rustify's Issues

RUSTSEC-2020-0095: difference is unmaintained

difference is unmaintained

Details
Status	unmaintained
Package	difference
Version	2.0.0
URL	johannhof/difference.rs#45
Date	2020-12-20

The author of the difference crate is unresponsive.

Maintained alternatives:

• dissimilar

• similar

• treediff

• diffus

See advisory page for additional details.

Requests should have `Content-Type: application/json`

The documentation strongly suggests that the content-type is set to JSON, but this doesn't happen anywhere!

We're using the following middleware … but it would be nice if it was included by default.

pub struct ContentTypeMiddleware;

impl MiddleWare for ContentTypeMiddleware {
    fn request<E>(
        &self,
        _: &E,
        req: &mut http::request::Request<Vec<u8>>,
    ) -> Result<(), ClientError>
    where
        E: Endpoint,
    {
        req.headers_mut()
            .append("content-type", HeaderValue::from_static("application/json"));

        Ok(())
    }

    fn response<E>(
        &self,
        _: &E,
        _: &mut http::response::Response<Vec<u8>>,
    ) -> Result<(), ClientError>
    where
        E: Endpoint,
    {
        Ok(())
    }
}

Would you be open to a PR adding this default behaviour?

Version 0.5.4 is a breaking change. It should be yanked and republished as 0.6

The release 0.5.4 includes changes from #17 where the requirement for http was changed from ^0.2.6 to ^1.0.0.

These are breaking changes because http is a public dependency (its types are leaking into the types defined by rustify) so applying a major semver requirement change on http propagates to rustify.

As an example, this now breaks vaultrs which currently depends on rustify: ^0.5.2 and http: ^0.2.9 and assumes unification between its http version and the one from rustify. See jmgilman/vaultrs#91

I recommend the following actions:

• rustify 0.5.4 should be yanked immediately
• rustify 0.6.0 should be released
• Optional: All public dependencies should be re-exported at the lib root and consumers should avoid relying on implicit cargo version unification

Future incompatibility with Rust RFC 3373: Avoid non-local definitions in functions

Rust RFC 3373: Avoid non-local definitions in functions was accepted and it's implementation at rust-lang/rust#120393 found that this crate would be affected by it.

To be more precise users of this crate would be affected by it, in the form of a warn-by-default lint: non_local_definitions. This is because the derive macros from this crate use impl in a local context, const _DERIVE_Endpoint_FOR_???:

rustify/rustify_derive/src/lib.rs

Lines 305 to 308 in 68fdbdb

	let const_name = format!("_DERIVE_Endpoint_FOR_{}", id);
	let const_ident = Ident::new(const_name.as_str(), Span::call_site());
	quote! {
	const #const_ident: () = {

Fortunately I believe a simple fix exist for this crate, by using a const-anon instead of named one (since const-anon are specialized to be "transparent" to their parent):

-    let const_name = format!("_DERIVE_Endpoint_FOR_{}", id);
-    let const_ident = Ident::new(const_name.as_str(), Span::call_site());
     quote! {
-        const #const_ident: () = {
+        const _: () = {

---

I would suggest applying some form of the patch above as well as releasing a patch version of this crate, as to have a fix available for users before or just after the PR is merged.

cc @jmgilman

Add support for flatten

Consider case where I want to add new user to endpint '/users'

POST /users/ 

{
    "name": "foobar"
}

I have a common code base that I cannot modify, but it has the definition of User. I would like have the option like serde(flatten):

use common::User;

#[derive(Debug, Clone, Endpoint)]
#[endpoint(
    path = "/users",
    method = "POST",
    response = "()"
)]
struct CreateUser {
    #[endpoint(flatten)]
    user: User
}