[−][src]Crate 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.

Usage

To use this crate, add the following to your Cargo.toml:

[dependencies]
gotham_restful = "0.0.1"

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(Vec<u8>);

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

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:

Re-exports

pub use hyper::Chunk;

pub use hyper::StatusCode;

pub use mime::Mime;

Structs

NoContent	This is the return type of a resource that doesn't actually return something. It will result in a 204 No Content answer by default. You don't need to use this type directly if using the function attributes:
Raw
Response	A response, used to create the final gotham response from.
Success	This can be returned from a resource when there is no cause of an error. For example:

Traits

DrawResourceRoutes	This trait allows to draw routes within an resource. Use this only inside the `Resource::setup` method.
DrawResources	This trait adds the `resource` method to gotham's routing. It allows you to register any RESTful `Resource` with a path.
FromBody	This trait must be implemented by every type that can be used as a request body. It allows to create the type from a hyper body chunk and it's content type.
RequestBody	A type that can be used inside a request body. Implemented for every type that is deserializable with serde. If the `openapi` feature is used, it must also be of type `OpenapiType`.
Resource	This trait must be implemented by every RESTful Resource. It will allow you to register the different methods for this Resource.
ResourceCreate	Handle a POST request on the Resource root.
ResourceDelete	Handle a DELETE request on the Resource with an id.
ResourceDeleteAll	Handle a DELETE request on the Resource root.
ResourceRead	Handle a GET request on the Resource with an id.
ResourceReadAll	Handle a GET request on the Resource root.
ResourceResult	A trait provided to convert a resource's result to json.
ResourceSearch	Handle a GET request on the Resource with additional search parameters.
ResourceType
ResourceUpdate	Handle a PUT request on the Resource with an id.
ResourceUpdateAll	Handle a PUT request on the Resource root.
ResponseBody	A type that can be used inside a response body. Implemented for every type that is serializable with serde. If the `openapi` feature is used, it must also be of type `OpenapiType`.

Attribute Macros

rest_create
rest_delete
rest_delete_all
rest_read
rest_read_all
rest_search
rest_update
rest_update_all

Derive Macros

FromBody
OpenapiType
RequestBody
Resource