Crate gotham_restful
source · [−]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
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
’sDateTime
types, the format isdate-time
instead ofdatetime
(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
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:
Contains the various validations that are applied after decoding a token.
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:
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.
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
.
A response, used to create the final gotham response from.
An AuthHandler
returning always the same secret. See AuthMiddleware
for a usage example.
This can be returned from a resource when there is no cause of an error. For example:
Enums
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):
The source of the authentication token in the request.
The authentication status returned by the auth middleware for each request.
Traits
This trait will help the auth middleware to determine the validity of an authentication token.
This trait allows to draw routes within an resource. Use this only inside the
Resource::setup
method.
This trait adds the resource
method to gotham’s routing. It allows you to register
any RESTful Resource
with a path.
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.
This trait adds the get_openapi
method to an OpenAPI-aware router.
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:
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
.
This trait must be implemented by every RESTful Resource. It will allow you to register the different methods for this Resource.
Handle a POST request on the Resource root.
Handle a DELETE request on the Resource with an id.
Handle a DELETE request on the Resource root.
Handle a GET request on the Resource with an id.
Handle a GET request on the Resource root.
A trait provided to convert a resource’s result to json.
Handle a GET request on the Resource with additional search parameters.
Handle a PUT request on the Resource with an id.
Handle a PUT request on the Resource root.
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
.
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.