Crate http_api_problem

Expand description

§HTTP-API-PROBLEM

A library to create HTTP response content for APIs based on RFC7807.

§Usage

Get the latest version for your Cargo.toml from crates.io.

Add this to your crate root:

use http_api_problem;

§serde

HttpApiProblem implements Serialize and Deserialize for HttpApiProblem.

§Examples

use http_api_problem::*;

let p = HttpApiProblem::new(StatusCode::UNPROCESSABLE_ENTITY)
    .title("You do not have enough credit.")
    .detail("Your current balance is 30, but that costs 50.")
    .type_url("https://example.com/probs/out-of-credit")
    .instance("/account/12345/msgs/abc");

assert_eq!(Some(StatusCode::UNPROCESSABLE_ENTITY), p.status);
assert_eq!(Some("You do not have enough credit."), p.title.as_deref());
assert_eq!(Some("Your current balance is 30, but that costs 50."), p.detail.as_deref());
assert_eq!(Some("https://example.com/probs/out-of-credit"), p.type_url.as_deref());
assert_eq!(Some("/account/12345/msgs/abc"), p.instance.as_deref());

There is also TryFrom<u16> implemented for StatusCode:

use http_api_problem::*;

let p = HttpApiProblem::try_new(422).unwrap()
    .title("You do not have enough credit.")
    .detail("Your current balance is 30, but that costs 50.")
    .type_url("https://example.com/probs/out-of-credit")
    .instance("/account/12345/msgs/abc");

assert_eq!(Some(StatusCode::UNPROCESSABLE_ENTITY), p.status);
assert_eq!(Some("You do not have enough credit."), p.title.as_deref());
assert_eq!(Some("Your current balance is 30, but that costs 50."), p.detail.as_deref());
assert_eq!(Some("https://example.com/probs/out-of-credit"), p.type_url.as_deref());
assert_eq!(Some("/account/12345/msgs/abc"), p.instance.as_deref());

§Status Codes

The specification does not require the HttpApiProblem to contain a status code. Nevertheless this crate supports creating responses for web frameworks. Responses require a status code. If no status code was set on the HttpApiProblem 500 - Internal Server Error will be used as a fallback. This can be easily avoided by only using those constructor functions which require a StatusCode.

§Features

§JsonSchema

The feature json-schema enables a derived implementation for JsonSchema, via schemars.

§Web Frameworks

There are multiple features to integrate with web frameworks:

axum
warp
hyper
actix-web
salvo
tide
rocket (v0.5.0-rc1)

These mainly convert the HttpApiProblem to response types of the frameworks and implement traits to integrate with the frameworks error handling.

Additionally, the feature rocket-okapi (which implies the features rocket and json-schema) implements rocket_okapi’s OpenApiResponder for the json schema generated by the json-schema feature.

§ApiError

The feature api-error enables a structure which can be return from “api handlers” that generate responses and can be converted into an HttpApiProblem.

§License

http-api-problem is primarily distributed under the terms of both the MIT license and the Apache License (Version 2.0).

Structs§

ApiError: An error that should be returned from an API handler of a web service.
ApiErrorBuilder
HttpApiProblem: Description of a problem that can be returned by an HTTP API based on RFC7807
InvalidStatusCode: A possible error value when converting a StatusCode from a u16 or &str.
StatusCode: An HTTP status code (status-code in RFC 9110 et al.).

Statics§

PROBLEM_JSON_MEDIA_TYPE: The recommended media type when serialized to JSON

Traits§

IntoApiError

Functions§

into_actix_response: HttpApiProblem.
into_axum_response: Creates an axum Response from something that can become an HttpApiProblem.
into_hyper_response: Creates an hyper::Response from something that can become an HttpApiProblem.
into_rocket_response: Creates an rocket::Response from something that can become an HttpApiProblem.
into_salvo_response: Creates a salvo::Response from something that can become an HttpApiProblem.
into_tide_response: Creates a tide::Response from something that can become an HttpApiProblem.

Derive Macros§

IntoApiError

Crate http_api_problemCopy item path