# Struct http::request::Request [−] [src]

    pub struct Request<T> { /* fields omitted */ }

Represents an HTTP request.

An HTTP request consists of a head and a potentially optional body. The body component is generic, enabling arbitrary types to represent the HTTP body. For example, the body could be `Vec<u8>`, a `Stream` of byte chunks, or a value that has been deserialized.

# Examples

Creating a `Request` to send

    use http::{Request, Response};

    let mut request = Request::builder()
        .uri("https://www.rust-lang.org/")
        .header("User-Agent", "my-awesome-agent/1.0");

    if needs_awesome_header() {
        request = request.header("Awesome", "yes");
    }

    let response = send(request.body(()).unwrap());

    fn send(req: Request<()>) -> Response<()> {
        // ...
    }

Inspecting a request to see what was sent.

    use http::{Request, Response, StatusCode};

    fn respond_to(req: Request<()>) -> http::Result<Response<()>> {
        if req.uri() != "/awesome-url" {
            return Response::builder()
                .status(StatusCode::NOT_FOUND)
                .body(())
        }

        let has_awesome_header = req.headers().contains_key("Awesome");
        let body = req.body();

        // ...
    }

Deserialize a request of bytes via json:

    use http::Request;
    use serde::de;

    fn deserialize<T>(req: Request<Vec<u8>>) -> serde_json::Result<Request<T>>
        where for<'de> T: de::Deserialize<'de>,
    {
        let (parts, body) = req.into_parts();
        let body = serde_json::from_slice(&body)?;
        Ok(Request::from_parts(parts, body))
    }

Or alternatively, serialize the body of a request to json

    use http::Request;
    use serde::ser;

    fn serialize<T>(req: Request<T>) -> serde_json::Result<Request<Vec<u8>>>
        where T: ser::Serialize,
    {
        let (parts, body) = req.into_parts();
        let body = serde_json::to_vec(&body)?;
        Ok(Request::from_parts(parts, body))
    }

## Implementations

### `impl Request<()>` [src]

#### `pub fn builder() -> Builder` [src]

Creates a new builder-style object to manufacture a `Request`

This method returns an instance of `Builder` which can be used to create a `Request`.

# Examples

    let request = Request::builder()
        .method("GET")
        .uri("https://www.rust-lang.org/")
        .header("X-Custom-Foo", "Bar")
        .body(())
        .unwrap();

#### `pub fn get<T>(uri: T) -> Builder where
Uri: TryFrom<T>,
<Uri as TryFrom<T>>::Error: Into<Error>,` [src]

Creates a new `Builder` initialized with a GET method and the given URI.

This method returns an instance of `Builder` which can be used to create a `Request`.

# Example

    let request = Request::get("https://www.rust-lang.org/")
        .body(())
        .unwrap();

#### `pub fn put<T>(uri: T) -> Builder where
Uri: TryFrom<T>,
<Uri as TryFrom<T>>::Error: Into<Error>,` [src]

Creates a new `Builder` initialized with a PUT method and the given URI.

This method returns an instance of `Builder` which can be used to create a `Request`.

# Example

    let request = Request::put("https://www.rust-lang.org/")
        .body(())
        .unwrap();

#### `pub fn post<T>(uri: T) -> Builder where
Uri: TryFrom<T>,
<Uri as TryFrom<T>>::Error: Into<Error>,` [src]

Creates a new `Builder` initialized with a POST method and the given URI.

This method returns an instance of `Builder` which can be used to create a `Request`.

# Example

    let request = Request::post("https://www.rust-lang.org/")
        .body(())
        .unwrap();

#### `pub fn delete<T>(uri: T) -> Builder where
Uri: TryFrom<T>,
<Uri as TryFrom<T>>::Error: Into<Error>,` [src]

Creates a new `Builder` initialized with a DELETE method and the given URI.

This method returns an instance of `Builder` which can be used to create a `Request`.

# Example

    let request = Request::delete("https://www.rust-lang.org/")
        .body(())
        .unwrap();

#### `pub fn options<T>(uri: T) -> Builder where
Uri: TryFrom<T>,
<Uri as TryFrom<T>>::Error: Into<Error>,` [src]

Creates a new `Builder` initialized with an OPTIONS method and the given URI.

This method returns an instance of `Builder` which can be used to create a `Request`.

# Example

    let request = Request::options("https://www.rust-lang.org/")
        .body(())
        .unwrap();

#### `pub fn head<T>(uri: T) -> Builder where
Uri: TryFrom<T>,
<Uri as TryFrom<T>>::Error: Into<Error>,` [src]

Creates a new `Builder` initialized with a HEAD method and the given URI.

This method returns an instance of `Builder` which can be used to create a `Request`.

# Example

    let request = Request::head("https://www.rust-lang.org/")
        .body(())
        .unwrap();

#### `pub fn connect<T>(uri: T) -> Builder where
Uri: TryFrom<T>,
<Uri as TryFrom<T>>::Error: Into<Error>,` [src]

Creates a new `Builder` initialized with a CONNECT method and the given URI.

This method returns an instance of `Builder` which can be used to create a `Request`.

# Example

    let request = Request::connect("https://www.rust-lang.org/")
        .body(())
        .unwrap();

#### `pub fn patch<T>(uri: T) -> Builder where
Uri: TryFrom<T>,
<Uri as TryFrom<T>>::Error: Into<Error>,` [src]

Creates a new `Builder` initialized with a PATCH method and the given URI.

This method returns an instance of `Builder` which can be used to create a `Request`.

# Example

    let request = Request::patch("https://www.rust-lang.org/")
        .body(())
        .unwrap();

#### `pub fn trace<T>(uri: T) -> Builder where
Uri: TryFrom<T>,
<Uri as TryFrom<T>>::Error: Into<Error>,` [src]

Creates a new `Builder` initialized with a TRACE method and the given URI.

This method returns an instance of `Builder` which can be used to create a `Request`.

# Example

    let request = Request::trace("https://www.rust-lang.org/")
        .body(())
        .unwrap();

### `impl<T> Request<T>` [src]

#### `pub fn new(body: T) -> Request<T>` [src]

Creates a new blank `Request` with the body

The component parts of this request will be set to their default, e.g. the GET method, no headers, etc.

# Examples

    let request = Request::new("hello world");

    assert_eq!(*request.method(), Method::GET);
    assert_eq!(*request.body(), "hello world");

#### `pub fn from_parts(parts: Parts, body: T) -> Request<T>` [src]

Creates a new `Request` with the given components parts and body.

# Examples

    let request = Request::new("hello world");
    let (mut parts, body) = request.into_parts();
    parts.method = Method::POST;

    let request = Request::from_parts(parts, body);

#### `pub fn method(&self) -> &Method` [src]

Returns a reference to the associated HTTP method.

# Examples

    let request: Request<()> = Request::default();
    assert_eq!(*request.method(), Method::GET);

#### `pub fn method_mut(&mut self) -> &mut Method` [src]

Returns a mutable reference to the associated HTTP method.

# Examples

    let mut request: Request<()> = Request::default();
    *request.method_mut() = Method::PUT;
    assert_eq!(*request.method(), Method::PUT);

#### `pub fn uri(&self) -> &Uri` [src]

Returns a reference to the associated URI.

# Examples

    let request: Request<()> = Request::default();
    assert_eq!(*request.uri(), *"/");

#### `pub fn uri_mut(&mut self) -> &mut Uri` [src]

Returns a mutable reference to the associated URI.

# Examples

    let mut request: Request<()> = Request::default();
    *request.uri_mut() = "/hello".parse().unwrap();
    assert_eq!(*request.uri(), *"/hello");

#### `pub fn version(&self) -> Version` [src]

Returns the associated version.

# Examples

    let request: Request<()> = Request::default();
    assert_eq!(request.version(), Version::HTTP_11);

#### `pub fn version_mut(&mut self) -> &mut Version` [src]

Returns a mutable reference to the associated version.

# Examples

    let mut request: Request<()> = Request::default();
    *request.version_mut() = Version::HTTP_2;
    assert_eq!(request.version(), Version::HTTP_2);

#### `pub fn headers(&self) -> &HeaderMap<HeaderValue>` [src]

Returns a reference to the associated header field map.

# Examples

    let request: Request<()> = Request::default();
    assert!(request.headers().is_empty());

#### `pub fn headers_mut(&mut self) -> &mut HeaderMap<HeaderValue>` [src]

Returns a mutable reference to the associated header field map.

# Examples

    let mut request: Request<()> = Request::default();
    request.headers_mut().insert(HOST, HeaderValue::from_static("world"));
    assert!(!request.headers().is_empty());

#### `pub fn extensions(&self) -> &Extensions` [src]

Returns a reference to the associated extensions.

# Examples

    let request: Request<()> = Request::default();
    assert!(request.extensions().get::<i32>().is_none());

#### `pub fn extensions_mut(&mut self) -> &mut Extensions` [src]

Returns a mutable reference to the associated extensions.

# Examples

    let mut request: Request<()> = Request::default();
    request.extensions_mut().insert("hello");
    assert_eq!(request.extensions().get(), Some(&"hello"));

#### `pub fn body(&self) -> &T` [src]

Returns a reference to the associated HTTP body.

# Examples

    let request: Request<String> = Request::default();
    assert!(request.body().is_empty());

#### `pub fn body_mut(&mut self) -> &mut T` [src]

Returns a mutable reference to the associated HTTP body.

# Examples

    let mut request: Request<String> = Request::default();
    request.body_mut().push_str("hello world");
    assert!(!request.body().is_empty());

#### `pub fn into_body(self) -> T` [src]

Consumes the request, returning just the body.

# Examples

    let request = Request::new(10);
    let body = request.into_body();
    assert_eq!(body, 10);

#### `pub fn into_parts(self) -> (Parts, T)` [src]

Consumes the request returning the head and body parts.

# Examples

    let request = Request::new(());
    let (parts, body) = request.into_parts();
    assert_eq!(parts.method, Method::GET);

#### `pub fn map<F, U>(self, f: F) -> Request<U> where
F: FnOnce(T) -> U,` [src]

Consumes the request returning a new request with body mapped to the return type of the passed in function.

# Examples

    let request = Request::builder().body("some string").unwrap();
    let mapped_request: Request<&[u8]> = request.map(|b| {
      assert_eq!(b, "some string");
      b.as_bytes()
    });
    assert_eq!(mapped_request.body(), &"some string".as_bytes());

## Trait Implementations

### `impl<T: Debug> Debug for Request<T>` [src]

#### `fn fmt(&self, f: &mut Formatter<'_>) -> Result` [src]

Formats the value using the given formatter. Read more

### `impl<T: Default> Default for Request<T>` [src]

#### `fn default() -> Request<T>` [src]

Returns the “default value” for a type. Read more

## Auto Trait Implementations

### `impl<T> !RefUnwindSafe for Request<T>`

### `impl<T> Send for Request<T> where
T: Send,`

### `impl<T> Sync for Request<T> where
T: Sync,`

### `impl<T> Unpin for Request<T> where
T: Unpin,`

### `impl<T> !UnwindSafe for Request<T>`

## Blanket Implementations

### `impl<T> Any for T where
T: 'static + ?Sized,` [src]

#### `pub fn type_id(&self) -> TypeId` [src]

Gets the `TypeId` of `self`. Read more

### `impl<T> Borrow<T> for T where
T: ?Sized,` [src]

#### `pub fn borrow(&self) -> &T` [src]

Immutably borrows from an owned value. Read more

### `impl<T> BorrowMut<T> for T where
T: ?Sized,` [src]

#### `pub fn borrow_mut(&mut self) -> &mut T` [src]

Mutably borrows from an owned value. Read more

### `impl<T> From<T> for T` [src]

#### `pub fn from(t: T) -> T` [src]

Performs the conversion.

### `impl<T, U> Into<U> for T where
U: From<T>,` [src]

#### `pub fn into(self) -> U` [src]

Performs the conversion.

### `impl<T, U> TryFrom<U> for T where
U: Into<T>,` [src]

#### `type Error = Infallible`

The type returned in the event of a conversion error.

#### `pub fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>` [src]

Performs the conversion.

### `impl<T, U> TryInto<U> for T where
U: TryFrom<T>,` [src]

#### `type Error = <U as TryFrom<T>>::Error`

The type returned in the event of a conversion error.

#### `pub fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>` [src]

Performs the conversion.