Skip to content

Commit c32c8eb

Browse files
Adrian ColeAdrian Cole
authored andcommitted
Documents how to send POST bodies
@brianm noticed we were missing docs on how to use POST.
1 parent 1705c15 commit c32c8eb

1 file changed

Lines changed: 54 additions & 7 deletions

File tree

‎README.md‎

Lines changed: 54 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -175,16 +175,63 @@ GitHub github = Feign.builder()
175175
```
176176

177177
### Encoders
178-
`Feign.builder()` allows you to specify additional configuration such as how to encode a request.
178+
The simplest way to send a request body to a server is to define a `POST` method that has a `String` or `byte[]` parameter without any annotations on it. You will likely need to add a `Content-Type` header.
179179

180-
If any methods in your interface use parameters types besides `String` or `byte[]`, you'll need to configure a non-default `Encoder`.
180+
```java
181+
interface LoginClient {
182+
@RequestLine("POST /")
183+
@Headers("Content-Type: application/json")
184+
void login(String content);
185+
}
186+
...
187+
client.login("{\"user_name\": \"denominator\", \"password\": \"secret\"}");
188+
```
181189

182-
Here's how to configure JSON encoding (using the `feign-gson` extension):
190+
By configuring an `Encoder`, you can send a type-safe request body. Here's an example using the `feign-gson` extension:
183191

184192
```java
185-
GitHub github = Feign.builder()
186-
.encoder(new GsonEncoder())
187-
.target(GitHub.class, "https://api.github.com");
193+
static class Credentials {
194+
final String user_name;
195+
final String password;
196+
197+
Credentials(String user_name, String password) {
198+
this.user_name = user_name;
199+
this.password = password;
200+
}
201+
}
202+
203+
interface LoginClient {
204+
@RequestLine("POST /")
205+
void login(Credentials creds);
206+
}
207+
...
208+
LoginClient client = Feign.builder()
209+
.encoder(new GsonEncoder())
210+
.target(LoginClient.class, "https://foo.com");
211+
212+
client.login(new Credentials("denominator", "secret"));
213+
```
214+
215+
### @Body templates
216+
The `@Body` annotation indicates a template to expand using parameters annotated with `@Param`. You will likely need to add a `Content-Type` header.
217+
218+
```java
219+
interface LoginClient {
220+
221+
@RequestLine("POST /")
222+
@Headers("Content-Type: application/xml")
223+
@Body("<login \"user_name\"=\"{user_name}\" \"password\"=\"{password}\"/>")
224+
void xml(@Param("user_name") String user, @Param("password") String password);
225+
226+
@RequestLine("POST /")
227+
@Headers("Content-Type: application/json")
228+
// json curly braces must be escaped!
229+
@Body("%7B\"user_name\": \"{user_name}\", \"password\": \"{password}\"%7D")
230+
void json(@Param("user_name") String user, @Param("password") String password);
231+
}
232+
...
233+
client.xml("denominator", "secret"); // <login "user_name"="denominator" "password"="secret"/>
234+
client.json("denominator", "secret"); // {"user_name": "denominator", "password": "secret"}
188235
```
189236

190237
### Advanced usage
@@ -228,7 +275,7 @@ Bank bank = Feign.builder()
228275
.target(Bank.class, "https://api.examplebank.com");
229276
```
230277

231-
#### Custom Parameter Expansion
278+
#### Custom @Param Expansion
232279
Parameters annotated with `Param` expand based on their `toString`. By
233280
specifying a custom `Param.Expander`, users can control this behavior,
234281
for example formatting dates.

0 commit comments

Comments
 (0)