ict.ken.be

Introduction to the ASP.NET WebApi
Jon Flanders

• Service layer for HTML5, mobile applications, ...
• REST : Representational State Transfer (Roy Fielding)
• Full rest -> Level4 service

RouteTable.Routes.MapHttpRoute(
"InstructorRoute",
"{controller}/{id},
new { id = RouteParameter.Optional }
);
 
ApiController
[Authorize(users="jon")]
public string Get() //returns all
{
  return this.Request.GetUserPrinciple().Identity.Name;	
}
public HttpResponseMessage<Instructor> Get(int id)
{
   var instructor = (from ...)
   if (null == instructor)
   {
      //return 404
      var notfoundMessage = new HttpRequestMessage<Instructor>(HttpStatusCode.NotFound);
      return notfoundMessage;		       
   }
   var newMessage = new HttpRequestMessage<Instructor>(instructor);
   return newMessage;
}
public HttpResponseMessage<Instructor> Post(Instructor instructor)
{ 
   //create and insert and return 201 
   var newMessage = new HttpRequestMessage<Instructor>(instructor, HttpStatusCode.created);
   newMessage.Headers.Location = 
      new Uri(Request.RequestUri, "/instructors/" + instructor.ID.ToString());
}
public Instructor Put(Instructor instructor)
{ update }
public Instructor Delete(int id)
{ remove }
System.Net.Http
System.Net.Http.Formatting
System.Web.Http
System.Web.Http.Common
System.Web.Http.WebHost
System.Web.Http.SelfHost
System.Web.Http.Data
System.Web.Http.Data.EntityFramework
System.Web.Http.Data.Helpers 

• ModelBinder for Body, header, querystring
• MediaTypeFormatters
• Validation via attributes
• HttpRequestMessage and HttpResponseMessage
• Content negotiation (xml or json)
• Customize file extension or querystring
• Fidler : Post with Content-Type:application/json
• http://odata.org with IQueryable
• HttpConfiguration class
• GlobalConfiguration.Configuration
• DependencyResolver 

Uniform interface of REST

• Start with URI, add well-known HTTP verbs
• Get: cacheble, safe, always same effect (idempotent)
• Post: create new resource, unsafe, non-cached 
• Put: update, idempotent
• Delete: remove, idempotent
• You can specify multiple verbs to one method

ApiController: IHttpController, IDisposable
{
   Configuration, ControllerContext, ModelState, Request, Url, Task<HttpResponseMessage>, ExecuteAsync, Initialize
}
 
HttpRequestMessage:IDisposable
{
  Content, Headers, Method, Properties, RequestUri, Version, Displose
}
 
HttpResponseMessage:IDisposable
{
  Content, Headers, IsSuccessStatusCode, ReasonPhrase, RequestMesage, StatusCode, Version, Dispose, EnsureSuccessStatusCode
}
$.ajax({
url: '/api/foo/id',
success: function (data) {},
statusCode: { 
	404: function() {} 
	}
}); 

HttpClient

• HttpWebRequest, WebClient

var c = new HttpClient();
c.GetAsync(uri).ContinueWith((t) =>
{
  HttpResponseMessage response = null;
  response = t.Result;
  response.EnsureSuccessStatusCode();
  response.Content.ReadAsAsync<JsonObject>().ContinueWith(readTask) =>
{
  ProcessJson(readTask.Result);
}
});

• http://search.twitter.com/search.json?q=fun
• PostAsync, PutAsync
• ObjectContent<T> for Json or XML
• StreamContent for raw data
• MultipartContent and MultiPartFormContent
• ByteArrayContent, FormUrlEncodedContent, StringContent
• UploadVideoClient (HttpClient)
• Dealing with headers
• Dealing with cookies 

Per-request headers

var pcontent = new HttpRequestMessage<Person>().CreateContent<Person>(new Person());
pcontent.Headers.ContentType = new MediaTypeHeaderValue("application/json");
pcontent.Headers.Add("Accept","application/xml");

• public class HttpClientHandler : HttpMessageHandler
• Derive from DelegatingHandler
• The HttpClient does not send a UserAgent by default
• client.DefaultRequestHeaders.Add("User-Agent","Jon's Cool Client");
• Token-based authorization can be accomplished by a custom HttpClientHandler

Self-Hosting Example

• Create a HttpConfiguration (eg. HttpSelfHostConfiguration)
• Create your HttpServer (eg. HttpSelfHostServer)
• Start listening: HttpServer.OpenAsync();
• When using the first contructor overload, you end up with HttpControllerDispatcher as your HttpMessageHandler. It allows you to use the same ASP.NET routing and same convention or configuration settings as ApiController in ASP.Net Hosting.
• config.Routes.MapHttpRoute("DefaultRoute", "{controller}/{id}", new { id=Parameter.Optional });
• You can pass HttpServer to HttpClient, useful for self-hosting testing (all in memory)

var client = new HttpClient(server);
client.GetAsync(...).ContinueWith(
(t)=>{ var result = t.Result; result.Content.ReadAsStringAsync().ContinueWith(
(tr) => { Console.Write(rt.Result);})
;});

Security

• /account/jsonlogin endpoint with MVC4 projects
• Authentication_JSON_AppService.axd
• App gets cookie

• HttpClient/WebHttpRequest/WebClient understand Windows authentication

• AuthorizeAttribute with names or roles on individual actions (returns 401 if unauthorized)

Self-host

• HttpMessageHandler
• request.GetUserPrincipal().Identity.Name;
• HttpSelfHostConfiguration

protected override BindingParameterCollection OnConfigureBinding(HttpBinding httpBinding)
{
   httpBinding.Security.Mode = HttpBindingSecurity.TransportCredentials;
   httpBinding.Security.Transport.CredentialType=HttpClientCredentialType.Windows;	
   return base.OnConfigureBinding(httpBinding);	
} 

Asp.Net Hosting

• Global.asax.cs
• GlobalConfiguration.Configuration.IncludeErrorDetailPolicy = IncludeErrorDetailPolicy.Always;

Extensibility

• GlobalConfiguration.Configuration
• HttpConfiguration
• Filters, Formatters, MessageHandlers, Routes, ServiceResolver
• IncludeErrorDetailPolicy.Always / Never / LocalOnly

• JsonP
• Inject code that isn't in same domain as controller
• HttpResponseMessage<JsonPReturn> Get(int id, string callback)
• response.Content.Headers.ContentType = new MediaTypeHeaderValue("application/javascript");

<script>
function myCallback(obj) { document.getElementById('msg').innerText = obj.Data; }
</script>
<script src="http://server.com/api/controller/values/1?callback=myCallBack" />

• AuthorizeAttribute is an IFilter
• MyFilter : IActionFilter
• actionContext.ActionArguments 

• HttpServer, HttpClientHandler, HttpControllerDispatcher

public class MyMethodOverrideHandler : DelegatingHandler
{
   const string header = "X-HTTP-Method-Override";
   //override SendAsync 
   //and let clients put the real verb in this header
}

• Implement IDependencyResolver or Call SetResolver and pass in two delegates

Action Filter vs. Mesage Handler

• MessageHandler - before model binding - HTTP message level - eg. run an xml Schema validation
• ActionFilter - after model binding - Extending your controller - eg. run an object validation