{"action":"created","comment":{"url":"https://api.github.com/repos/CenterForOpenScience/osf.io/pulls/comments/40436126","id":40436126,"diff_hunk":"@@ -35,7 +35,249 @@ def get_file(self, check_permissions=True):\n \n \n class FileDetail(generics.RetrieveUpdateAPIView, FileMixin):\n-    \"\"\"Details about a specific file.\n+    \"\"\"Details about files and folders. *Writeable*.\n+\n+    Welcome to the Files API.  Brace yourself, things are about to get *weird*.\n+\n+    The Files API is the one place in the OSF API where we break hard from the JSON-API spec.  This is because most of\n+    the behind-the-scenes moving, uploading, deleting, etc. of files and folders is actually be handled for us by a\n+    nifty piece of software called [WaterButler](https://github.com/CenterForOpenScience/waterbutler).  WaterButler lets\n+    us interact with files stored on different cloud storage platforms through a consistent API.  However, it uses\n+    different conventions for requests, responses, and URL-building, so pay close attention to the documentation for\n+    [actions](#actions).  The exceptions are the \"Get Info\" and \"Checkout\" actions, which are OSF-centric.\n+\n+    If your file or folder is stored on a non-OSF provider, the file metadata will be retrieved if not already present\n+    in the system.  Otherwise, the cached metadata will be presented.  To force metadata retrieval, you'll need to issue\n+    a GET request to the Node Files List endpoint.\n+\n+    Both files and folders are available through the Files API and are distinguished by the `kind` attribute (\"file\" for\n+    files, \"folder\" for folders).  Not all actions and relationships are relevent to both files and folders, so the\n+    applicable types are listed by each heading.\n+\n+    ###Waterbutler Entities\n+\n+    When an action is performed against a WaterButler endpoint, it will generally respond with a file entity, a folder\n+    entity, or no content.\n+\n+    ####File Entity\n+\n+        name          type       description\n+        -------------------------------------------------------------------------\n+        name          string     name of the new folder\n+        path          string     OSF path/id of the file\n+        materialized  string     the full path of the folder relative to the storage root\n+        kind          string     \"file\"\n+        etag          string     etag - http caching identifier\n+        modified      timestamp  last modified timestamp - format depends on provider\n+        contentType   string     null if provider=\"osfstorage\", else MIME-type\n+        provider      string     id of provider e.g. \"osfstorage\", \"s3\", \"googledrive\"\n+        size          integer    size of file in bytes\n+        extra         object\n+          version     integer    version number of file. will be 1 on initial upload\n+          downloads   integer    count of the number times the file has been downloaded\n+          hashes      object\n+            md5       string     md5 hash of file\n+            sha256    string     SHA-256 hash of file\n+\n+    ####Folder Entity\n+\n+        name          type    description\n+        ----------------------------------------------------------------------\n+        name          string  name of the new folder\n+        path          string  OSF path/id of the folder\n+        materialized  string  the full path of the folder relative to the storage root\n+        kind          string  \"folder\"\n+        etag          string  etag - http caching identifier\n+        extra         object  null\n+\n+\n+    ##Attributes\n+\n+    For an OSF File entity, the `type` is \"files\" regardless of whether the entity is actually a file or folder.  They\n+    can be distinguished by the `kind` attribute.  Files and folders use the same representation, but some attributes may\n+    be null for one kind but not the other. `size` will be null for folders.  A list of storage provider keys can be\n+    found [here](/v2/#storage-providers).\n+\n+        name          type               description\n+        ---------------------------------------------------------------------------------\n+        name          string             name of the file or folder; use for display\n+        kind          string             \"file\" or \"folder\"\n+        path          url path           unique path for this entity, used in \"move\" actions\n+        size          integer            size of file in bytes, null for folders\n+        provider      string             storage provider for this file. \"osfstorage\" if stored on the OSF.  Other\n+                                         examples include \"s3\" for Amazon S3, \"googledrive\" for Google Drive, \"box\"\n+                                         for Box.com.\n+        last_touched  iso8601 timestamp  last time the metadata for the file was retrieved. only applies to non-OSF\n+                                         storage providers.\n+\n+    ##Relationships\n+\n+    ###Checkout (*files, folders*)\n+\n+    ** *Checkouts are still a work-in-progress. This property may be set but is currently a no-op.* **\n+\n+    A link to the user who has checked out the file.  While a file is checked out, only the checkout holder may modify\n+    it.  If a file is not checked out, this url will be null.\n+\n+    ###Files (*folders*)\n+\n+    The `files` endpoint lists all of the subfiles and folders of the current folder. Will be null for files.\n+\n+    ###Versions (*files*)\n+\n+    The `versions` endpoint provides version history for files.  Will be null for folders.\n+\n+    ##Links\n+\n+        info:        the canonical api endpoint for the latest version of the file\n+        new_folder:  url to target when creating new subfolders (null for files)\n+        move:        url to target for move, copy, and rename actions\n+        upload:      url to target for uploading new files and updating existing files\n+        download:    url to request a download of the latest version of the file (null for folders)\n+        delete:      url to target for deleting files and folders\n+\n+    ##Actions\n+\n+    The `links` property of the response provides endpoints for common file operations. The currently-supported actions\n+    are:\n+\n+    ###Get Info (*files, folders*)\n+\n+        Method:   GET\n+        URL:      links.info\n+        Params:   <none>\n+        Success:  200 OK + file representation\n+\n+    The details of a particular file can be retrieved by performing a GET request against the `info` link. The response\n+    will be a standard OSF response format with the [OSF File attributes](#attributes).\n+\n+    ###Download (*files*)\n+\n+        Method:   GET\n+        URL:      links.download\n+        Params:   <none>\n+        Success:  200 OK + file body\n+\n+    To download a file, issue a GET request against the `download` link.  The response will have the Content-Disposition\n+    header set, which will will trigger a download in a browser.\n+\n+    ###Create Subfolder (*folders*)\n+\n+        Method:       PUT\n+        URL:          links.new_folder\n+        Query Params: ?name={new_folder_name}\n+        Body:         <empty>\n+        Success:      201 Created + new folder representation\n+\n+    You can create a subfolder of an existing folder by issuing a PUT request against the `new_folder` link.  The name\n+    of the new subfolder should be provided in the `name` query parameter.  The response will contain a [WaterButler\n+    folder entity](#folder-entity).\n+\n+    ###Upload New File (*folders*)\n+\n+        Method:       PUT\n+        URL:          links.upload\n+        Query Params: ?kind=file&name={new_file_name}\n+        Body (Raw):   <file data (not form-encoded)>\n+        Success:      201 Created + new file representation\n+\n+    To upload a file to a folder, issue a PUT request to the folder's `upload` link with the raw file data in the\n+    request body, and the `kind` and `name` query parameters set to `'file'` and the desired name of the file.  The\n+    response will contain a [WaterButler file entity](#file-entity) that describes the new file.\n+\n+    ###Update Existing File (*file*)\n+\n+        Method:       PUT\n+        URL:          links.upload\n+        Query Params: ?kind=file&name={new_file_name}","path":"api/files/views.py","position":159,"original_position":159,"commit_id":"ce45edcac40b096a95222ce18da7df2be89cb180","original_commit_id":"ce45edcac40b096a95222ce18da7df2be89cb180","user":{"login":"chrisseto","id":5532905,"avatar_url":"https://avatars.githubusercontent.com/u/5532905?v=3","gravatar_id":"","url":"https://api.github.com/users/chrisseto","html_url":"https://github.com/chrisseto","followers_url":"https://api.github.com/users/chrisseto/followers","following_url":"https://api.github.com/users/chrisseto/following{/other_user}","gists_url":"https://api.github.com/users/chrisseto/gists{/gist_id}","starred_url":"https://api.github.com/users/chrisseto/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/chrisseto/subscriptions","organizations_url":"https://api.github.com/users/chrisseto/orgs","repos_url":"https://api.github.com/users/chrisseto/repos","events_url":"https://api.github.com/users/chrisseto/events{/privacy}","received_events_url":"https://api.github.com/users/chrisseto/received_events","type":"User","site_admin":false},"body":"Should name be `{old_file_name}`?\r\nYou can also put directly to a file to update it.","created_at":"2015-09-25T14:37:16Z","updated_at":"2015-09-25T14:37:16Z","html_url":"https://github.com/CenterForOpenScience/osf.io/pull/4337#discussion_r40436126","pull_request_url":"https://api.github.com/repos/CenterForOpenScience/osf.io/pulls/4337","_links":{"self":{"href":"https://api.github.com/repos/CenterForOpenScience/osf.io/pulls/comments/40436126"},"html":{"href":"https://github.com/CenterForOpenScience/osf.io/pull/4337#discussion_r40436126"},"pull_request":{"href":"https://api.github.com/repos/CenterForOpenScience/osf.io/pulls/4337"}}},"pull_request":{"url":"https://api.github.com/repos/CenterForOpenScience/osf.io/pulls/4337","id":45777232,"html_url":"https://github.com/CenterForOpenScience/osf.io/pull/4337","diff_url":"https://github.com/CenterForOpenScience/osf.io/pull/4337.diff","patch_url":"https://github.com/CenterForOpenScience/osf.io/pull/4337.patch","issue_url":"https://api.github.com/repos/CenterForOpenScience/osf.io/issues/4337","number":4337,"state":"open","locked":false,"title":"[CR] Add browsable API docs for api v2","user":{"login":"felliott","id":86835,"avatar_url":"https://avatars.githubusercontent.com/u/86835?v=3","gravatar_id":"","url":"https://api.github.com/users/felliott","html_url":"https://github.com/felliott","followers_url":"https://api.github.com/users/felliott/followers","following_url":"https://api.github.com/users/felliott/following{/other_user}","gists_url":"https://api.github.com/users/felliott/gists{/gist_id}","starred_url":"https://api.github.com/users/felliott/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/felliott/subscriptions","organizations_url":"https://api.github.com/users/felliott/orgs","repos_url":"https://api.github.com/users/felliott/repos","events_url":"https://api.github.com/users/felliott/events{/privacy}","received_events_url":"https://api.github.com/users/felliott/received_events","type":"User","site_admin":false},"body":"For: [#OSF-4248]\r\n\r\nThis PR is currently a work in progress, and is probably out-of-date with respect to current develop (92aa988).  ","created_at":"2015-09-23T13:15:48Z","updated_at":"2015-09-25T14:37:16Z","closed_at":null,"merged_at":null,"merge_commit_sha":"a95298e6472e013482e9c9631f069e8244cf77aa","assignee":null,"milestone":null,"commits_url":"https://api.github.com/repos/CenterForOpenScience/osf.io/pulls/4337/commits","review_comments_url":"https://api.github.com/repos/CenterForOpenScience/osf.io/pulls/4337/comments","review_comment_url":"https://api.github.com/repos/CenterForOpenScience/osf.io/pulls/comments{/number}","comments_url":"https://api.github.com/repos/CenterForOpenScience/osf.io/issues/4337/comments","statuses_url":"https://api.github.com/repos/CenterForOpenScience/osf.io/statuses/ce45edcac40b096a95222ce18da7df2be89cb180","head":{"label":"felliott:feature/api-v2-docs","ref":"feature/api-v2-docs","sha":"ce45edcac40b096a95222ce18da7df2be89cb180","user":{"login":"felliott","id":86835,"avatar_url":"https://avatars.githubusercontent.com/u/86835?v=3","gravatar_id":"","url":"https://api.github.com/users/felliott","html_url":"https://github.com/felliott","followers_url":"https://api.github.com/users/felliott/followers","following_url":"https://api.github.com/users/felliott/following{/other_user}","gists_url":"https://api.github.com/users/felliott/gists{/gist_id}","starred_url":"https://api.github.com/users/felliott/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/felliott/subscriptions","organizations_url":"https://api.github.com/users/felliott/orgs","repos_url":"https://api.github.com/users/felliott/repos","events_url":"https://api.github.com/users/felliott/events{/privacy}","received_events_url":"https://api.github.com/users/felliott/received_events","type":"User","site_admin":false},"repo":{"id":42676625,"name":"osf.io","full_name":"felliott/osf.io","owner":{"login":"felliott","id":86835,"avatar_url":"https://avatars.githubusercontent.com/u/86835?v=3","gravatar_id":"","url":"https://api.github.com/users/felliott","html_url":"https://github.com/felliott","followers_url":"https://api.github.com/users/felliott/followers","following_url":"https://api.github.com/users/felliott/following{/other_user}","gists_url":"https://api.github.com/users/felliott/gists{/gist_id}","starred_url":"https://api.github.com/users/felliott/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/felliott/subscriptions","organizations_url":"https://api.github.com/users/felliott/orgs","repos_url":"https://api.github.com/users/felliott/repos","events_url":"https://api.github.com/users/felliott/events{/privacy}","received_events_url":"https://api.github.com/users/felliott/received_events","type":"User","site_admin":false},"private":false,"html_url":"https://github.com/felliott/osf.io","description":"Facilitating Open Science","fork":true,"url":"https://api.github.com/repos/felliott/osf.io","forks_url":"https://api.github.com/repos/felliott/osf.io/forks","keys_url":"https://api.github.com/repos/felliott/osf.io/keys{/key_id}","collaborators_url":"https://api.github.com/repos/felliott/osf.io/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/felliott/osf.io/teams","hooks_url":"https://api.github.com/repos/felliott/osf.io/hooks","issue_events_url":"https://api.github.com/repos/felliott/osf.io/issues/events{/number}","events_url":"https://api.github.com/repos/felliott/osf.io/events","assignees_url":"https://api.github.com/repos/felliott/osf.io/assignees{/user}","branches_url":"https://api.github.com/repos/felliott/osf.io/branches{/branch}","tags_url":"https://api.github.com/repos/felliott/osf.io/tags","blobs_url":"https://api.github.com/repos/felliott/osf.io/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/felliott/osf.io/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/felliott/osf.io/git/refs{/sha}","trees_url":"https://api.github.com/repos/felliott/osf.io/git/trees{/sha}","statuses_url":"https://api.github.com/repos/felliott/osf.io/statuses/{sha}","languages_url":"https://api.github.com/repos/felliott/osf.io/languages","stargazers_url":"https://api.github.com/repos/felliott/osf.io/stargazers","contributors_url":"https://api.github.com/repos/felliott/osf.io/contributors","subscribers_url":"https://api.github.com/repos/felliott/osf.io/subscribers","subscription_url":"https://api.github.com/repos/felliott/osf.io/subscription","commits_url":"https://api.github.com/repos/felliott/osf.io/commits{/sha}","git_commits_url":"https://api.github.com/repos/felliott/osf.io/git/commits{/sha}","comments_url":"https://api.github.com/repos/felliott/osf.io/comments{/number}","issue_comment_url":"https://api.github.com/repos/felliott/osf.io/issues/comments{/number}","contents_url":"https://api.github.com/repos/felliott/osf.io/contents/{+path}","compare_url":"https://api.github.com/repos/felliott/osf.io/compare/{base}...{head}","merges_url":"https://api.github.com/repos/felliott/osf.io/merges","archive_url":"https://api.github.com/repos/felliott/osf.io/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/felliott/osf.io/downloads","issues_url":"https://api.github.com/repos/felliott/osf.io/issues{/number}","pulls_url":"https://api.github.com/repos/felliott/osf.io/pulls{/number}","milestones_url":"https://api.github.com/repos/felliott/osf.io/milestones{/number}","notifications_url":"https://api.github.com/repos/felliott/osf.io/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/felliott/osf.io/labels{/name}","releases_url":"https://api.github.com/repos/felliott/osf.io/releases{/id}","created_at":"2015-09-17T19:17:58Z","updated_at":"2015-09-17T19:18:03Z","pushed_at":"2015-09-25T14:12:44Z","git_url":"git://github.com/felliott/osf.io.git","ssh_url":"git@github.com:felliott/osf.io.git","clone_url":"https://github.com/felliott/osf.io.git","svn_url":"https://github.com/felliott/osf.io","homepage":"http://osf.io","size":101554,"stargazers_count":0,"watchers_count":0,"language":"Python","has_issues":false,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":0,"mirror_url":null,"open_issues_count":0,"forks":0,"open_issues":0,"watchers":0,"default_branch":"develop"}},"base":{"label":"CenterForOpenScience:develop","ref":"develop","sha":"17423bbc5af1d722c864af76d490442fdfb1b6fd","user":{"login":"CenterForOpenScience","id":3344584,"avatar_url":"https://avatars.githubusercontent.com/u/3344584?v=3","gravatar_id":"","url":"https://api.github.com/users/CenterForOpenScience","html_url":"https://github.com/CenterForOpenScience","followers_url":"https://api.github.com/users/CenterForOpenScience/followers","following_url":"https://api.github.com/users/CenterForOpenScience/following{/other_user}","gists_url":"https://api.github.com/users/CenterForOpenScience/gists{/gist_id}","starred_url":"https://api.github.com/users/CenterForOpenScience/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/CenterForOpenScience/subscriptions","organizations_url":"https://api.github.com/users/CenterForOpenScience/orgs","repos_url":"https://api.github.com/users/CenterForOpenScience/repos","events_url":"https://api.github.com/users/CenterForOpenScience/events{/privacy}","received_events_url":"https://api.github.com/users/CenterForOpenScience/received_events","type":"Organization","site_admin":false},"repo":{"id":10199599,"name":"osf.io","full_name":"CenterForOpenScience/osf.io","owner":{"login":"CenterForOpenScience","id":3344584,"avatar_url":"https://avatars.githubusercontent.com/u/3344584?v=3","gravatar_id":"","url":"https://api.github.com/users/CenterForOpenScience","html_url":"https://github.com/CenterForOpenScience","followers_url":"https://api.github.com/users/CenterForOpenScience/followers","following_url":"https://api.github.com/users/CenterForOpenScience/following{/other_user}","gists_url":"https://api.github.com/users/CenterForOpenScience/gists{/gist_id}","starred_url":"https://api.github.com/users/CenterForOpenScience/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/CenterForOpenScience/subscriptions","organizations_url":"https://api.github.com/users/CenterForOpenScience/orgs","repos_url":"https://api.github.com/users/CenterForOpenScience/repos","events_url":"https://api.github.com/users/CenterForOpenScience/events{/privacy}","received_events_url":"https://api.github.com/users/CenterForOpenScience/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/CenterForOpenScience/osf.io","description":"Facilitating Open Science","fork":false,"url":"https://api.github.com/repos/CenterForOpenScience/osf.io","forks_url":"https://api.github.com/repos/CenterForOpenScience/osf.io/forks","keys_url":"https://api.github.com/repos/CenterForOpenScience/osf.io/keys{/key_id}","collaborators_url":"https://api.github.com/repos/CenterForOpenScience/osf.io/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/CenterForOpenScience/osf.io/teams","hooks_url":"https://api.github.com/repos/CenterForOpenScience/osf.io/hooks","issue_events_url":"https://api.github.com/repos/CenterForOpenScience/osf.io/issues/events{/number}","events_url":"https://api.github.com/repos/CenterForOpenScience/osf.io/events","assignees_url":"https://api.github.com/repos/CenterForOpenScience/osf.io/assignees{/user}","branches_url":"https://api.github.com/repos/CenterForOpenScience/osf.io/branches{/branch}","tags_url":"https://api.github.com/repos/CenterForOpenScience/osf.io/tags","blobs_url":"https://api.github.com/repos/CenterForOpenScience/osf.io/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/CenterForOpenScience/osf.io/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/CenterForOpenScience/osf.io/git/refs{/sha}","trees_url":"https://api.github.com/repos/CenterForOpenScience/osf.io/git/trees{/sha}","statuses_url":"https://api.github.com/repos/CenterForOpenScience/osf.io/statuses/{sha}","languages_url":"https://api.github.com/repos/CenterForOpenScience/osf.io/languages","stargazers_url":"https://api.github.com/repos/CenterForOpenScience/osf.io/stargazers","contributors_url":"https://api.github.com/repos/CenterForOpenScience/osf.io/contributors","subscribers_url":"https://api.github.com/repos/CenterForOpenScience/osf.io/subscribers","subscription_url":"https://api.github.com/repos/CenterForOpenScience/osf.io/subscription","commits_url":"https://api.github.com/repos/CenterForOpenScience/osf.io/commits{/sha}","git_commits_url":"https://api.github.com/repos/CenterForOpenScience/osf.io/git/commits{/sha}","comments_url":"https://api.github.com/repos/CenterForOpenScience/osf.io/comments{/number}","issue_comment_url":"https://api.github.com/repos/CenterForOpenScience/osf.io/issues/comments{/number}","contents_url":"https://api.github.com/repos/CenterForOpenScience/osf.io/contents/{+path}","compare_url":"https://api.github.com/repos/CenterForOpenScience/osf.io/compare/{base}...{head}","merges_url":"https://api.github.com/repos/CenterForOpenScience/osf.io/merges","archive_url":"https://api.github.com/repos/CenterForOpenScience/osf.io/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/CenterForOpenScience/osf.io/downloads","issues_url":"https://api.github.com/repos/CenterForOpenScience/osf.io/issues{/number}","pulls_url":"https://api.github.com/repos/CenterForOpenScience/osf.io/pulls{/number}","milestones_url":"https://api.github.com/repos/CenterForOpenScience/osf.io/milestones{/number}","notifications_url":"https://api.github.com/repos/CenterForOpenScience/osf.io/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/CenterForOpenScience/osf.io/labels{/name}","releases_url":"https://api.github.com/repos/CenterForOpenScience/osf.io/releases{/id}","created_at":"2013-05-21T15:53:37Z","updated_at":"2015-09-23T19:12:14Z","pushed_at":"2015-09-25T14:12:44Z","git_url":"git://github.com/CenterForOpenScience/osf.io.git","ssh_url":"git@github.com:CenterForOpenScience/osf.io.git","clone_url":"https://github.com/CenterForOpenScience/osf.io.git","svn_url":"https://github.com/CenterForOpenScience/osf.io","homepage":"http://osf.io","size":231751,"stargazers_count":139,"watchers_count":139,"language":"Python","has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":120,"mirror_url":null,"open_issues_count":419,"forks":120,"open_issues":419,"watchers":139,"default_branch":"develop"}},"_links":{"self":{"href":"https://api.github.com/repos/CenterForOpenScience/osf.io/pulls/4337"},"html":{"href":"https://github.com/CenterForOpenScience/osf.io/pull/4337"},"issue":{"href":"https://api.github.com/repos/CenterForOpenScience/osf.io/issues/4337"},"comments":{"href":"https://api.github.com/repos/CenterForOpenScience/osf.io/issues/4337/comments"},"review_comments":{"href":"https://api.github.com/repos/CenterForOpenScience/osf.io/pulls/4337/comments"},"review_comment":{"href":"https://api.github.com/repos/CenterForOpenScience/osf.io/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/CenterForOpenScience/osf.io/pulls/4337/commits"},"statuses":{"href":"https://api.github.com/repos/CenterForOpenScience/osf.io/statuses/ce45edcac40b096a95222ce18da7df2be89cb180"}}}}