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.

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

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_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 backtrace(&self) -> Option<&Backtrace>

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

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

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

impl From<ApiError> for HttpApiProblem

fn from(error: ApiError) -> Self

Performs the conversion.

impl From<HttpApiProblem> for Response<Body>

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

Performs the conversion.

impl From<HttpApiProblem> for HttpResponse

fn from(problem: HttpApiProblem) -> HttpResponse

Performs the conversion.

impl From<HttpApiProblem> for Response<'static>

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

Performs the conversion.

impl From<HttpApiProblem> for Response

fn from(problem: HttpApiProblem) -> Response

Performs the conversion.

impl From<HttpApiProblem> for Response

fn from(problem: HttpApiProblem) -> Response

Performs the conversion.

impl From<StatusCode> for HttpApiProblem

fn from(status: StatusCode) -> HttpApiProblem

Performs the conversion.

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 Reject for HttpApiProblem