[WIP] files: add /files endpoints

source/includes/overview/_introduction.md

@@ -6,15 +6,15 @@ The Zenodo REST API currently supports:
 
 * **Deposit** — upload and publishing of research outputs (identical to
   functionality available in the user interface).
+* **Records** — search published records.
+* **Files** — download/upload of files.
 
 Check out the [Quickstart](#quickstart-upload) guide for an example on how to
 programmatically upload and publish your research outputs.
 
 The following REST APIs are currently in testing before we launch them in
 **beta** with full documentation:
 
-* **Records** — search published records.
-* **Files** — download/upload of files.
 * **Communities** - search communities.
 * **Funders** — search for funders.
 * **Grants** — search for grants.

source/includes/overview/_quickstart.md

@@ -4,45 +4,16 @@ This short guide will give a quick overview of how to upload and publish on
 Zenodo, and will be using Python together with the
 [Requests](http://www.python-requests.org/en/latest/user/install/) package.
 
-```terminal
-$ pip install requests
-```
-
-- First, make sure you have the
-[Requests](http://www.python-requests.org/en/latest/user/install/) module
-installed:
-
-<div class="align-columns"></div>
-
-```terminal
-$ python
-Python 2.7.5+
-[GCC 4.8.1] on linux2
-Type "help", "copyright", "credits" or "license" for more information.
-```
-- Next, fire up a Python command prompt:
-
-<div class="align-columns"></div>
-
-```python
-import requests
-```
-
-- Import the `requests` module:
-
 <div class="align-columns"></div>
 
 ```python
+>>> import requests
 >>> r = requests.get("https://zenodo.org/api/deposit/depositions")
 >>> r.status_code
 401
 >>> r.json()
 ```
 
-- Try to access the API:
-
-<div class="align-columns"></div>
-
 ```json
 {
   "message": "The server could not verify that you are authorized to access
@@ -53,12 +24,17 @@ import requests
 }
 ```
 
+- Try to access the API:
+
+<div class="align-columns"></div>
+
 - All API access requires an access token, so
 [create](https://zenodo.org/account/settings/applications/tokens/new/) one.
 
 <div class="align-columns"></div>
 
 ```python
+>>> ACCESS_TOKEN = 'ChangeMe'
 >>> r = requests.get('https://zenodo.org/api/deposit/depositions',
 ...                  params={'access_token': ACCESS_TOKEN})
 >>> r.status_code
@@ -78,8 +54,14 @@ access token):
 
 ```python
 >>> headers = {"Content-Type": "application/json"}
+>>> params = {'access_token': ACCESS_TOKEN}
 >>> r = requests.post('https://zenodo.org/api/deposit/depositions',
-...                   params={'access_token': ACCESS_TOKEN}, json={},
+...                   params=params,
+...                   json={},
+...                   # Headers are not necessary here since "requests" automatically
+...                   # adds "Content-Type: application/json", because we're using
+...                   # the "json=" keyword argument...
+...                   # headers=headers, 
 ...                   headers=headers)
 >>> r.status_code
 201
@@ -117,7 +99,69 @@ access token):
 
 <div class="align-columns"></div>
 
+- Now, let's upload a new file.  
+To do so a new API has been released, which is significantly more perfomant and which supports much larger file sizes. The old API supports 100MB per file, the new supports 50GB per file.
+
+<div class="align-columns"></div>
+
 ```python
+bucket_url = r.json()["links"]["bucket"]
+```
+
+```shell
+curl https://zenodo.org/api/deposit/depositions/222761?access_token=$ACCESS_TOKEN
+{ ...  
+  "links": { "bucket": "https://zenodo.org/api/files/568377dd-daf8-4235-85e1-a56011ad454b", ... },
+... }
+```
+
+ - In the **new files API** we use a PUT request to a 'bucket' link, which is the container for files
+bucket url looks like this: ``'https://zenodo.org/api/files/12341234-abcd-1234-abcd-0e62efee00c0'``
+
+```shell
+# This does a file stream PUT request to the "links.bucket" link
+$ curl --upload-file /path/to/your/file.dat https://zenodo.org/api/files/568377dd-daf8-4235-85e1-a56011ad454b/file.dat?access_token=$ACCES_TOKEN
+{ ... }
+```
+
+```python
+# NEW API
+filename = "my-file.zip"
+path = "/path/to/%s" % filename
+
+# We pass the file object (fp) directly to request as 'data' for stream upload
+# the target URL is the URL of the bucket and the desired filename on Zenodo seprated by slash
+with open(path, "rb") as fp:
+    r = requests.put(
+        "%s/%s" % (bucket_url, filename),
+        data=fp,
+        # No headers included in the request, since it's a raw byte request
+        params=params,
+    )
+r.json()
+```
+```json
+{
+  "mimetype": "application/pdf",
+  "updated": "2020-02-26T14:20:53.811817+00:00",
+  "links": {"self": "https://sandbox.zenodo.org/api/files/44cc40bc-50fd-4107-b347-00838c79f4c1/dummy_example.pdf",
+  "version": "https://sandbox.zenodo.org/api/files/44cc40bc-50fd-4107-b347-00838c79f4c1/dummy_example.pdf?versionId=38a724d3-40f1-4b27-b236-ed2e43200f85",
+  "uploads": "https://sandbox.zenodo.org/api/files/44cc40bc-50fd-4107-b347-00838c79f4c1/dummy_example.pdf?uploads"},
+  "is_head": true,
+  "created": "2020-02-26T14:20:53.805734+00:00",
+  "checksum": "md5:2942bfabb3d05332b66eb128e0842cff",
+  "version_id": "38a724d3-40f1-4b27-b236-ed2e43200f85",
+  "delete_marker": false,
+  "key": "dummy_example.pdf",
+  "size": 13264
+ }
+ ```
+
+<div class="align-columns"></div>
+
+
+```python
+# OLD API
 >>> # Get the deposition id from the previous response
 >>> deposition_id = r.json()['id']
 >>> data = {'name': 'myfirstfile.csv'}
@@ -128,7 +172,6 @@ access token):
 >>> r.status_code
 201
 >>> r.json()
-
 ```
 
 ```json
@@ -140,7 +183,7 @@ access token):
 }
 ```
 
-- Now, let's upload a new file:
+- Here are the instructions for the **old files API**:
 
 <div class="align-columns"></div>
 

source/includes/resources/deposit-actions/_newversion.md

@@ -16,8 +16,10 @@ curl -i -X POST https://zenodo.org/api/deposit/depositions/1234/actions/newversi
 
 ```python
 import requests
-r = requests.post('https://zenodo.org/api/deposit/depositions/1234/actions/newversion',
-                  params={'access_token': ACCESS_TOKEN})
+r = requests.post(
+    "https://zenodo.org/api/deposit/depositions/1234/actions/newversion",
+    params={"access_token": ACCESS_TOKEN},
+)
 ```
 
 #### HTTP Request

source/includes/resources/deposit-files/_create.md

@@ -1,6 +1,6 @@
 ### Create
 
-Upload a new file.
+<div class="align-columns"></div>
 
 ```shell
 curl -i https://zenodo.org/api/deposit/depositions/1234/files?access_token=ACCESS_TOKEN
@@ -19,6 +19,10 @@ files = {'file': open('path/to/local_file.csv', 'rb')}
 r = requests.post(url, data=data, files=files)
 ```
 
+Upload a new file.
+
+<div class="align-columns"></div>
+
 #### HTTP Request
 
 `POST  /api/deposit/depositions/:id/files`

source/includes/resources/deposit-files/_root.md

@@ -1,7 +1,3 @@
 ## Deposition files
 
-<aside class="notice">
-    Heads up! We will be launching a new file API which is significant more
-    performant than the current API and which supports much larger file sizes.
-    The current API supports 100MB per file, the new supports 50GB per file.
-</aside>
+About file API, the new API documentation can be found [here](#files)

source/includes/resources/files/_create.md

@@ -0,0 +1,65 @@
+### Create
+
+<div class="align-columns"></div>
+
+```shell
+curl --upload-file /path/to/your/file.dat https://zenodo.org/api/files/568377dd-daf8-4235-85e1-a56011ad454b/file.dat?access_token=$ACCESS_TOKEN
+```
+
+```python
+import json
+import requests
+
+filename = "my-file.zip"
+path = "/path/to/%s" % filename
+bucket_url = r.json()['links']['bucket']
+
+with open(path, "rb") as fp:
+     r = requests.put(
+         "%s/%s" % (bucket_url, filename),
+         data=fp,
+         # No headers included in the request, since it's a raw byte request
+         params=params,
+     )
+```
+
+```json
+{"mimetype": "application/pdf",
+ "updated": "2020-02-27T16:51:25.538105+00:00",
+ "links": {"self": "https://sandbox.zenodo.org/api/files/e68058df-573d-485a-842d-aeab42f3ffd4/dummy_example.pdf",
+  "version": "https://sandbox.zenodo.org/api/files/e68058df-573d-485a-842d-aeab42f3ffd4/dummy_example.pdf?versionId=fd204a79-49ee-4407-857b-81c60ab31d72",
+  "uploads": "https://sandbox.zenodo.org/api/files/e68058df-573d-485a-842d-aeab42f3ffd4/dummy_example.pdf?uploads"},
+ "is_head": true,
+ "created": "2020-02-27T16:51:25.526680+00:00",
+ "checksum": "md5:2942bfabb3d05332b66eb128e0842cff",
+ "version_id": "fd204a79-49ee-4407-857b-81c60ab31d72",
+ "delete_marker": false,
+ "key": "dummy_example.pdf",
+ "size": 13264}
+```
+
+Upload a new file.
+
+<div class="align-columns"></div>
+
+#### HTTP Request
+
+`PUT  /api/deposit/depositions/:id/files`
+
+#### Request headers
+
+`Content-Type: application/json`
+
+#### Scopes
+
+`deposit:write`
+
+#### Success response
+
+* **Code:** `201 Created`
+* **Body**: a [file](#files) resource.
+
+#### Error response
+
+See [HTTP status codes](#http-status-codes) (400 and 500 series errors) and
+[error responses](#errors).

source/includes/resources/files/_delete.md

@@ -0,0 +1,40 @@
+### Delete
+
+<div class="align-columns"></div>
+
+```shell
+curl -i -X DELETE https://zenodo.org/api/files/21fedcba-9876-5432-1fed-cba987654321/filename?access_token=ACCESS_TOKEN
+```
+
+```python
+r = requests.delete(
+    "%s/%s" % (bucket_url, filename),
+    params=params,
+)
+```
+
+Delete an existing deposition file resource.  
+Note, only deposition files for unpublished depositions may be deleted.
+
+<div class="align-columns"></div>
+
+#### HTTP Request
+
+`DELETE /api/files/:bucket_id/:filename`
+
+#### Scopes
+
+`deposit:write`
+
+#### Success response
+
+* **Code:** `204 No Content`
+* **Body**: Empty.
+
+#### Error response
+
+* `404 Not found`: Deposition file does not exist.
+* `403 Forbidden`: Deleting an already published deposition.
+
+See also [HTTP status codes](#http-status-codes) (400 and 500 series errors) and
+[error responses](#errors).