ApiSettings

ApiSettings

There is another way to modify your api on a higher level, by passing an implementation of IApiSettings to the Api.For-method or by passing an action to modify the default settings. Here are two examples on how to set the default content-serializer to a serializer that transforms content to FormUrlEncoded content.

Subclassing DefaultApiSettings

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

...

public class MySettings : DefaultApiSettings
{
    public MySettings()
    {
        Request.ContentSerializer = new FormUrlEncodedSerializer();
    }
}

Configuring DefaultApiSettings

var api = Api.For<ITypicodeApi>("http://jsonplaceholder.typicode.com", x => 
{
    x.Request.ContentSerializer = new FormUrlEncodedSerializer();
});

Settings in ApiSettings are divided into Request and Response and typically govern details of details of creating the HttpRequestMessage and parsing the HttpResonseMessage. Let's have a look at the available options.

Request

InsertMissingSlashBetweenBaseLocationAndVerbAttributeUrl

Defaults to true. If true, forward slashes will be inserted between the url segment of a [BaseLocation("api")] and a [HttpGet("customers")] creating an url like api/customers. If false, forward slashes must be appended manually at the end of "api" or beginning of "customers" to get the same result, like [BaseLocation("api")] and [HttpGet("/customers")]. Otherwise the resulting url would look like apicustomers

EncodeUrlSegmentSeparatorsInUrlSegmentSubstitutions

Defaults to false. When false a baselocation like [BaseLocation("api/v2")] will create an url like api/v2. If true, it would become api%2Fv2 (the slash is now Url-encoded).

ParameterValueFormatter

Before any parameter object is inserted into the url or used as header or query-parameter, it must be ToString()-ed. The default implementation DefaultParameterValueFormatter will format the value with Invariant Culture if it is IFormattable. Otherwise, normal ToString() will be applied. (this string will later be urlencoded if needed, you don't have to worry about that).

You can change the behaviour of the DefaultParameterValueFormatter by turning it off or using another culture, or you can replace it with your own by implementing IParameterValueFormatter. Here is an example on how you change culture of the existing one.

public class MySettings : DefaultApiSettings
{
    public MySettings()
    {
        ((DefaultParameterValueFormatter)Request.ParameterValueFormatter).CultureInfo = CultureInfo.GetCultureInfo("sv-SE");
    }
}

QueryParameterListStrategy

Defaults to NormalQueryParamaterListStrategy. This setting defined how parameters that are lists are handled. 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 by implementing your own IQueryParamaterListStrategy. There is another prepacked implementation of this interface called DelimitedQueryParamaterListStrategy which would generate an url like

HTTP GET http://myapi.com//customer?country=SE,EN

ContentSerializer

Defaults to new JsonContentSerializer(new Newtonsoft.Json.JsonSerializer()). The content serializer is responsible for turning your [Content]-objects into body content.

ParameterListTransformers

ParameterListTransformers has been discussed already in the previous section (Parameter attributes). Worth mentioning here is that the list of parameterlisttransformers by default consist of two transformers.

The first one is the ParameterCreatorTransformer which starts with an empty list of parameters and returns a new list of parameters based upon parameters passed to your method. At this time, a parameter will get a parametertype of Content if it has the [Content]-attribute, Header if it has the [Header]-attribute, Route if its name matches any replacable section in the url-template, and otherwise Query. You can change their type later through attributes, but webanchor will NOT change their types automatically again. Say if you change a query-parameter's name so that it suddenly matches a route-segment-substitution, Web Anchor will not change the parameter's type to Route. The second parameterlisttransformer is the AttributesTransformer which enables parameter attribute transforming. See the section about Alias or the Prefix-example in this section: Parameter attributes.

Response

This part is subject to change in near future so I won't bother writing about it's current state.