Formatting Response Data

[danroth27]

ASP.NET MVC -> Models -> Formatting Response Data

• Format specific action results
  • JsonResult
  • ContentResult
    • string (will just return text)
  • Note: For non-trivial actions with multiple return types, prefer IActionResult
• Content negotiation
  • Define content negotiation - only happens if client specifies Accept header
  • Default format is JSON
  • IActionResult and Ok, BadRequest, Created, etc.
  • Return a POCO/Model Type (e.g. Foo, IEnumerable) (framework creates an ObjectResult for you - note null behavior returns 204 NoContent)
  • [Produces("application/json")] filter/attribute to restrict a controller or action (or global) to a particular content type
  • Note how browser accept headers are handled by default
• Configuring formatters
  • Xml Formatters package
  • config.InputFormatters, config.OutputFormatters in AddMvc (only outputformatters matter for conneg; input formatters would affect model binding)
  • builder.AddXmlSerializerFormatters (in formatters.xml package)
  • Use config.RespectBrowserAcceptHeader to support browser/wildcard content negotiation (if there is a wildcard, we will assume it's a browser)
  • Add camel casing to Json formatting using AddJsonOptions and SerializerSettings.ContractResolver = new CamelCasePropertyNamesContractResolver();
  • Special case for return string (will be text/plain unless TextPlainFormatter removed)
  • Special case for return null (as a POCO, not an IActionResult) (will be 204 NoContent unless HttpNoContentOutputFormatter is removed)
  • If you give us a header, we go through list of formatters, find one that can serialize the type to that format.
  • If no formatter can support the type being returned, then we will send a 406
    • If you ask for XML, but we don't have it, we will return JSON
  • If no accept header is given, we will go through the formatters in order and return the first one that can handle the object to be serialized
• Response format URL mappings
• Recommendations
  • Prefer IActionResult as your return type for data since it allows you to handle error states and different HTTP status codes

Note: Chrome's Accept header includes application/xml by default, so if you enable Xml and you find you're getting it when you hit your endpoint, that's probably why. If accept header has a wildcard (*), which browsers tend to do, then we will assume it's a browser and will send JSON. If you are not respecting browser headers, and there is a wildcard, we will just send JSON (we will act as if there was no Accept header).

Does ASP.NET Core respect q factors? http://stackoverflow.com/questions/8552927/what-is-q-0-5-in-accept-http-headers
YES. Link to RFC and just say we support the spec.
"Content negotiation allows clients to use the accept header to tell the server what formats they accept" (link accept header to RFC)

Reference: https://blogs.msdn.microsoft.com/webdev/2014/11/24/content-negotiation-in-mvc-6-or-how-can-i-just-write-json/

[ardalis]

@danroth27 I fleshed this out a bit. I'm not sure what "Response format URL mappings" means, though. Can you clarify?

[danroth27]

Response format mappings allow you to specify some part of the URI, like a format query string parameter, or a format specific file extension (.xml, .json) as a way to indicate that you would like a specific response format.

[ardalis]

https://github.com/aspnet/Mvc/blob/a78f77afde003c4a3fcf5dd7b6dc13dd9c85f825/test/Microsoft.AspNetCore.Mvc.FunctionalTests/FormatFilterSampleTest.cs