FeignHttp is a declarative HTTP client. Based on rust macros.
FeignHttp mark macros on asynchronous functions, you need a runtime for support async/await. You can use async-std or tokio.
async-std:
toml
[dependencies]
async-std = { version = "1", features = ["attributes", "tokio1"] }
The feature tokio1 is need when use reqwest as the HTTP backend.
tokio:
toml
[dependencies]
tokio = { version = "1", features = ["full"] }
Add feignhttp in your Cargo.toml and use default feature:
toml
feignhttp = { version = "0.3" }
Then add the following code:
```rust use feignhttp::get;
async fn github() -> feignhttp::Result
async fn main() -> Result<(), Box
Ok(())
} ```
The get attribute macro specifies get request, feignhttp::Result<String> specifies the return result.
It will send get request to https://api.github.com and receive a plain text body.
Using non-default HTTP backend:
toml
feignhttp = { version = "0.2", default-features = false, features = ["isahc-client"] }
The default-features = false option disable default reqwest.
For a post request, you should use the post attribute macro to specify request method and use a body attribute to specify
a request body.
```rust use feignhttp::post;
async fn post_data(#[body] text: String) -> feignhttp::Result
The #[body] mark a request body. Function parameter text is a String type, it will put in the request body as plain text.
String and &str will be put as plain text into the request body.
Using path to specify path value:
```rust use feignhttp::get;
async fn repository(
#[path] owner: &str,
#[path] repo: String,
) -> feignhttp::Result
async fn main() -> Result<(), Box
Ok(())
} ```
dxx will replace {owner} and feignhttp will replace {repo} , the url to be send will be
https://api.github.com/repos/dxx/feignhttp. You can specify a path name like #[path("owner")].
Using query to specify query parameter:
```rust use feignhttp::get;
async fn contributors(
#[path("owner")] user: &str,
#[path] repo: &str,
#[query] page: u32,
) -> feignhttp::Result
async fn main() -> Result<(), Box
Ok(())
} ```
The page parameter will as query parameter in the url. An url which will be send is https://api.github.com/repos/dxx/feignhttp?page=1.
Note: A function parameter without
queryattribute will as a query parameter by default.
Using header to specify request header:
```rust use feignhttp::get;
async fn commits(
#[header] accept: &str,
#[path] owner: &str,
#[path] repo: &str,
#[query] page: u32,
#[query] per_page: u32,
) -> feignhttp::Result
async fn main() -> Result<(), Box
Ok(())
} ```
A header accept:application/vnd.github.v3+json will be send.
Using form to specify form parameter:
```rust use feignhttp::post;
async fn post_user(
#[form] id: i32,
#[form] name: &str,
) -> feignhttp::Result
async fn main() -> Result<(), Box
Ok(())
} ```
See here for more examples.
We can use constant to maintain all urls of request:
```rust use feignhttp::get;
const GITHUB_URL: &str = "https://api.github.com";
async fn languages(
#[path] owner: &str,
#[path] repo: &str,
) -> feignhttp::Result
Url constant must be the first metadata in get attribute macro. You also can specify metadata key:
```rust
async fn languages(
#[path] owner: &str,
#[path] repo: &str,
) -> feignhttp::Result
Serde is a framework for serializing and deserializing Rust data structures. When use json, you should add serde in Cargo.toml:
toml
[dependencies]
serde = { version = "1", features = ["derive"] }
Here is an example of getting json:
```rust use feignhttp::get; use serde::Deserialize;
// Deserialize: Specifies deserialization
struct IssueItem {
pub id: u32,
pub number: u32,
pub title: String,
pub url: String,
pub repository_url: String,
pub state: String,
pub body: Option
const GITHUB_URL: &str = "https://api.github.com";
async fn issues(
#[path] owner: &str,
#[path] repo: &str,
page: u32,
per_page: u32,
) -> feignhttp::Result
async fn main() -> Result<(), Box
Ok(())
} ```
This issues function return Vec<IssueItem>, it is deserialized according to the content of the response.
Send a json request:
```rust use feignhttp::post; use serde::Serialize;
struct User { id: i32, name: String, }
async fn post_user(#[body] user: User) -> feignhttp::Result
async fn main() -> Result<(), Box
Ok(())
} ```
See here for a complete example.
Structure is a good way to manage requests. Define a structure and then define a large number of request methods：
```rust use feignhttp::feign;
const GITHUB_URL: &str = "https://api.github.com";
struct Github;
impl Github {
#[get]
async fn home() -> feignhttp::Result
#[get("/repos/{owner}/{repo}")]
async fn repository(
#[path] owner: &str,
#[path] repo: &str,
) -> feignhttp::Result<String> {}
// ...
// Structure method still send request
#[get(path = "/repos/{owner}/{repo}/languages")]
async fn languages(
&self,
#[path] owner: &str,
#[path] repo: &str,
) -> feignhttp::Result<String> {}
} ```
See here for a complete example.
If you need to configure the timeout, use connect_timeout and timeout to specify connect timeout and read timeout.
Connect timeout:
```rust
async fn connect_timeout() -> feignhttp::Result
Read timeout:
```rust
async fn timeout() -> feignhttp::Result
FeignHttp is provided under the MIT license. See LICENSE.