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
usenew Uri("http://baseUrlOfService").AppendPathSegment("subPath");
- Trailing slashes are handled…
http://baseUrlOfService/subPath
can also be done usingnew Uri("http://baseUrlOfService/").AppendPathSegment("subPath");
- To get
- Adding query string parameters
- To get
http://url?myParam=aValue
usenew 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 usingnew Uri("http://url").AppendQueryStringParam("q", "hello").AppendPathSegment("path");
although this is not really recommended as it doesn’t read great…
- To get
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>();
- Void Return Usage:
- 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");
- GET –
- 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();
- Add a body to the request:
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();