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>,
    // some fields omitted
}

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",
}

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.

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);

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, String> 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.

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.

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

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<(), String> where
    V: Serialize,
    K: Into<String>, 

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

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_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_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.

pub 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.

pub fn backtrace(&self) -> Option<&Backtrace>

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

Returns a stack backtrace, if available, of where this error occurred.

pub fn description(&self) -> &str

👎 Deprecated since 1.42.0:

use the Display impl or to_string()

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

👎 Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

impl From<ApiError> for HttpApiProblem

fn from(error: ApiError) -> Self

Performs the conversion.

impl From<StatusCode> for HttpApiProblem

fn from(status: StatusCode) -> HttpApiProblem

Performs the conversion.

impl Reject for HttpApiProblem

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.