{"action":"created","comment":{"url":"https://api.github.com/repos/aspnet/Docs/pulls/comments/66910410","id":66910410,"diff_hunk":"@@ -1,8 +1,223 @@\n-.. include:: /../common/stub-topic.txt\n+Formatting Response Data\n+========================\n \n-|stub-icon| Formatting\n-======================\n+By `Steve Smith`_\n \n-.. include:: /../common/stub-notice.txt\n+ASP.NET Core MVC has built-in support for formatting response data, using fixed formats or in response to client specifications.\n+\n+.. contents:: Sections\n+    :local:\n+    :depth: 1\n+\n+`View or download sample from GitHub <https://github.com/aspnet/Docs/tree/master/mvc/models/formatting/sample>`_.\n+\n+Format-Specific Action Results\n+------------------------------\n+\n+Some ``ActionResult`` options are specific to a particular format, such as ``JsonResult`` and ``ContentResult`` (note string return types are simply formatted as text). Actions can return specific results that are always formatted in a particular manner. For example, returning a ``JsonResult`` will return JSON-formatted data, regardless of client preferences. Likewise, returning a ``ContentResult`` will return plain text formatted string data.\n+\n+To return data using a specific result type, assuming you're inheriting from the base ``Controller`` class, it's recommended that you use the built-in helper method ``Json`` to return JSON and ``Content`` plain text. These methods check to see if the data being formatted implements ``IDisposable`` and register the object for disposal if required. Your action method should return either the specific result type (for instance, ``JsonResult``) or ``IActionResult``.\n+\n+Returning JSON-formatted data:\n+\n+.. literalinclude:: formatting/sample/src/ResponseFormattingSample/Controllers/Api/AuthorsController.cs\n+  :language: c#\n+  :lines: 21-26\n+  :emphasize-lines: 3,5\n+  :dedent: 8\n+\n+Sample response from this action:\n+\n+.. image:: formatting/_static/json-response.png\n+\n+Note that the content type of the response is ``application/json``, shown both in the list of network requests and in the Response Headers section. Also note the list of options presented by the browser (in this case, Microsoft Edge) in the Accept header, in the Request Headers section. The current technique is ignoring this header; obeying it is discussed below.\n+\n+To return plain text formatted data, use ``ContentResult`` and the ``Content`` helper:\n+\n+.. literalinclude:: formatting/sample/src/ResponseFormattingSample/Controllers/Api/AuthorsController.cs\n+  :language: c#\n+  :lines: 47-52\n+  :emphasize-lines: 3,5\n+  :dedent: 8\n+\n+A response from this action:\n+\n+.. image:: formatting/_static/text-response.png\n+\n+Note in this case the ``Content-Type`` returned is ``text/plain``. You can also achieve this same behavior using just a string response type:\n+\n+.. literalinclude:: formatting/sample/src/ResponseFormattingSample/Controllers/Api/AuthorsController.cs\n+  :language: c#\n+  :lines: 54-59\n+  :emphasize-lines: 3,5\n+  :dedent: 8\n+\n+.. tip:: For non-trivial actions with multiple return types or options (for example, different HTTP status codes based on the result of operations performed), prefer ``IActionResult`` as the return type.\n+\n+Content Negotiation\n+-------------------\n+\n+Content negotiation (*conneg* for short) occurs when the client specifies an `Accept header <https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html>`_. The default format used by ASP.NET Core MVC is JSON. Negotiation occurs automatically for ``IActionResult`` return types, including results returned using the helper methods ``Ok``, ``BadRequest``, ``Created``, etc. You can also return a model type (a class you've defined as your data transfer type) and the framework will automatically wrap it in an ``ObjectResult`` for you.","path":"aspnet/mvc/models/formatting.rst","position":64,"original_position":64,"commit_id":"c91b4deb5e4838b57173edcc58fd609dfe9226dc","original_commit_id":"c91b4deb5e4838b57173edcc58fd609dfe9226dc","user":{"login":"danroth27","id":1874516,"avatar_url":"https://avatars.githubusercontent.com/u/1874516?v=3","gravatar_id":"","url":"https://api.github.com/users/danroth27","html_url":"https://github.com/danroth27","followers_url":"https://api.github.com/users/danroth27/followers","following_url":"https://api.github.com/users/danroth27/following{/other_user}","gists_url":"https://api.github.com/users/danroth27/gists{/gist_id}","starred_url":"https://api.github.com/users/danroth27/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/danroth27/subscriptions","organizations_url":"https://api.github.com/users/danroth27/orgs","repos_url":"https://api.github.com/users/danroth27/repos","events_url":"https://api.github.com/users/danroth27/events{/privacy}","received_events_url":"https://api.github.com/users/danroth27/received_events","type":"User","site_admin":false},"body":"> Negotiation occurs automatically for ``IActionResult`` return types, including results returned from the helper methods\r\n\r\nContent negotiation is implemented by ``ObjectResult``. It is also built into the status code specific action results returned from the helper methods","created_at":"2016-06-14T05:27:06Z","updated_at":"2016-06-14T05:27:06Z","html_url":"https://github.com/aspnet/Docs/pull/1327#discussion_r66910410","pull_request_url":"https://api.github.com/repos/aspnet/Docs/pulls/1327","_links":{"self":{"href":"https://api.github.com/repos/aspnet/Docs/pulls/comments/66910410"},"html":{"href":"https://github.com/aspnet/Docs/pull/1327#discussion_r66910410"},"pull_request":{"href":"https://api.github.com/repos/aspnet/Docs/pulls/1327"}}},"pull_request":{"url":"https://api.github.com/repos/aspnet/Docs/pulls/1327","id":72223964,"html_url":"https://github.com/aspnet/Docs/pull/1327","diff_url":"https://github.com/aspnet/Docs/pull/1327.diff","patch_url":"https://github.com/aspnet/Docs/pull/1327.patch","issue_url":"https://api.github.com/repos/aspnet/Docs/issues/1327","number":1327,"state":"open","locked":false,"title":"Formatting Response Data","user":{"login":"ardalis","id":782127,"avatar_url":"https://avatars.githubusercontent.com/u/782127?v=3","gravatar_id":"","url":"https://api.github.com/users/ardalis","html_url":"https://github.com/ardalis","followers_url":"https://api.github.com/users/ardalis/followers","following_url":"https://api.github.com/users/ardalis/following{/other_user}","gists_url":"https://api.github.com/users/ardalis/gists{/gist_id}","starred_url":"https://api.github.com/users/ardalis/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/ardalis/subscriptions","organizations_url":"https://api.github.com/users/ardalis/orgs","repos_url":"https://api.github.com/users/ardalis/repos","events_url":"https://api.github.com/users/ardalis/events{/privacy}","received_events_url":"https://api.github.com/users/ardalis/received_events","type":"User","site_admin":false},"body":"Fixes #122 \r\n@Rick-Anderson please review","created_at":"2016-06-01T17:52:09Z","updated_at":"2016-06-14T05:27:06Z","closed_at":null,"merged_at":null,"merge_commit_sha":"3476c2ea40f8dfbd1cdd32a3a91807e2aa842ca7","assignee":null,"milestone":null,"commits_url":"https://api.github.com/repos/aspnet/Docs/pulls/1327/commits","review_comments_url":"https://api.github.com/repos/aspnet/Docs/pulls/1327/comments","review_comment_url":"https://api.github.com/repos/aspnet/Docs/pulls/comments{/number}","comments_url":"https://api.github.com/repos/aspnet/Docs/issues/1327/comments","statuses_url":"https://api.github.com/repos/aspnet/Docs/statuses/c91b4deb5e4838b57173edcc58fd609dfe9226dc","head":{"label":"aspnet:ardalis/formatting-response","ref":"ardalis/formatting-response","sha":"c91b4deb5e4838b57173edcc58fd609dfe9226dc","user":{"login":"aspnet","id":6476660,"avatar_url":"https://avatars.githubusercontent.com/u/6476660?v=3","gravatar_id":"","url":"https://api.github.com/users/aspnet","html_url":"https://github.com/aspnet","followers_url":"https://api.github.com/users/aspnet/followers","following_url":"https://api.github.com/users/aspnet/following{/other_user}","gists_url":"https://api.github.com/users/aspnet/gists{/gist_id}","starred_url":"https://api.github.com/users/aspnet/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/aspnet/subscriptions","organizations_url":"https://api.github.com/users/aspnet/orgs","repos_url":"https://api.github.com/users/aspnet/repos","events_url":"https://api.github.com/users/aspnet/events{/privacy}","received_events_url":"https://api.github.com/users/aspnet/received_events","type":"Organization","site_admin":false},"repo":{"id":28239455,"name":"Docs","full_name":"aspnet/Docs","owner":{"login":"aspnet","id":6476660,"avatar_url":"https://avatars.githubusercontent.com/u/6476660?v=3","gravatar_id":"","url":"https://api.github.com/users/aspnet","html_url":"https://github.com/aspnet","followers_url":"https://api.github.com/users/aspnet/followers","following_url":"https://api.github.com/users/aspnet/following{/other_user}","gists_url":"https://api.github.com/users/aspnet/gists{/gist_id}","starred_url":"https://api.github.com/users/aspnet/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/aspnet/subscriptions","organizations_url":"https://api.github.com/users/aspnet/orgs","repos_url":"https://api.github.com/users/aspnet/repos","events_url":"https://api.github.com/users/aspnet/events{/privacy}","received_events_url":"https://api.github.com/users/aspnet/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/aspnet/Docs","description":"Documentation for ASP.NET Core","fork":false,"url":"https://api.github.com/repos/aspnet/Docs","forks_url":"https://api.github.com/repos/aspnet/Docs/forks","keys_url":"https://api.github.com/repos/aspnet/Docs/keys{/key_id}","collaborators_url":"https://api.github.com/repos/aspnet/Docs/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/aspnet/Docs/teams","hooks_url":"https://api.github.com/repos/aspnet/Docs/hooks","issue_events_url":"https://api.github.com/repos/aspnet/Docs/issues/events{/number}","events_url":"https://api.github.com/repos/aspnet/Docs/events","assignees_url":"https://api.github.com/repos/aspnet/Docs/assignees{/user}","branches_url":"https://api.github.com/repos/aspnet/Docs/branches{/branch}","tags_url":"https://api.github.com/repos/aspnet/Docs/tags","blobs_url":"https://api.github.com/repos/aspnet/Docs/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/aspnet/Docs/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/aspnet/Docs/git/refs{/sha}","trees_url":"https://api.github.com/repos/aspnet/Docs/git/trees{/sha}","statuses_url":"https://api.github.com/repos/aspnet/Docs/statuses/{sha}","languages_url":"https://api.github.com/repos/aspnet/Docs/languages","stargazers_url":"https://api.github.com/repos/aspnet/Docs/stargazers","contributors_url":"https://api.github.com/repos/aspnet/Docs/contributors","subscribers_url":"https://api.github.com/repos/aspnet/Docs/subscribers","subscription_url":"https://api.github.com/repos/aspnet/Docs/subscription","commits_url":"https://api.github.com/repos/aspnet/Docs/commits{/sha}","git_commits_url":"https://api.github.com/repos/aspnet/Docs/git/commits{/sha}","comments_url":"https://api.github.com/repos/aspnet/Docs/comments{/number}","issue_comment_url":"https://api.github.com/repos/aspnet/Docs/issues/comments{/number}","contents_url":"https://api.github.com/repos/aspnet/Docs/contents/{+path}","compare_url":"https://api.github.com/repos/aspnet/Docs/compare/{base}...{head}","merges_url":"https://api.github.com/repos/aspnet/Docs/merges","archive_url":"https://api.github.com/repos/aspnet/Docs/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/aspnet/Docs/downloads","issues_url":"https://api.github.com/repos/aspnet/Docs/issues{/number}","pulls_url":"https://api.github.com/repos/aspnet/Docs/pulls{/number}","milestones_url":"https://api.github.com/repos/aspnet/Docs/milestones{/number}","notifications_url":"https://api.github.com/repos/aspnet/Docs/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/aspnet/Docs/labels{/name}","releases_url":"https://api.github.com/repos/aspnet/Docs/releases{/id}","deployments_url":"https://api.github.com/repos/aspnet/Docs/deployments","created_at":"2014-12-19T17:38:02Z","updated_at":"2016-06-13T18:47:01Z","pushed_at":"2016-06-14T03:33:02Z","git_url":"git://github.com/aspnet/Docs.git","ssh_url":"git@github.com:aspnet/Docs.git","clone_url":"https://github.com/aspnet/Docs.git","svn_url":"https://github.com/aspnet/Docs","homepage":"","size":51161,"stargazers_count":527,"watchers_count":527,"language":"C#","has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":904,"mirror_url":null,"open_issues_count":158,"forks":904,"open_issues":158,"watchers":527,"default_branch":"master"}},"base":{"label":"aspnet:master","ref":"master","sha":"25720cc6a15a16e7d2719c3d9bc4a9248d69512e","user":{"login":"aspnet","id":6476660,"avatar_url":"https://avatars.githubusercontent.com/u/6476660?v=3","gravatar_id":"","url":"https://api.github.com/users/aspnet","html_url":"https://github.com/aspnet","followers_url":"https://api.github.com/users/aspnet/followers","following_url":"https://api.github.com/users/aspnet/following{/other_user}","gists_url":"https://api.github.com/users/aspnet/gists{/gist_id}","starred_url":"https://api.github.com/users/aspnet/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/aspnet/subscriptions","organizations_url":"https://api.github.com/users/aspnet/orgs","repos_url":"https://api.github.com/users/aspnet/repos","events_url":"https://api.github.com/users/aspnet/events{/privacy}","received_events_url":"https://api.github.com/users/aspnet/received_events","type":"Organization","site_admin":false},"repo":{"id":28239455,"name":"Docs","full_name":"aspnet/Docs","owner":{"login":"aspnet","id":6476660,"avatar_url":"https://avatars.githubusercontent.com/u/6476660?v=3","gravatar_id":"","url":"https://api.github.com/users/aspnet","html_url":"https://github.com/aspnet","followers_url":"https://api.github.com/users/aspnet/followers","following_url":"https://api.github.com/users/aspnet/following{/other_user}","gists_url":"https://api.github.com/users/aspnet/gists{/gist_id}","starred_url":"https://api.github.com/users/aspnet/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/aspnet/subscriptions","organizations_url":"https://api.github.com/users/aspnet/orgs","repos_url":"https://api.github.com/users/aspnet/repos","events_url":"https://api.github.com/users/aspnet/events{/privacy}","received_events_url":"https://api.github.com/users/aspnet/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/aspnet/Docs","description":"Documentation for ASP.NET Core","fork":false,"url":"https://api.github.com/repos/aspnet/Docs","forks_url":"https://api.github.com/repos/aspnet/Docs/forks","keys_url":"https://api.github.com/repos/aspnet/Docs/keys{/key_id}","collaborators_url":"https://api.github.com/repos/aspnet/Docs/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/aspnet/Docs/teams","hooks_url":"https://api.github.com/repos/aspnet/Docs/hooks","issue_events_url":"https://api.github.com/repos/aspnet/Docs/issues/events{/number}","events_url":"https://api.github.com/repos/aspnet/Docs/events","assignees_url":"https://api.github.com/repos/aspnet/Docs/assignees{/user}","branches_url":"https://api.github.com/repos/aspnet/Docs/branches{/branch}","tags_url":"https://api.github.com/repos/aspnet/Docs/tags","blobs_url":"https://api.github.com/repos/aspnet/Docs/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/aspnet/Docs/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/aspnet/Docs/git/refs{/sha}","trees_url":"https://api.github.com/repos/aspnet/Docs/git/trees{/sha}","statuses_url":"https://api.github.com/repos/aspnet/Docs/statuses/{sha}","languages_url":"https://api.github.com/repos/aspnet/Docs/languages","stargazers_url":"https://api.github.com/repos/aspnet/Docs/stargazers","contributors_url":"https://api.github.com/repos/aspnet/Docs/contributors","subscribers_url":"https://api.github.com/repos/aspnet/Docs/subscribers","subscription_url":"https://api.github.com/repos/aspnet/Docs/subscription","commits_url":"https://api.github.com/repos/aspnet/Docs/commits{/sha}","git_commits_url":"https://api.github.com/repos/aspnet/Docs/git/commits{/sha}","comments_url":"https://api.github.com/repos/aspnet/Docs/comments{/number}","issue_comment_url":"https://api.github.com/repos/aspnet/Docs/issues/comments{/number}","contents_url":"https://api.github.com/repos/aspnet/Docs/contents/{+path}","compare_url":"https://api.github.com/repos/aspnet/Docs/compare/{base}...{head}","merges_url":"https://api.github.com/repos/aspnet/Docs/merges","archive_url":"https://api.github.com/repos/aspnet/Docs/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/aspnet/Docs/downloads","issues_url":"https://api.github.com/repos/aspnet/Docs/issues{/number}","pulls_url":"https://api.github.com/repos/aspnet/Docs/pulls{/number}","milestones_url":"https://api.github.com/repos/aspnet/Docs/milestones{/number}","notifications_url":"https://api.github.com/repos/aspnet/Docs/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/aspnet/Docs/labels{/name}","releases_url":"https://api.github.com/repos/aspnet/Docs/releases{/id}","deployments_url":"https://api.github.com/repos/aspnet/Docs/deployments","created_at":"2014-12-19T17:38:02Z","updated_at":"2016-06-13T18:47:01Z","pushed_at":"2016-06-14T03:33:02Z","git_url":"git://github.com/aspnet/Docs.git","ssh_url":"git@github.com:aspnet/Docs.git","clone_url":"https://github.com/aspnet/Docs.git","svn_url":"https://github.com/aspnet/Docs","homepage":"","size":51161,"stargazers_count":527,"watchers_count":527,"language":"C#","has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":904,"mirror_url":null,"open_issues_count":158,"forks":904,"open_issues":158,"watchers":527,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/aspnet/Docs/pulls/1327"},"html":{"href":"https://github.com/aspnet/Docs/pull/1327"},"issue":{"href":"https://api.github.com/repos/aspnet/Docs/issues/1327"},"comments":{"href":"https://api.github.com/repos/aspnet/Docs/issues/1327/comments"},"review_comments":{"href":"https://api.github.com/repos/aspnet/Docs/pulls/1327/comments"},"review_comment":{"href":"https://api.github.com/repos/aspnet/Docs/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/aspnet/Docs/pulls/1327/commits"},"statuses":{"href":"https://api.github.com/repos/aspnet/Docs/statuses/c91b4deb5e4838b57173edcc58fd609dfe9226dc"}}}}
{"actor":{"display_login":"danroth27"}}