Building an HttpRequestMessage

Building an URL

There are 3 components that together make up the urls you want to call.

First, we have the part you give to the api when you create it.

Api.For<ITypicodeApi>("http://jsonplaceholder.typicode.com");

Second, we have the part you can give to your api through the BaseLocationAttribute. This is optional.

[BaseLocation("posts")]
public interface ITypicodeApi 

Third, we have the part you give to your methods through different HttpAttributes. These attributes also decide which http method will be used.

[Get("")]
Task<List<Post>> GetPosts();

[Get("{id}")]
Task<Post> GetPost(int id);

[Delete("{id}")]
Task<HttpResponseMessage> DeletePost(int id);

Substitutions

The BaseLocationAttribute and the HttpAttributes all accept paths that can contain placeholders. These placeholders are recognized by the surrounding {}-brackets. By default, these placeholders will be replaced with data from the parameters accepted by the method, if their names are matching.

[BaseLocation("api/{resource}")]
public interface IMyApi
{
    [Get("{id}")]
    Task<HttpResponseMessage> Get(string resource, int id);
}

Query parameters

Any parameters accepted by your method that does not match a placeholder in the url, will be appended to your url as a query parameter.

[Get("")]
Task<List<Post>> GetPosts(int? userId);

By the way... there is nothing stopping you from appending status query parameters directly in the HttpAttribute

[Get("?userId=2")]
Task<List<Post>> GetPosts();

Lists of query string parameters

By default, a query parameter with multiple values will be appended multiple times. Like this:

[Get("customer")]
Task<List<Customer>> GetCustomers(IEnumerable<string> country);

Api.For<MyApi>("http://myapi.com").GetCustomers(new[] { "SE", "EN" });

// -> HTTP GET http://myapi.com//customer?country=SE&country=EN

This can be changed in ApiSettings. See QueryParamaterListStrategy ApiSettings.

Body content

If there is a parameter accepted by your method that is attributed with the ContentAttribute, it will, by default, be serialized as JSON and sent as body content.

[Post("")]
Task<HttpResponseMessage> PostPost([Content]Post post);

Headers

Parameters attributed with the HeaderAttribute will become headers in the http request.

[Get("resource")]
Task<HttpResponseMessage> Get([Header] string authorization);

URL Encoding

One last thing. We URL encode anything that will eventually end up in the url. So if you pass in for example "Hello there" as a parameter for url segment substitution, Hello%20there is what will be put in the URL. This is fine most times, but we make one exception to this rule. In the example above, if you pass messages/sent as resource, we will not replace the / with %2F. If you wish to change this default behaviour, there is an option available in the IApiSettings. See EncodeUrlSegmentSeparatorsInUrlSegmentSubstitutions in ApiSettings.