Summary

Microsoft sort of recommends the HttpClient but I really just don’t like the interface on it.  I wanted something that sat on top of the .NET Uri object without having to new up anything else.  I also really like the fluent interface for work like this because its easy to see where the components came from rather than using format strings.  Naos.FluentUri was created to simply clean up the way I called RESTful services from .NET.

Project

Naos is an opensource project dedicated to providing infrastructure tools for free to aid in small companies having solid platforms to launch on, learn more at http://naosproject.com.

Source

The entire project is open sourced under the MIT license and available at: https://github.com/NaosFramework/Naos.FluentUri

Referencing

The entire implemenation is in a single file so it can be included without taking a dependency on the NuGet package if necessary preferred.

• Reference the NuGet package: http://www.nuget.org/packages/Naos.FluentUri.
  OR
• Include the single file in your project:https://raw.githubusercontent.com/NaosFramework/Naos.FluentUri/master/Naos.FluentUri/Naos.FluentUri.cs.

Use – Building up the URL

• Adding segments to the URL
  • To get http://baseUrlOfService/subPath use new Uri("http://baseUrlOfService").AppendPathSegment("subPath");
  • Trailing slashes are handled… http://baseUrlOfService/subPath can also be done using new Uri("http://baseUrlOfService/").AppendPathSegment("subPath");
• Adding query string parameters
  • To get http://url?myParam=aValue use new Uri(http://url).AppendQueryStringParam("myParam", "aValue");
  • Can also be done in batches by using .AppendQueryStringParams(/* IDictionary<string, string> */); or .AppendQueryStringParams(/* ICollection<KeyValuePair<string, string>> */);
  • Will work correctly out of order too… http://url/path?q=hello can be done using new Uri("http://url").AppendQueryStringParam("q", "hello").AppendPathSegment("path"); although this is not really recommended as it doesn’t read great…

Use – Calling the URL

• Void Return vs. Typed Return
  • Void Return Usage:
    • new Uri("http://api/Objects/42/Setting").Put();
  • Typed Return Usage:
    • MyObject returnedData = net Uri("http://api/Objects/42").Get<MyObject>();
• The four main verbs are currently supported as first class methods as well as a method to pass any verb as a string.
  • GET – new Uri("http://api/Objects/42").Get();
  • POST – new Uri("http://api/Objects/").Post();
  • PUT – new Uri("http://api/Objects/42/Setting").Put();
  • DELETE – new Uri("http://api/Objects/42").Delete();
  • “Custom Verb” – new Uri("http://api/Objects/42").CallWithVerb("Custom Verb");
• There are additional decorators for the call for standard operations.
  • Add a body to the request:
    • new Uri("http://api/Objects/").WithBody(new MyObject()).Post();
  • Add a cookie to the request:
    • // Cookie can also be of type HttpCookie...
    • var cookie = new Cookie(".ASPXAUTH", "[AuthCookieValue]") { Expires = DateTime.Now.AddDays(30) };
    • var obj = new Uri("http://api/Objects/42").WithCookie(cookie).Get<MyObject>();
  • Add headers to the request:
    • // Headers can also be of type WebHeaderCollection or NameValueCollection..
    • var headers = new[] { new KeyValuePair<string, string>("Auth-Token", "[AuthTokenValue]") };
    • var obj = new Uri("http://api/Objects/42").WithHeaders(headers).Get<MyObject>();
  • Update the timeout of the request:
    • var obj = new Uri("http://api/Objects/42").WithTimeout(TimeSpan.FromHours(1)).Get<MyObject>();
  • Save response headers using a lambda:
    • KeyValuePair<string, string>[] responseHeadersFromCall;
    • new Uri("http://api/Auth/Login").WithResponseHeaderSaveAction(responseHeaders => responseHeadersFromCall = responseHeaders).Post();

Use – Combined

C# Example of making and authentication call.

var loginResponse = new Uri("http://auth.services.com")
                                     .AppendPathSegment("login")
                                     .WithBody(loginRequest)
                                     .Post();

C# Example of updating a users’ zip code.

new Uri("http://user.services.com")
            .AppendPathSegment("user")
            .AppendPathSegment(user.Id)
            .AppendPathSegment("zipCode")
            .AppendPathSegment(user.ZipCode)
            .WithCookie(authCookieToAllowThis)
            .Put();