Recommend auth headers

.github/workflows/deploy.yml

@@ -10,28 +10,30 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v4
     - name: Set up Ruby
       uses: ruby/setup-ruby@v1
       with:
-        ruby-version: 2.4.2
+        ruby-version: '2.6.10'
 
-    - uses: actions/cache@v2
+    - uses: actions/cache@v4
       with:
         path: vendor/bundle
-        key: gems-${{ runner.os }}-2.4.2-${{ hashFiles('**/Gemfile.lock') }}
+        key: gems-${{ runner.os }}-2.6-${{ hashFiles('**/Gemfile.lock') }}
         restore-keys: |
-          gems-${{ runner.os }}-2.4.2-
+          gems-${{ runner.os }}-2.6-
           gems-${{ runner.os }}-
 
     - name: bundle install
       run: |
         bundle config path vendor/bundle
         bundle install --jobs 4 --retry 3
+      env:
+        BUNDLE_FORCE_RUBY_PLATFORM: true
     - run: bundle exec middleman build
 
     - name: Deploy
-      uses: peaceiris/actions-gh-pages@v3
+      uses: peaceiris/actions-gh-pages@v4
       with:
         github_token: ${{ secrets.GITHUB_TOKEN }}
         publish_dir: ./build

.github/workflows/tests.yml

@@ -11,22 +11,24 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v4
     - name: Set up Ruby
       uses: ruby/setup-ruby@v1
       with:
-        ruby-version: 2.4.2
+        ruby-version: '2.6.10'
 
-    - uses: actions/cache@v2
+    - uses: actions/cache@v4
       with:
         path: vendor/bundle
-        key: gems-${{ runner.os }}-2.4.2-${{ hashFiles('**/Gemfile.lock') }}
+        key: gems-${{ runner.os }}-2.6-${{ hashFiles('**/Gemfile.lock') }}
         restore-keys: |
-          gems-${{ runner.os }}-2.4.2-
+          gems-${{ runner.os }}-2.6-
           gems-${{ runner.os }}-
 
     - name: bundle install
       run: |
         bundle config path vendor/bundle
         bundle install --jobs 4 --retry 3
+      env:
+        BUNDLE_FORCE_RUBY_PLATFORM: true
     - run: bundle exec middleman build

.ruby-version

@@ -0,0 +1 @@
+2.6.10

Dockerfile

@@ -1,8 +1,18 @@
-FROM ruby:2.4.2-onbuild
+FROM ruby:2.6.10-alpine
+
+WORKDIR /usr/src/app
+
+# Install system dependencies
+RUN apk add --no-cache nodejs npm build-base
+
+# Copy application files
+COPY . .
+
+# Install bundler and gems
+RUN gem install bundler:1.17.2 && \
+    BUNDLE_FORCE_RUBY_PLATFORM=true bundle install
+
 VOLUME /usr/src/app/source
 EXPOSE 4567
 
-RUN apt-get update && apt-get install -y nodejs \
-&& apt-get clean && rm -rf /var/lib/apt/lists/*
-
-CMD ["bundle", "exec", "middleman", "server", "--watcher-force-polling"]
+CMD ["bundle", "exec", "middleman", "server", "--bind-address=0.0.0.0", "--watcher-force-polling"]

Gemfile

@@ -1,5 +1,7 @@
 source 'https://rubygems.org'
 
+ruby '2.6.10'
+
 # Middleman
 gem 'middleman', '~>4.1.0'
 gem 'middleman-syntax', '~> 3.0.0'

Gemfile.lock

@@ -25,7 +25,7 @@ GEM
     fast_blank (1.0.0)
     fastimage (2.0.0)
       addressable (~> 2)
-    ffi (1.9.14)
+    ffi (1.17.2)
     haml (5.1.2)
       temple (>= 0.8.0)
       tilt
@@ -120,5 +120,8 @@ DEPENDENCIES
   redcarpet (~> 3.3.2)
   rouge (~> 2.0.5)
 
+RUBY VERSION
+   ruby 2.6.10p210
+
 BUNDLED WITH
-   1.12.5
+   1.17.2

README.md

@@ -24,8 +24,7 @@ order set things up locally you're going to need:
 
 1. `git clone git@github.com:zenodo/developers.zenodo.org.git`
 2. `cd developers.zenodo.org`
-3. Initialize and start Slate. You can either do this locally, with Docker or
-   with Vagrant:
+3. Initialize and start Slate. You can either do this locally or with Docker:
 
 ```shell
 # either run this to run locally
@@ -34,10 +33,6 @@ bundle exec middleman server
 
 # OR using Docker
 docker-compose up
-
-# OR run this to run with vagrant
-vagrant up
-# (you might need to try ``vagrant provision`` first if the service doesn't start)
 ```
 
 You can now see the docs rendered at http://localhost:4567. Any modification

docker-compose.yml

@@ -1,6 +1,7 @@
-app:
-  build: .
-  ports:
-    - 4567:4567
-  volumes:
-    - ./source:/usr/src/app/source
+services:
+  app:
+    build: .
+    ports:
+      - 4567:4567
+    volumes:
+      - ./source:/usr/src/app/source

source/includes/overview/_api-basics.md

@@ -40,22 +40,22 @@ HTTP will fail. We support authentication with via OAuth 2.0.
 
 ### Using access tokens
 
-An access token must be included in all requests as either:
+An access token must be included in all requests. The recommended and more secure method is using HTTP headers:
 
 ```
-GET /api/deposit/depositions?access_token=<ACCESS_TOKEN>
+GET /api/deposit/depositions
+Authorization: Bearer <ACCESS_TOKEN>
 ```
 
-- an URL parameter (named ``access_token``):
+- **Recommended:** as HTTP request header (``Authorization``):
 
 <div class="align-columns"></div>
 
 ```
-GET /api/deposit/depositions
-Authorization: Bearer <ACCESS_TOKEN>
+GET /api/deposit/depositions?access_token=<ACCESS_TOKEN>
 ```
 
-- or as HTTP request header (``Authorization``):
+- or as URL parameter (named ``access_token``), though this is less secure:
 
 <div class="align-columns"></div>
 

source/includes/overview/_quickstart.md

@@ -88,8 +88,9 @@ axios.get("https://zenodo.org/api/deposit/depositions").then(response => {
 
 ```python
 ACCESS_TOKEN = 'ChangeMe'
+headers = {'Authorization': f'Bearer {ACCESS_TOKEN}'}
 r = requests.get('https://zenodo.org/api/deposit/depositions',
-                  params={'access_token': ACCESS_TOKEN})
+                  headers=headers)
 r.status_code
 # 200
 r.json()
@@ -99,12 +100,12 @@ r.json()
 ```javascript
 const ACCESS_TOKEN = 'ChangeMe'
 
-const requestParams = {
-  params: {
-    'access_token': ACCESS_TOKEN
+const requestConfig = {
+  headers: {
+    'Authorization': `Bearer ${ACCESS_TOKEN}`
   }
 }
-axios.get("https://zenodo.org/api/deposit/depositions", requestParams).then(response => {
+axios.get("https://zenodo.org/api/deposit/depositions", requestConfig).then(response => {
   console.log(response.status);
   // > 200
   console.log(response.data);  
@@ -124,34 +125,27 @@ access token):
 <div class="align-columns"></div>
 
 ```python
-headers = {"Content-Type": "application/json"}
-params = {'access_token': ACCESS_TOKEN}
+headers = {
+    "Content-Type": "application/json",
+    "Authorization": f"Bearer {ACCESS_TOKEN}"
+}
 r = requests.post('https://sandbox.zenodo.org/api/deposit/depositions',
-                   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
 r.json()
 ```
 
 ```javascript
-const requestParams = {
-  params: {
-    'access_token': ACCESS_TOKEN
-  },
-  headers : {
-    "Content-Type": "application/json"
+const requestConfig = {
+  headers: {
+    "Content-Type": "application/json",
+    "Authorization": `Bearer ${ACCESS_TOKEN}`
   }
 }
 
-axios.post("https://zenodo.org/api/deposit/depositions", requestParams).then(response => {
+axios.post("https://zenodo.org/api/deposit/depositions", {}, requestConfig).then(response => {
   console.log(response.status);
   // 201
   console.log(response.data);  
@@ -206,7 +200,8 @@ bucket_url = r.json()["links"]["bucket"]
 ```
 
 ```shell
-curl https://zenodo.org/api/deposit/depositions/222761?access_token=$ACCESS_TOKEN
+curl -H "Authorization: Bearer $ACCESS_TOKEN" \
+  https://zenodo.org/api/deposit/depositions/222761
 { ...
   "links": {
     "bucket": "https://zenodo.org/api/files/568377dd-daf8-4235-85e1-a56011ad454b",
@@ -223,14 +218,17 @@ This will stream the file located in '/path/to/your/file.dat' and store it in ou
 The uploaded file will be named according to the last argument in the upload URL,
 'file.dat' in our case. 
 '''
-$ curl --upload-file /path/to/your/file.dat https://zenodo.org/api/files/568377dd-daf8-4235-85e1-a56011ad454b/file.dat?access_token=$ACCES_TOKEN
+$ curl --upload-file /path/to/your/file.dat \
+  -H "Authorization: Bearer $ACCESS_TOKEN" \
+  https://zenodo.org/api/files/568377dd-daf8-4235-85e1-a56011ad454b/file.dat
 { ... }
 ```
 
 ```python
 ''' New API '''
 filename = "my-file.zip"
 path = "/path/to/%s" % filename
+headers = {'Authorization': f'Bearer {ACCESS_TOKEN}'}
 
 ''' 
 The target URL is a combination of the bucket link with the desired filename
@@ -240,7 +238,7 @@ with open(path, "rb") as fp:
     r = requests.put(
         "%s/%s" % (bucket_url, filename),
         data=fp,
-        params=params,
+        headers=headers,
     )
 r.json()
 ```
@@ -264,19 +262,17 @@ form.append('file', stream);
 // Create request
 let url = `${bucketURL}/${fileName}`;
 
-let params = { 'access_token': token }
-
 let headers = {
-    'Content-type': 'application/zip'
+    'Content-type': 'application/zip',
+    'Authorization': `Bearer ${token}`
 }
 
 const requestConfig = {
     data: {
       name: fileName,
       ...form
     },
-    headers: headers,
-    params: params
+    headers: headers
 }
 
 axios.put(url, requestConfig).then(response => {
@@ -315,8 +311,9 @@ Get the deposition id from the previous response
 deposition_id = r.json()['id']
 data = {'name': 'myfirstfile.csv'}
 files = {'file': open('/path/to/myfirstfile.csv', 'rb')}
+headers = {'Authorization': f'Bearer {ACCESS_TOKEN}'}
 r = requests.post('https://zenodo.org/api/deposit/depositions/%s/files' % deposition_id,
-                   params={'access_token': ACCESS_TOKEN}, data=data,
+                   headers=headers, data=data,
                    files=files)
 r.status_code
 # 201
@@ -350,8 +347,12 @@ data = {
                        'affiliation': 'Zenodo'}]
      }
  }
+headers = {
+    'Content-Type': 'application/json',
+    'Authorization': f'Bearer {ACCESS_TOKEN}'
+}
 r = requests.put('https://zenodo.org/api/deposit/depositions/%s' % deposition_id,
-                  params={'access_token': ACCESS_TOKEN}, data=json.dumps(data),
+                  data=json.dumps(data),
                   headers=headers)
 r.status_code
 # 200
@@ -366,8 +367,9 @@ r.status_code
 <div class="align-columns"></div>
 
 ```python
+headers = {'Authorization': f'Bearer {ACCESS_TOKEN}'}
 r = requests.post('https://zenodo.org/api/deposit/depositions/%s/actions/publish' % deposition_id,
-                      params={'access_token': ACCESS_TOKEN} )
+                      headers=headers)
 r.status_code
 # 202
 ```