Skip to content

Latest commit

 

History

History
366 lines (226 loc) · 15.7 KB

api.rst

File metadata and controls

366 lines (226 loc) · 15.7 KB
Raw

API

v0 API

Warning

The v0 WaterButler API is deprecated and should no longer be used. It is only documented to provide a reference for legacy consumers.

TODO: v0 api docs

v1 API

The version 1 WaterButler API tries to conform to RESTful principles. A v1 url takes the form:

http://files.osf.io/v1/resources/<node_id>/providers/<provider_id>/<id_or_path>

e.g. http://files.osf.io/v1/resources/jy4bd/providers/osfstorage/523402a0234

Here jy4bd is the id of an OSF project, osfstorage is the provider, and 523402a0234 is the identifier of a particular file.

Conventions

Trailing slashes are significant. When <id_or_path> refers to a folder, it must always have a trailing slash. If it's a file, it must never have a trailing slash. Some providers allow files and folders to have the same name within a directory. The slash indicates user intention. This is true even for providers that use IDs. If the request URL contains the ID 1a23490d777c/ but 1a23490d777c refers to a file, WB will return a 404 Not Found.

Create returns 201, Update returns 200, Move/Copy returns depends. A successful file or folder creation operations should always return a 201 Created status (or 202 Accepted). A successful update/rename operation should always return a 200 Updated. Move / copy should return 200 if overwriting a file at the destination path, otherwise it should return 200.

Actions

The links property of the response provides endpoints for common file operations. The currently-supported actions are:

Get Info (files, folders)

Method:   GET
Params:   ?meta=
Success:  200 OK + file representation
Example:  GET /resources/mst3k/providers/osfstorage/?meta=

The contents of a folder or details of a particular file can be retrieved by performing a GET request against the entity's URL with the meta= query parameter appended. The response will be a JSON-API formatted response.

Download (files)

Method:   GET
Params:   <none>
Success:  200 OK + file body
Example:  GET /resources/mst3k/providers/osfstorage/2348825492342

To download a file, issue a GET request against its URL. The response will have the Content-Disposition header set, which will will trigger a download in a browser.

Download Zip Archive (folders)

Method:   GET
Params:   <none>
Success:  200 OK + folder body
Example:  GET /resources/mst3k/providers/osfstorage/23488254123123/?zip=

To download a zip archive of a folder, issue a GET request against its URL. The response will have the Content-Disposition header set, which will will trigger a download in a browser.

Create Subfolder (folders)

Method:       PUT
Query Params: ?kind=folder&name={new_folder_name}
Body:         <empty>
Success:      201 Created + new folder representation
Example:      PUT /resources/mst3k/providers/osfstorage/?kind=folder&name=foo-folder

You can create a subfolder of an existing folder by issuing a PUT request against the new_folder link. The ?kind=folder portion of the query parameter is already included in the new_folder link. The name of the new subfolder should be provided in the name query parameter. The response will contain a WaterButler folder entity. If a folder with that name already exists in the parent directory, the server will return a 409 Conflict error response.

Upload New File (folders)

Method:       PUT
Query Params: ?kind=file&name={new_file_name}
Body (Raw):   <file data (not form-encoded)>
Success:      201 Created + new file representation
Example:      PUT /resources/mst3k/providers/osfstorage/?kind=file&name=foo-file

To upload a file to a folder, issue a PUT request to the folder's upload link with the raw file data in the request body, and the kind and name query parameters set to 'file' and the desired name of the file. The response will contain a WaterButler file entity that describes the new file. If a file with the same name already exists in the folder, the server will return a 409 Conflict error response. The file may be updated via the url in the create response's /links/upload attribute.

Update Existing File (file)

Method:       PUT
Query Params: ?kind=file
Body (Raw):   <file data (not form-encoded)>
Success:      200 OK + updated file representation
Example:      PUT /resources/mst3k/providers/osfstorage/2348825492342?kind=file

To update an existing file, issue a PUT request to the file's upload link with the raw file data in the request body and the kind query parameter set to "file". The update action will create a new version of the file. The response will contain a WaterButler file entity that describes the updated file.

Rename (files, folders)

Method:        POST
Query Params:  <none>
Body (JSON):   {
                "action": "rename",
                "rename": {new_file_name}
               }
Success:       200 OK + new entity representation

To rename a file or folder, issue a POST request to the move link with the action body parameter set to "rename" and the rename body parameter set to the desired name. The response will contain either a folder entity or file entity with the new name.

Move & Copy (files, folders)

Method:        POST
Query Params:  <none>
Body (JSON):   {
                // mandatory
                "action":   "move"|"copy",
                "path":     {path_attribute_of_target_folder},
                // optional
                "rename":   {new_name},
                "conflict": "replace"|"keep"|"warn", // defaults to 'warn'
                "resource": {node_id},               // defaults to current {node_id}
                "provider": {provider}               // defaults to current {provider}
               }
Success:       200 OK or 201 Created + new entity representation

Move and copy actions both use the same request structure, a POST to the move url, but with different values for the action body parameters. The path parameter is also required and should be the OSF path attribute of the folder being written to. The rename and conflict parameters are optional. If you wish to change the name of the file or folder at its destination, set the rename parameter to the new name. The conflict param governs how name clashes are resolved. Possible values are replace, keep, and warn. warn is the default and will cause WaterButler to throw a 409 Conflict error if the file that already exists in the target folder. replace will tell WaterButler to overwrite the existing file, if present. keep will attempt to keep both by adding a suffix to the new file's name until it no longer conflicts. The suffix will be ' (x)' where x is a increasing integer starting from 1. This behavior is intended to mimic that of the OS X Finder. The response will contain either a folder entity or file entity with the new name.

Files and folders can also be moved between nodes and providers. The resource parameter is the id of the node under which the file/folder should be moved. It must agree with the path parameter, that is the path must identify a valid folder under the node identified by resource. Likewise, the provider parameter may be used to move the file/folder to another storage provider, but both the resource and path parameters must belong to a node and folder already extant on that provider. Both resource and provider default to the current node and providers.

The return value for a successful move or copy will be the metadata associated with the file or in the case of foldersm the metadata associated with that folder and its immediate children.

If a moved/copied file is overwriting an existing file, a 200 OK response will be returned. Otherwise, a 201 Created will be returned.

Delete (file, folders)

Method:        DELETE
Query Params:  ?confirm_delete=1 // required for root folder delete only
Success:       204 No Content

To delete a file or folder send a DELETE request to the delete link. Nothing will be returned in the response body. As a precaution against inadvertantly deleting the root folder, the query parameter confirm_delete must be set to 1 for root folder deletes. In addition, a root folder delete does not actually delete the root folder. Instead it deletes all contents of the folder, but not the folder itself.

Magic Query Parameters

Provider Handler Params

These query parameters apply to all providers. These are used, along with the request method, to specify what operation to perform, whether to upload, download, move, rename .etc.

meta

Indicates that WaterButler should return metadata about the file instead of downloading the contents. Not necessary for folders, which return metadata by default.

  • Type: flag
  • Expected on: GET requests for files
  • Interactions:
    • revisions / versions: meta takes precedence. File metadata is returned, the revision list is not.
    • revision / version: These are honored and passed to the the metadata method. Metadata for the file at the specified revision is returned.
  • Notes:
    • The meta query parameter is not required to fetch folder metadata; a bare GET folder request suffices. To download a folder, the zip query parameter should be provided.

zip

Tells WaterButler to download a folder's contents as a .zip file.

  • Type: flag
  • Expected on: GET requests against folder paths
  • Interactions:
    • Take precendence over all other query parameters, which will be ignored.
  • Notes:
    • A GET request against a folder with no query parameters will return metadata, but the same request on a file will download it.

kind

Indicates whether a PUT request should create a file or a folder.

  • Type: string, either "file" or "folder", defaulting to "file"
  • Expected on: PUT requests
  • Interactions: None
  • Notes:
    • Issuing a PUT request against a file with ?kind=folder will always fail, throwing a 400 Bad Request.

name

Indicates the name of the file or folder to be created.

  • Type: string
  • Expected on: PUT requests for folders
  • Interactions: None
  • Notes:
    • The name parameter is only valid when creating a new file or folder. Including it in a PUT request against a file will result in a 400 Bad Request. Renaming files is done with POST requests.

revisions / versions

Indicates the user wants a list of metadata for all available file revisions.

  • Type: flag
  • Expected on: GET for file paths
  • Interactions:
    • Both parameters are overridden by the meta parameter. Neither should be used with other parameters.
    • revisions and versions are currently used interchangeably, with versions taking precedence if both are provided.
  • Notes:
    • The pluralization is vital, version and revision are used for identifying particular versions.

revision / version

This is the id of the version or revision of the file or folder which Waterbuter is to return.

  • Type: int
  • Expected on: GET or HEAD requests for files or folders
  • Interactions:
    • is used as a parameter of the metadata provider function.
  • Notes:
    • If both are provided, version takes precendence over revision.
    • revision and version can be used interchangeably. Comments within the code indicate version is preferred, but no reason is supplied.
    • Note the lack of pluralization.

direct

Issuing a download request with a query parameter named direct indicates that WB should handle the download, even if a direct download via redirect would be possible (e.g. osfstorage and s3). In this case, WB will act as a middleman, downloading the data from the provider and passing it through to the requestor.

  • Type: flag
  • Expected on: GET file paths
  • Interactions: None
  • Notes:
    • Only supported by/relevant to osfstorage (GoogleCloud or Rackspace Cloudfiles backend) and S3.

displayName

When downloading a file, sets the name to download it as. Replaces the original file name in the Content-Disposition header.

  • Type: string
  • Expected on: GET download requests for files
  • Interactions: None
  • Notes: None

mode

Indicates if a file is being downloaded to be rendered. Outside OSF's MFR this isn't useful.

  • Type: string
  • Expected on: GET requests for files
  • Interactions: None
  • Notes:
    • mode is only used by the osfstorage provider for MFR.

confirm_delete

WaterButler does not permit users to delete the root folder of a provider, as this would break the connection between the resource and the storage provider. This request has been repurposed to recursively delete the entire contents of the root, leaving the root behind. For safety, this request requires an additional query parameter confirm_delete to be present and set to 1.

  • Type: bool
  • Expected on: DELETE requests against a root folder
  • Interactions: None
  • Notes:
    • Currently supported by: Figshare, Dropbox, Box, Github, S3, Google Drive, and osfstorage

Auth Handler Params

These query parameters are relayed to the auth handler to support authentication and authorization of the request.

cookie

Allows WaterButler to authenticate as a user using a cookie issued by the auth handler.

  • Type: string
  • Expected on: All calls
  • Notes: This is a legacy method of authentication and will be discontinued in the future.

view_only

OSF-specific parameter used to identify special "view-only" links that are used to give temporary read access toa protected resource.

  • Type: string
  • Expected on: GET requests for files or folders
  • Notes: Only used internally for the Open Science Framework.

GitHub Provider Params

Query parameters specific to the GitHub provider.

commit / branch identification

Not a single parameter, but rather a class of parameters. WaterButler has used many different parameters to identify the branch or commit a particular file should be found under. These parameters can be either a commit SHA or a branch name. These parameters are ref, version, branch, sha, revision. All will continue to be supported to maintain back-compatibility, but ref (for SHAs or branch names) and branch (branch names only) are preferred.

If both a SHA and a branch name are provided in different parameters, the SHA will take precedence. If multiple parameters are given with different SHAs, then the order of precedence will be: ref, version, sha, revision, branch. If multiple parameters are given with different branches, the order of precedence is: branch, ref, version, sha, revision.

  • Type: str
  • Expected on: Any GitHub provider request
  • Interactions: None

fileSha

Identifies a specific revision of a file via its SHA.

Warning

PLEASE DON'T USE THIS! This was a mistake and should have never been added. It will hopefully be removed or at the very least demoted in a future version. File SHAs only identify the contents of a file. They provide no information about the file name, path, commit, branch, etc.

  • Type: str
  • Expected on: Any GitHub provider request
  • Interactions: The fileSha is always assumed to be a file revision that is an ancestor of the imputed commit or branch ref. Providing a fileSha for a file version that was committed after the imputed ref will result in a 404.