Basics pt. 2

So you're up and running now know the very basics on how to define an interface to create HTTP GET-requests. You'd soon want to POST something, wouldn't you?

Post

So. Continuing on the Api provided over at http://jsonplaceholder.typicode.com/, extend on the interface you already created and define a signature like this

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

Using this method could look something like this

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

var newPost = new Post
{
    UserId = 1,
    Title = "Red Cup",
    Body = "Red Cup Starts you up!"
};

await api.CreatePost(newPost);

// -> HTTP POST http://jsonplaceholder.typicode.com/posts
// {
//     userId: 1,
//     title: 'Red Cup',
//     body: 'Red Cup Starts you up!' 
// }
 

As you can see, the parameter marked with the [Content]-attribute is serialized to a json-object and sent as body with the HTTP Request.

Put & Delete

HTTP Put and HTTP Delete are also supported through their corresponding [Put]- and [Delete]-attributes.

HttpResponseMessage

Sometimes you don't want the HttpResponse-content to be parsed and deserialized to an object in such an automatic way as Web Anchor does for you. Sometimes you just want your normal HTTP code 200 or 404. This is easily achieved by replacing your Task<Post> with Task<HttpResponseMessage>. No parsing will be done, and the HttpResponseMessage is returned to you untouched.

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

This is a powerful feature that gives you full control on how to react on the response.

Some people want the best of two worlds. Watch this to see how you could extend web anchors default behaviour to make use of Web Anchors default body deserialization along with retrieving extra information from the HttpResponseMessage.

Exceptions

If you are using the Task<HttpResponseMessage> variation, a 404 or any other non-successful calls would still just return a HttpResponseMessage.

However, if you have defined api return types like Task<Post> above, any non-successful calls will throw an ApiException which contains a reference to the HttpResponseMessage for you to inspect.

Injectable HttpClient and IDisposable

When creating an api like Api.For<ITypicode>(), a HttpClient is created backstage for you. This HttpClient will never be disposed, which could be OK. However, if you want to make sure it is disposed when you're done with your api, you can let your api implement the IDisposable-interface and then use it with the using-statement.

[BaseLocation("posts")]
public interface ITypicodeApi : IDisposable
{
    [Get("")]
    Task<List<Post>> GetPosts();
}

using(var api = Api.For<ITypicodeApi>("http://jsonplaceholder.typicode.com"))
{
    var result = await api.GetPosts();
}

Now the backstage HttpClient will disposed when your api is disposed.

Sometimes, you want to use your own HttpClient, because you want to access some of its extension points or be in full control of how it is created and disposed. You can do that! Just pass it in, but be aware that you must dispose it yourself.

Api.For<ITypicodeApi>(someHttpClient)