Crate gotham_restful

Expand description

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:

OpenapiRouter

This type is required to build routes while adding them to the generated OpenAPI Spec at the same time. There is no need to use this type directly. See WithOpenapi on how to do this.

OpenapiSchema

This struct needs to be available for every type that can be part of an OpenAPI Spec. It is already implemented for primitive types, String, Vec, Option and the like. To have it available for your type, simply derive from OpenapiType.

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.

GetOpenapi

This trait adds the get_openapi method to an OpenAPI-aware router.

OpenapiType

This trait needs to be implemented by every type that is being used in the OpenAPI Spec. It gives access to the OpenapiSchema of this type. It is provided for primitive types, String and the like. For use on your own types, there is a derive macro:

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.

WithOpenapi

This trait adds the with_openapi method to gotham’s routing. It turns the default router into one that will only allow RESTful resources, but record them and generate an OpenAPI specification on request.

Attribute Macros

Derive Macros