gotham-restful

This crate is an extension to the popular gotham web framework for Rust. The idea is to have several RESTful resources that can be added to the gotham router. This crate will take care of everything else, like parsing path/query parameters, request bodies, and writing response bodies, relying on serde and serde_json for (de)serializing. If you enable the openapi feature, you can also generate an OpenAPI Specification from your RESTful resources.

Note: The stable branch contains some bugfixes against the last release. The master branch currently tracks gotham's master branch and the next release will use gotham 0.5.0 and be compatible with the new future / async stuff.

Usage

A basic server with only one resource, handling a simple GET request, could look like this:

/// Our RESTful Resource.
#[derive(Resource)]
#[rest_resource(read_all)]
struct UsersResource;

/// Our return type.
#[derive(Deserialize, Serialize)]
struct User {
	id: i64,
	username: String,
	email: String
}

/// Our handler method.
#[rest_read_all(UsersResource)]
fn read_all(_state: &mut State) -> Success<Vec<User>> {
	vec![User {
		id: 1,
		username: "h4ck3r".to_string(),
		email: "h4ck3r@example.org".to_string()
	}].into()
}

/// Our main method.
fn main() {
	gotham::start("127.0.0.1:8080", build_simple_router(|route| {
		route.resource::<UsersResource>("users");
	}));
}

Uploads and Downloads can also be handled, but you need to specify the mime type manually:

#[derive(Resource)]
#[rest_resource(create)]
struct ImageResource;

#[derive(FromBody, RequestBody)]
#[supported_types(mime::IMAGE_GIF, mime::IMAGE_JPEG, mime::IMAGE_PNG)]
struct RawImage {
	content: Vec<u8>,
	content_type: Mime
}

#[rest_create(ImageResource)]
fn create(_state : &mut State, body : RawImage) -> Raw<Vec<u8>> {
	Raw::new(body.content, body.content_type)
}

Look at the example for more methods and usage with the openapi feature.

Known Issues

These are currently known major issues. For a complete list please see the issue tracker. If you encounter any issues that aren't yet reported, please report them here.

Enabling the openapi feature might break code (#4)
For chrono's DateTime types, the format is date-time instead of datetime (openapiv3#14)

License

Licensed under your option of:

4 KiB Raw Blame History

gotham-restful

Usage

Known Issues

License

4 KiB

Raw Blame History