# parse_link_header
[](https://github.com/g1eny0ung/parse_link_header/actions/workflows/rust.yml)
[](https://codecov.io/gh/g1eny0ung/parse_link_header)
A library for parsing HTTP Link header.
- [How to use](#how-to-use)
- [Note for version 0.1.x](#note-for-version-01x)
- [Example](#example)
- [parse_with_rel](#parse_with_rel)
- [Feature: `url`](#feature-url)
- [How to contribute](#how-to-contribute)
- [License](#license)
## How to use
### Note for version 0.1.x
The version 0.1 can't correctly handle the `relative ref` which described in
<https://tools.ietf.org/html/rfc3986#section-4.1>
The parsed value of version 0.1 refers to the return value of
<https://github.com/thlorenz/parse-link-header>, which is a `HashMap` with the
same structure.
**So if you want to parse `relative ref`, please use version `>=0.2`.**
**Or if you don't care about `relative ref` and want a simple `HashMap<String, HashMap<String, String>>` result, you can use version `0.1`.**
### Example
In your `Cargo.toml`, add:
```toml
[dependencies]
parse_link_header = "0.4"
```
Then:
```rust
let link_header = r#"<https://api.github.com/repositories/41986369/contributors?page=2>; rel="next", <https://api.github.com/repositories/41986369/contributors?page=14>; rel="last""#;
let res = parse_link_header::parse(link_header);
assert!(res.is_ok());
let val = res.unwrap();
assert_eq!(val.len(), 2);
assert_eq!(val.get(&Some("next".to_string())).unwrap().raw_uri, "https://api.github.com/repositories/41986369/contributors?page=2");
assert_eq!(val.get(&Some("last".to_string())).unwrap().raw_uri, "https://api.github.com/repositories/41986369/contributors?page=14");
```
The parsed value is a `Result<HashMap<Option<Rel>, Link>, Error>` (aka a
[`LinkMap`](https://docs.rs/parse_link_header/latest/parse_link_header/type.LinkMap.html)), which `Rel` and `Link` is:
```rust
use std::collections::HashMap;
#[cfg(not(feature = "url"))]
use http::Uri;
#[cfg(feature = "url")]
use url::Url as Uri;
#[derive(Debug, PartialEq)]
pub struct Link {
pub uri: Uri,
pub raw_uri: String,
pub queries: HashMap<String, String>,
pub params: HashMap<String, String>,
}
type Rel = String;
```
Note that according to <https://tools.ietf.org/html/rfc8288#section-3.3> (October 2017),
**the rel parameter must be present**. That's why the key of `HashMap<Option<Rel>, Link>` is `Option<Rel>`.
So if you find that the key is `None`, check if you specified the `rel` type.
## parse_with_rel
> Version >= 0.3.0
Alternatively, use the `parse_with_rel()` function to get a `HashMap<String, Link>` (aka a [`RelLinkMap`](https://docs.rs/parse_link_header/latest/parse_link_header/type.RelLinkMap.html)), as in:
```rust
let link_header = r#"<https://api.github.com/repositories/41986369/contributors?page=2>; rel="next", <https://api.github.com/repositories/41986369/contributors?page=14>; rel="last""#;
let res = parse_link_header::parse_with_rel(link_header);
assert!(res.is_ok());
let val = res.unwrap();
assert_eq!(val.len(), 2);
assert_eq!(val.get("next").unwrap().raw_uri, "https://api.github.com/repositories/41986369/contributors?page=2");
assert_eq!(val.get("last").unwrap().raw_uri, "https://api.github.com/repositories/41986369/contributors?page=14");
```
You can use this function if you ensure that the `rel` parameter is present in the header.
## Feature: `url`
> Version >= 0.3.0
If the `url` feature is enabled, the `uri` field in struct [`parse_link_header::Link`](https://docs.rs/parse_link_header/latest/parse_link_header/struct.Link.html) will be
of type `url::Url` from the [url crate](https://crates.io/crates/url), rather than the `http::uri::Uri` it normally is.
This allows integration with other libraries that use the url crate, such as [reqwest](https://crates.io/crates/reqwest).
**NOTE:** This implicitly disabled support for relative refs, as URLs do not support relative refs (whereas URIs do).
## How to contribute
Pull a request or open an issue to describe your changes or problems.
## License
MIT @ g1eny0ung