Struct http_api_problem::HttpApiProblem

pub struct HttpApiProblem {
    pub type_url: Option<String>,
    pub status: Option<StatusCode>,
    pub title: Option<String>,
    pub detail: Option<String>,
    pub instance: Option<String>,
    /* private fields */
}

Description of a problem that can be returned by an HTTP API based on RFC7807

Example

{
   "type": "https://example.com/probs/out-of-credit",
   "title": "You do not have enough credit.",
   "detail": "Your current balance is 30, but that costs 50.",
   "instance": "/account/12345/msgs/abc",
}

Purpose

The purpose of HttpApiProblem is to generate a meaningful response for clients. It is not intended to be used as a replacement for a proper Error struct within applications.

For a struct which can be returned by HTTP handlers use ApiError which can be enabled with the feature toggle api-error. ApiError can be directly converted into HttpApiProblem.

Status Codes and Responses

Prefer to use one of the constructors which ensure that a StatusCode is set. If no StatusCode is set and a transformation to a response of a web framework is made a StatusCode becomes mandatory which in this case will default to 500.

When receiving an HttpApiProblem there might be an invalid StatusCode contained. In this case the status field will be empty. This is a trade off so that the recipient does not have to deal with another error and can still have access to the remaining fields of the struct.

Fields

type_url: Option<String>

A URI reference RFC3986 that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML [W3C.REC-html5-20141028]). When this member is not present, its value is assumed to be “about:blank”.

status: Option<StatusCode>

The HTTP status code RFC7231, Section 6 generated by the origin server for this occurrence of the problem.

title: Option<String>

A short, human-readable summary of the problem type. It SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization (e.g., using proactive content negotiation; see RFC7231, Section 3.4.

detail: Option<String>

A human-readable explanation specific to this occurrence of the problem.

instance: Option<String>

A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.

Implementations

impl HttpApiProblem

pub fn new<T: Into<StatusCode>>(status: T) -> Self

Creates a new instance with the given StatusCode.

#Example

use http_api_problem::*;

let p = HttpApiProblem::new(StatusCode::INTERNAL_SERVER_ERROR);

assert_eq!(Some(StatusCode::INTERNAL_SERVER_ERROR), p.status);
assert_eq!(None, p.title);
assert_eq!(None, p.detail);
assert_eq!(None, p.type_url);
assert_eq!(None, p.instance);

pub fn try_new<T: TryInto<StatusCode>>( status: T ) -> Result<Self, InvalidStatusCode>

where T::Error: Into<InvalidStatusCode>,

Creates a new instance with the given StatusCode.

Fails if the argument can not be converted into a StatusCode.

#Example

use http_api_problem::*;

let p = HttpApiProblem::try_new(500).unwrap();

assert_eq!(Some(StatusCode::INTERNAL_SERVER_ERROR), p.status);
assert_eq!(None, p.title);
assert_eq!(None, p.detail);
assert_eq!(None, p.type_url);
assert_eq!(None, p.instance);

pub fn with_title<T: Into<StatusCode>>(status: T) -> Self

Creates a new instance with title derived from a StatusCode.

#Example

use http_api_problem::*;

let p = HttpApiProblem::with_title(StatusCode::NOT_FOUND);

assert_eq!(Some(StatusCode::NOT_FOUND), p.status);
assert_eq!(Some("Not Found"), p.title.as_deref());
assert_eq!(None, p.detail);
assert_eq!(None, p.type_url);
assert_eq!(None, p.instance);

pub fn try_with_title<T: TryInto<StatusCode>>( status: T ) -> Result<Self, InvalidStatusCode>

where T::Error: Into<InvalidStatusCode>,

Creates a new instance with title derived from a StatusCode.

Fails if the argument can not be converted into a StatusCode.

#Example

use http_api_problem::*;

let p = HttpApiProblem::try_with_title(404).unwrap();

assert_eq!(Some(StatusCode::NOT_FOUND), p.status);
assert_eq!(Some("Not Found"), p.title.as_deref());
assert_eq!(None, p.detail);
assert_eq!(None, p.type_url);
assert_eq!(None, p.instance);

pub fn with_title_and_type<T: Into<StatusCode>>(status: T) -> Self

Creates a new instance with the title and type_url derived from the StatusCode.

#Example

use http_api_problem::*;

let p = HttpApiProblem::with_title_and_type(StatusCode::SERVICE_UNAVAILABLE);

assert_eq!(Some(StatusCode::SERVICE_UNAVAILABLE), p.status);
assert_eq!(Some("Service Unavailable"), p.title.as_deref());
assert_eq!(None, p.detail);
assert_eq!(Some("https://httpstatuses.com/503".to_string()), p.type_url);
assert_eq!(None, p.instance);

Examples found in repository

examples/additional_fields.rs (line 12)

fn main() {
    let problem = HttpApiProblem::with_title_and_type(StatusCode::INTERNAL_SERVER_ERROR)
        .value("error", &"this sucks")
        .value("everything", &42)
        .value(
            "person",
            &Person {
                name: "Peter".into(),
                age: 77,
            },
        );

    let json = problem.json_string();

    println!("{}", json);

    let parsed: HttpApiProblem = serde_json::from_str(&json).unwrap();

    println!("\n\n{:#?}", parsed);
}

pub fn try_with_title_and_type<T: TryInto<StatusCode>>( status: T ) -> Result<Self, InvalidStatusCode>

where T::Error: Into<InvalidStatusCode>,

Creates a new instance with the title and type_url derived from the StatusCode.

Fails if the argument can not be converted into a StatusCode.

#Example

use http_api_problem::*;

let p = HttpApiProblem::try_with_title_and_type(503).unwrap();

assert_eq!(Some(StatusCode::SERVICE_UNAVAILABLE), p.status);
assert_eq!(Some("Service Unavailable"), p.title.as_deref());
assert_eq!(None, p.detail);
assert_eq!(Some("https://httpstatuses.com/503".to_string()), p.type_url);
assert_eq!(None, p.instance);

pub fn empty() -> Self

Creates a new instance without any field set.

Prefer to use one of the other constructors which ensure that a StatusCode is set. If no StatusCode is set and a transformation to a response of a web framework is made a StatusCode becomes mandatory which in this case will default to 500.

pub fn status<T: Into<StatusCode>>(self, status: T) -> Self

Sets the status

#Example

use http_api_problem::*;

let p = HttpApiProblem::new(StatusCode::NOT_FOUND).title("Error");

assert_eq!(Some(StatusCode::NOT_FOUND), p.status);
assert_eq!(Some("Error"), p.title.as_deref());
assert_eq!(None, p.detail);
assert_eq!(None, p.type_url);
assert_eq!(None, p.instance);

pub fn type_url<T: Into<String>>(self, type_url: T) -> Self

Sets the type_url

#Example

use http_api_problem::*;

let p = HttpApiProblem::new(StatusCode::NOT_FOUND).type_url("http://example.com/my/real_error");

assert_eq!(Some(StatusCode::NOT_FOUND), p.status);
assert_eq!(None, p.title);
assert_eq!(None, p.detail);
assert_eq!(Some("http://example.com/my/real_error".to_string()), p.type_url);
assert_eq!(None, p.instance);

pub fn try_status<T: TryInto<StatusCode>>( self, status: T ) -> Result<Self, InvalidStatusCode>

where T::Error: Into<InvalidStatusCode>,

Tries to set the status

Fails if the argument can not be converted into a StatusCode.

#Example

use http_api_problem::*;

let p = HttpApiProblem::try_new(404).unwrap().title("Error");

assert_eq!(Some(StatusCode::NOT_FOUND), p.status);
assert_eq!(Some("Error"), p.title.as_deref());
assert_eq!(None, p.detail);
assert_eq!(None, p.type_url);
assert_eq!(None, p.instance);

pub fn title<T: Into<String>>(self, title: T) -> Self

Sets the title

#Example

use http_api_problem::*;

let p = HttpApiProblem::new(StatusCode::NOT_FOUND).title("Another Error");

assert_eq!(Some(StatusCode::NOT_FOUND), p.status);
assert_eq!(Some("Another Error"), p.title.as_deref());
assert_eq!(None, p.detail);
assert_eq!(None, p.type_url);
assert_eq!(None, p.instance);

pub fn detail<T: Into<String>>(self, detail: T) -> HttpApiProblem

Sets the detail

#Example

use http_api_problem::*;

let p = HttpApiProblem::new(StatusCode::NOT_FOUND).detail("a detailed description");

assert_eq!(Some(StatusCode::NOT_FOUND), p.status);
assert_eq!(None, p.title);
assert_eq!(Some("a detailed description".to_string()), p.detail);
assert_eq!(None, p.type_url);
assert_eq!(None, p.instance);

pub fn instance<T: Into<String>>(self, instance: T) -> HttpApiProblem

Sets the instance

#Example

use http_api_problem::*;

let p = HttpApiProblem::new(StatusCode::NOT_FOUND).instance("/account/1234/withdraw");

assert_eq!(Some(StatusCode::NOT_FOUND), p.status);
assert_eq!(None, p.title);
assert_eq!(None, p.detail);
assert_eq!(None, p.type_url);
assert_eq!(Some("/account/1234/withdraw".to_string()), p.instance);

pub fn try_value<K, V>( self, key: K, value: &V ) -> Result<Self, Box<dyn Error + Send + Sync + 'static>>

where V: Serialize, K: Into<String>,

Add a value that must be serializable.

The key must not be one of the field names of this struct.

These values get serialized into the JSON on top level.

pub fn value<K, V>(self, key: K, value: &V) -> Self

where V: Serialize, K: Into<String>,

Add a value that must be serializable.

The key must not be one of the field names of this struct. If the key is a field name or the value is not serializable nothing happens.

These values get serialized into the JSON on top level.

Examples found in repository

examples/additional_fields.rs (line 13)

fn main() {
    let problem = HttpApiProblem::with_title_and_type(StatusCode::INTERNAL_SERVER_ERROR)
        .value("error", &"this sucks")
        .value("everything", &42)
        .value(
            "person",
            &Person {
                name: "Peter".into(),
                age: 77,
            },
        );

    let json = problem.json_string();

    println!("{}", json);

    let parsed: HttpApiProblem = serde_json::from_str(&json).unwrap();

    println!("\n\n{:#?}", parsed);
}

pub fn set_value<K, V>(&mut self, key: K, value: &V)

where V: Serialize, K: Into<String>,

Add a value that must be serializable.

The key must not be one of the field names of this struct. If the key is a field name or the value is not serializable nothing happens.

These values get serialized into the JSON on top level.

pub fn get_value<K, V>(&self, key: &str) -> Option<V>

where V: DeserializeOwned,

Returns the deserialized field for the given key.

If the key does not exist or the field is not deserializable to the target type None is returned

pub fn try_set_value<K, V>( &mut self, key: K, value: &V ) -> Result<(), Box<dyn Error + Send + Sync + 'static>>

where V: Serialize, K: Into<String>,

pub fn additional_fields(&self) -> &HashMap<String, Value>

Returns a reference to the serialized fields

If the key does not exist or the field is not deserializable to the target type None is returned

pub fn additional_fields_mut(&mut self) -> &mut HashMap<String, Value>

Returns a mutable reference to the serialized fields

If the key does not exist or the field is not deserializable to the target type None is returned

pub fn keys<K, V>(&self) -> impl Iterator<Item = &String>

where V: DeserializeOwned,

pub fn json_value(&self, key: &str) -> Option<&Value>

Returns the serde_json::Value for the given key if the key exists.

pub fn json_bytes(&self) -> Vec<u8>

Serialize to a JSON Vec<u8>

pub fn json_string(&self) -> String

Serialize to a JSON String

Examples found in repository

examples/additional_fields.rs (line 23)

fn main() {
    let problem = HttpApiProblem::with_title_and_type(StatusCode::INTERNAL_SERVER_ERROR)
        .value("error", &"this sucks")
        .value("everything", &42)
        .value(
            "person",
            &Person {
                name: "Peter".into(),
                age: 77,
            },
        );

    let json = problem.json_string();

    println!("{}", json);

    let parsed: HttpApiProblem = serde_json::from_str(&json).unwrap();

    println!("\n\n{:#?}", parsed);
}

pub fn to_hyper_response(&self) -> Response<Body>

Creates a hyper response.

If status is None 500 - Internal Server Error is the default.

Requires the hyper feature

pub fn to_axum_response(&self) -> Response

Creates an axum Response.

If status is None 500 - Internal Server Error is the default.

Requires the axum feature

pub fn to_actix_response(&self) -> HttpResponse

Creates an actix response.

If status is None or not convertible to an actix status 500 - Internal Server Error is the default.

Requires the actix-web feature

pub fn to_rocket_response(&self) -> Response<'static>

Creates a rocket response.

If status is None 500 - Internal Server Error is the default.

Requires the rocket feature

pub fn to_salvo_response(&self) -> Response

Creates a salvo response.

If status is None 500 - Internal Server Error is the default.

Requires the salvo feature

pub fn to_tide_response(&self) -> Response

Creates a tide response.

If status is None 500 - Internal Server Error is the default.

Requires the tide feature

pub fn with_title_from_status<T: Into<StatusCode>>(status: T) -> Self

👎Deprecated since 0.50.0: please use with_title instead

pub fn with_title_and_type_from_status<T: Into<StatusCode>>(status: T) -> Self

👎Deprecated since 0.50.0: please use with_title_and_type instead

pub fn set_status<T: Into<StatusCode>>(self, status: T) -> Self

👎Deprecated since 0.50.0: please use status instead

pub fn set_title<T: Into<String>>(self, title: T) -> Self

👎Deprecated since 0.50.0: please use title instead

pub fn set_detail<T: Into<String>>(self, detail: T) -> Self

👎Deprecated since 0.50.0: please use detail instead

pub fn set_type_url<T: Into<String>>(self, type_url: T) -> Self

👎Deprecated since 0.50.0: please use type_url instead

pub fn set_instance<T: Into<String>>(self, instance: T) -> Self

👎Deprecated since 0.50.0: please use instance instead

Trait Implementations

impl Clone for HttpApiProblem

fn clone(&self) -> HttpApiProblem

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for HttpApiProblem

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for HttpApiProblem

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for HttpApiProblem

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Error for HttpApiProblem

fn source(&self) -> Option<&(dyn Error + 'static)>

The lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0: use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0: replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type based access to context intended for error reports.

impl From<ApiError> for HttpApiProblem

fn from(error: ApiError) -> Self

Converts to this type from the input type.

impl From<HttpApiProblem> for HttpResponse

fn from(problem: HttpApiProblem) -> HttpResponse

Converts to this type from the input type.

impl From<HttpApiProblem> for Response

fn from(problem: HttpApiProblem) -> Response

Converts to this type from the input type.

impl From<HttpApiProblem> for Response<'static>

fn from(problem: HttpApiProblem) -> Response<'static>

Converts to this type from the input type.

impl From<HttpApiProblem> for Response

fn from(problem: HttpApiProblem) -> Response

Converts to this type from the input type.

impl From<HttpApiProblem> for Response<Body>

fn from(problem: HttpApiProblem) -> Response<Body>

Converts to this type from the input type.

impl From<HttpApiProblem> for Response

fn from(problem: HttpApiProblem) -> Response

Converts to this type from the input type.

impl From<Infallible> for HttpApiProblem

fn from(error: Infallible) -> HttpApiProblem

Converts to this type from the input type.

impl From<StatusCode> for HttpApiProblem

fn from(status: StatusCode) -> HttpApiProblem

Converts to this type from the input type.

impl IntoResponse for HttpApiProblem

fn into_response(self) -> Response

Create a response.

impl JsonSchema for HttpApiProblem

fn schema_name() -> String

The name of the generated JSON Schema.

fn schema_id() -> Cow<'static, str>

Returns a string that uniquely identifies the schema produced by this type.

fn json_schema(gen: &mut SchemaGenerator) -> Schema

Generates a JSON Schema for this type.

fn is_referenceable() -> bool

Whether JSON Schemas generated for this type should be re-used where possible using the $ref keyword.

impl OpenApiResponderInner for HttpApiProblem

fn responses(gen: &mut OpenApiGenerator) -> Result<Responses>

Create the responses type, which is a list of responses that can be rendered in openapi.json format.

impl PartialEq for HttpApiProblem

fn eq(&self, other: &HttpApiProblem) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'r> Responder<'r, 'static> for HttpApiProblem

fn respond_to(self, _request: &Request<'_>) -> Result<'static>

Returns Ok if a Response could be generated successfully. Otherwise, returns an Err with a failing Status.

impl Serialize for HttpApiProblem

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl Eq for HttpApiProblem

impl Reject for HttpApiProblem

impl StructuralEq for HttpApiProblem

impl StructuralPartialEq for HttpApiProblem