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

This crate targets stable rust, currently requiring rustc 1.40+. 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::header::HeaderName;

pub use hyper::Chunk;

pub use hyper::StatusCode;

pub use mime::Mime;

pub use result::AuthResult::AuthErr;

Structs

AuthMiddleware

This is the auth middleware. To use it, first make sure you have the auth feature enabled. Then simply add it to your pipeline and request it inside your handler:

AuthValidation

Contains the various validations that are applied after decoding a token.

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.

StaticAuthHandler

An AuthHandler returning always the same secret. See AuthMiddleware for a usage example.

Success

This can be returned from a resource when there is no cause of an error. For example:

Enums

AuthResult

This return type can be used to map another ResourceResult that can only be returned if the client is authenticated. Otherwise, an empty 403 Forbidden response will be issued. Use can look something like this (assuming the auth feature is enabled):

AuthSource

The source of the authentication token in the request.

AuthStatus

The authentication status returned by the auth middleware for each request.

Traits

AuthHandler

This trait will help the auth middleware to determine the validity of an authentication token.

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