diff --git a/source/includes/overview/_introduction.md b/source/includes/overview/_introduction.md
index d76c6b6..08e5491 100644
--- a/source/includes/overview/_introduction.md
+++ b/source/includes/overview/_introduction.md
@@ -6,6 +6,8 @@ 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.
@@ -13,8 +15,6 @@ 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.
diff --git a/source/includes/overview/_quickstart.md b/source/includes/overview/_quickstart.md
index 884cb6d..d1e24dd 100644
--- a/source/includes/overview/_quickstart.md
+++ b/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:
-
-
-
-```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:
-
-
-
-```python
-import requests
-```
-
-- Import the `requests` module:
-
```python
+>>> import requests
>>> r = requests.get("https://zenodo.org/api/deposit/depositions")
>>> r.status_code
401
>>> r.json()
```
-- Try to access the API:
-
-
-
```json
{
"message": "The server could not verify that you are authorized to access
@@ -53,12 +24,17 @@ import requests
}
```
+- Try to access the API:
+
+
+
- All API access requires an access token, so
[create](https://zenodo.org/account/settings/applications/tokens/new/) one.
```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):
+- 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.
+
+
+
```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
+ }
+ ```
+
+
+
+
+```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**:
diff --git a/source/includes/resources/deposit-actions/_newversion.md b/source/includes/resources/deposit-actions/_newversion.md
index 14ea2df..a043d5f 100644
--- a/source/includes/resources/deposit-actions/_newversion.md
+++ b/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
diff --git a/source/includes/resources/deposit-files/_create.md b/source/includes/resources/deposit-files/_create.md
index 75e2cc4..629f1b6 100644
--- a/source/includes/resources/deposit-files/_create.md
+++ b/source/includes/resources/deposit-files/_create.md
@@ -1,6 +1,6 @@
### Create
-Upload a new file.
+
```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.
+
+
+
#### HTTP Request
`POST /api/deposit/depositions/:id/files`
diff --git a/source/includes/resources/deposit-files/_root.md b/source/includes/resources/deposit-files/_root.md
index 2489dd8..d10a82e 100644
--- a/source/includes/resources/deposit-files/_root.md
+++ b/source/includes/resources/deposit-files/_root.md
@@ -1,7 +1,3 @@
## Deposition files
-
+About file API, the new API documentation can be found [here](#files)
\ No newline at end of file
diff --git a/source/includes/resources/files/_create.md b/source/includes/resources/files/_create.md
new file mode 100644
index 0000000..f52e1ce
--- /dev/null
+++ b/source/includes/resources/files/_create.md
@@ -0,0 +1,65 @@
+### Create
+
+
+
+```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.
+
+
+
+#### 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).
diff --git a/source/includes/resources/files/_delete.md b/source/includes/resources/files/_delete.md
new file mode 100644
index 0000000..fef6f9a
--- /dev/null
+++ b/source/includes/resources/files/_delete.md
@@ -0,0 +1,40 @@
+### Delete
+
+
+
+```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.
+
+
+
+#### 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).
diff --git a/source/includes/resources/files/_list.md b/source/includes/resources/files/_list.md
new file mode 100644
index 0000000..5c15d7d
--- /dev/null
+++ b/source/includes/resources/files/_list.md
@@ -0,0 +1,94 @@
+### List
+
+List all files for a given deposition.
+
+
+
+```shell
+curl -k https://sandbox.zenodo.org/api/deposit/depositions/503451?access_token=$ACCESS_TOKEN
+{ ...
+ "links": { "bucket": "https://zenodo.org/api/files/568377dd-daf8-4235-85e1-a56011ad454b", ... },
+... }
+```
+
+```python
+r = requests.get(
+ "%s/api/deposit/depositions/503451" % url,
+ params={"access_token": ACCESS_TOKEN},
+ json={},
+ headers=headers,
+)
+bucket = r.json()['links']['bucket'].split('/')[-1]
+```
+
+- In order to list files, we need to retrieve the `bucket_id` of the deposition.
+
+
+
+```shell
+curl -k https://sandbox.zenodo.org/api/files/9a6431d2-7a70-4426-8937-7fc513c61745?access_token=$ACCESS_TOKEN
+```
+
+```python
+r = requests.get(
+ "%s/api/files/%s" % (url, bucket),
+ params={"access_token": ACCESS_TOKEN},
+ json={},
+ headers=headers,
+)
+```
+
+```json
+{"max_file_size": 50000000000,
+ "updated": "2020-02-27T13:49:38.691360+00:00",
+ "locked": true,
+ "links": {"self": "https://sandbox.zenodo.org/api/files/9a6431d2-7a70-4426-8937-7fc513c61745",
+ "uploads": "https://sandbox.zenodo.org/api/files/9a6431d2-7a70-4426-8937-7fc513c61745?uploads",
+ "versions": "https://sandbox.zenodo.org/api/files/9a6431d2-7a70-4426-8937-7fc513c61745?versions"},
+ "created": "2020-02-27T13:48:53.238371+00:00",
+ "quota_size": 50000000000,
+ "id": "9a6431d2-7a70-4426-8937-7fc513c61745",
+ "contents": [{"mimetype": "application/pdf",
+ "updated": "2020-02-27T13:48:53.661733+00:00",
+ "links": {"self": "https://sandbox.zenodo.org/api/files/9a6431d2-7a70-4426-8937-7fc513c61745/dummy_example.pdf",
+ "version": "https://sandbox.zenodo.org/api/files/9a6431d2-7a70-4426-8937-7fc513c61745/dummy_example.pdf?versionId=07b79ac5-e916-4a57-b867-32fd0be92d6d",
+ "uploads": "https://sandbox.zenodo.org/api/files/9a6431d2-7a70-4426-8937-7fc513c61745/dummy_example.pdf?uploads"},
+ "is_head": true,
+ "created": "2020-02-27T13:48:53.653459+00:00",
+ "checksum": "md5:2942bfabb3d05332b66eb128e0842cff",
+ "version_id": "07b79ac5-e916-4a57-b867-32fd0be92d6d",
+ "delete_marker": false,
+ "key": "dummy_example.pdf",
+ "size": 13264},
+ {"mimetype": "text/xml",
+ "updated": "2020-02-27T13:48:53.818217+00:00",
+ "links": {"self": "https://sandbox.zenodo.org/api/files/9a6431d2-7a70-4426-8937-7fc513c61745/dummy.xml",
+ "version": "https://sandbox.zenodo.org/api/files/9a6431d2-7a70-4426-8937-7fc513c61745/dummy.xml?versionId=2211e7f0-621c-4196-90ab-6bd3b1b3f09a",
+ "uploads": "https://sandbox.zenodo.org/api/files/9a6431d2-7a70-4426-8937-7fc513c61745/dummy.xml?uploads"},
+ "is_head": true,
+ "created": "2020-02-27T13:48:53.810332+00:00",
+ "checksum": "md5:096f5764575997fd339c16240e87f505",
+ "version_id": "2211e7f0-621c-4196-90ab-6bd3b1b3f09a",
+ "delete_marker": false,
+ "key": "dummy.xml",
+ "size": 693}],
+ "size": 13957}
+```
+
+- This allow to retrieve files contained in the bucket.
+
+
+
+#### HTTP Request
+
+`GET /api/files/:bucket_id`
+
+#### Success response
+
+* **Code:** `200 OK`
+* **Body**: an object of [files](#files) resources.
+
+#### Error response
+
+See [HTTP status codes](#http-status-codes) (400 and 500 series errors) and
+[error responses](#errors).
\ No newline at end of file
diff --git a/source/includes/resources/files/_representation.md b/source/includes/resources/files/_representation.md
new file mode 100644
index 0000000..85618b5
--- /dev/null
+++ b/source/includes/resources/files/_representation.md
@@ -0,0 +1,4 @@
+### Representation
+
+The new file API which is significant more performant than the current API and supports much larger file sizes.
+The old API supports 100MB per file, the new supports 50GB per file.
\ No newline at end of file
diff --git a/source/includes/resources/files/_retrieve.md b/source/includes/resources/files/_retrieve.md
new file mode 100644
index 0000000..8f0db1d
--- /dev/null
+++ b/source/includes/resources/files/_retrieve.md
@@ -0,0 +1,29 @@
+### Retrieve
+
+Retrieve a single deposition file.
+
+```shell
+curl -i https://zenodo.org/api/deposit/depositions/1234/files/12345678-9abc-def1-2345-6789abcdef12?access_token=ACCESS_TOKEN
+
+```
+
+```python
+import requests
+r = requests.get('https://zenodo.org/api/deposit/depositions/1234/files/12345678-9abc-def1-2345-6789abcdef12',
+ params={'access_token': ACCESS_TOKEN})
+```
+
+#### HTTP Request
+
+`GET /api/deposit/depositions/:id/files/:file_id`
+
+
+#### Success Response
+
+* **Code:** `200 OK`
+* **Body**: a [deposition file](#deposition-file) resource.
+
+#### Error response
+
+See [HTTP status codes](#http-status-codes) (400 and 500 series errors) and
+[error responses](#errors).
diff --git a/source/includes/resources/files/_root.md b/source/includes/resources/files/_root.md
new file mode 100644
index 0000000..89b2e0d
--- /dev/null
+++ b/source/includes/resources/files/_root.md
@@ -0,0 +1 @@
+## Files
\ No newline at end of file
diff --git a/source/includes/resources/files/_update.md b/source/includes/resources/files/_update.md
new file mode 100644
index 0000000..45822a2
--- /dev/null
+++ b/source/includes/resources/files/_update.md
@@ -0,0 +1 @@
+### Update
\ No newline at end of file
diff --git a/source/includes/resources/records/_list.md b/source/includes/resources/records/_list.md
new file mode 100644
index 0000000..239cee9
--- /dev/null
+++ b/source/includes/resources/records/_list.md
@@ -0,0 +1,68 @@
+### List
+
+List all open access records if no `ACCESS_TOKEN` is provided.
+Otherwise it will add the records to which the authenticate user has access.
+
+```python
+import requests
+
+response = requests.get(
+ "/api/records", params={"q": "my title", "access_token": ACCESS_TOKEN}
+)
+print(response.json())
+```
+
+```shell
+curl -i /api/records/?access_token=ACCESS_TOKEN
+```
+
+#### HTTP Request
+
+`GET /api/records/`
+
+#### Query arguments
+
+| Parameter | Required | Description |
+|:----------------------------|:---------|:-------------------------------------------------------------------------------------------------------------------------------|
+| `q`_string_ | optional | [Search query](https://help.zenodo.org/guides/search/) (using Elasticsearch query string syntax). |
+| `status`_string_ | optional | Filter result based on deposit status (either ``draft`` or ``published``) |
+| `sort`_string_ | optional | Sort order (``bestmatch`` or ``mostrecent``). Prefix with minus to change form ascending to descending (e.g. ``-mostrecent``). |
+| `page`_integer_ | optional | Page number for pagination. |
+| `size`_integer_ | optional | Number of results to return per page. |
+| `communities` _string_ | optional | Return records part of the specified communities. (Use of `community identifier`) |
+| `type` _string_ | optional | Return records part of the specified type. (`Publication`, `Poster`, `Presentation`...) |
+| `subtype` _string_ | optional | Return records part of the specified subtype. (`Journal article`, `Preprint`, `Proposal`...) |
+| `custom` _string_ | optional | Return records part of the specified custom keywords. (Format `custom=[field_name]:field_value`) |
+
+#### Header
+
+Response format of the search can be requested by specifying it in the header.
+
+| Accept | Description |
+|:------------------------------------------|:------------------|
+| `application/json` | JSON |
+| `application/ld+json` | JSON-LD |
+| `application/vnd.zenodo.v1+json` | Zenodo |
+| `application/marcxml+xml` | Marc XML |
+| `application/x-bibtex` | Bibtex |
+| `application/x-datacite+xml` | Datacite XML |
+| `application/x-dc+xml` | Dublin Core |
+| `application/dcat+xml` | DCAT XML |
+| `application/vnd.citationstyles.csl+json` | Citation JSON |
+| `application/vnd.geo+json` | Geo-JSON |
+| `application/x-datacite-v41+xml` | Datacite v4.1 XML |
+| `text/x-bibliography` | Bibliography |
+
+#### Success Response
+
+* **Code:** `200 OK`
+* **Body**: an array of [record](#records) resources.
+
+#### Error Response
+
+See [HTTP status codes](#http-status-codes) (400 and 500 series errors) and
+[error responses](#errors).
+
+#### Search guide
+
+Advanced search queries can as well be performed on Zenodo website through the search box. This is documented in the [search guide](https://help.zenodo.org/guides/search/)
\ No newline at end of file
diff --git a/source/includes/resources/records/_representation.md b/source/includes/resources/records/_representation.md
new file mode 100644
index 0000000..544d6ef
--- /dev/null
+++ b/source/includes/resources/records/_representation.md
@@ -0,0 +1,3 @@
+### Representation
+
+The Records ressource is used to search through published records.
\ No newline at end of file
diff --git a/source/includes/resources/records/_retrieve.md b/source/includes/resources/records/_retrieve.md
new file mode 100644
index 0000000..50c8bd7
--- /dev/null
+++ b/source/includes/resources/records/_retrieve.md
@@ -0,0 +1,28 @@
+### Retrieve
+
+Retrieve a single record resource.
+
+```shell
+curl -i /api/records/1234
+```
+
+```python
+import requests
+r = requests.get("/api/records/1234)
+```
+
+#### HTTP Request
+
+`GET /api/records/:id`
+
+Again, the output format of the search can be specified in the [header](#header)
+
+#### Success response
+
+* **Code:** `200 OK`
+* **Body**: a [record](#records) resource.
+
+#### Error response
+
+See [HTTP status codes](#http-status-codes) (400 and 500 series errors) and
+[error responses](#errors). |
diff --git a/source/includes/resources/records/_root.md b/source/includes/resources/records/_root.md
new file mode 100644
index 0000000..e6aa176
--- /dev/null
+++ b/source/includes/resources/records/_root.md
@@ -0,0 +1 @@
+## Records
\ No newline at end of file
diff --git a/source/index.html.md b/source/index.html.md
index 1526469..d58cee5 100644
--- a/source/index.html.md
+++ b/source/index.html.md
@@ -35,6 +35,18 @@ includes:
- resources/deposit-actions/edit
- resources/deposit-actions/discard
- resources/deposit-actions/newversion
+ - resources/records/root
+ - resources/records/representation
+ - resources/records/list
+ - resources/records/retrieve
+ - resources/files/root
+ - resources/files/representation
+ - resources/files/list
+ - resources/files/create
+ - resources/files/sort
+ - resources/files/retrieve
+ - resources/files/update
+ - resources/files/delete
- resources/licenses/root
- resources/licenses/representation
- resources/licenses/list