docs: update with git webhooks docs

spec/components/headers/X-Github-Event.yaml

@@ -0,0 +1,3 @@
+description: event type from GitLab webhooks
+schema:
+  type: string

spec/components/headers/X-Gitlab-Event.yaml

@@ -0,0 +1,3 @@
+description: event type from GitHub webhooks
+schema:
+  type: string

spec/components/parameters/file_path.yaml

@@ -2,5 +2,5 @@ in: query
 name: file_path
 schema:
   type: string
-description: The full path (on the server) of the file
+description: The full path (on the server) of the file.
 required: true

spec/components/parameters/repo_id.yaml

@@ -0,0 +1,6 @@
+in: path
+name: repo_id
+schema:
+  type: string
+description: Repository id (from GitHub/GitLab).
+required: true

spec/openapi.yaml

@@ -58,30 +58,32 @@ externalDocs:
   url: 'https://cernanalysispreservation.readthedocs.io'
 tags:
   - name: Deposits
-    description: The Deposit resource is used for uploading and editing records on CAP
+    description: The Deposit resource is used for uploading and editing records on CAP.
   - name: Records
     description: >
       The Record resource is used for fetching and searching published records
-      on CAP. Create deposit
+      on CAP.
   - name: Files
     description: >
       The Files resource is used for uploading files and attach them to
-      records/deposits
+      records/deposits.
 
       The following type of upload are possible:
         * Local files
         * Git repos
         * URL linked files
   - name: Search
-    description: Search functionality
+    description: Search functionality.
   - name: Schemas
-    description: Operations about schemas
+    description: Operations about schemas.
   - name: JSON Schemas
-    description: Operations about schemas
+    description: Operations about schemas.
   - name: Services
-    description: Operations about services
+    description: Operations about services.
   - name: User
-    description: Operations about user
+    description: Operations about user.
+  - name: Webhooks
+    description: 'Repository webhook connection, for CAP repo updating.'
 security:
   - Access Token: []
 servers:

spec/paths/repos@event.yaml

@@ -0,0 +1,55 @@
+post:
+  tags:
+    - Webhooks
+  summary: Listen for a webhook event.
+  description: >-
+    Listen and verify that an event including repo-related payload, comes from
+    GitHub/GitLab.
+  operationId: repo_event
+  responses:
+    '200':
+      description: OK
+      headers:
+        X-Rate-Limit:
+          $ref: '#/components/headers/RateLimit'
+        X-Expires-After:
+          $ref: '#/components/headers/ExpiresAfter'
+        X-Gitlab-Event:
+          $ref: '#/components/headers/X-Gitlab-Event'
+        X-Github-Event:
+          $ref: '#/components/headers/X-Github-Event'
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              message:
+                type: string
+          examples:
+            response:
+              value:
+                message: Snapshot of repo 113545 was saved successfully.
+    '401':
+      description: Exception
+      headers:
+        X-Rate-Limit:
+          $ref: '#/components/headers/RateLimit'
+        X-Expires-After:
+          $ref: '#/components/headers/ExpiresAfter'
+        X-Gitlab-Event:
+          $ref: '#/components/headers/X-Gitlab-Event'
+        X-Github-Event:
+          $ref: '#/components/headers/X-Github-Event'
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              message:
+                type: string
+          examples:
+            response:
+              value:
+                message: >-
+                  Could not verify the event from repo 113545. No changes were
+                  made.

spec/paths/repos@{repo_id}@disable-hook.yaml

@@ -0,0 +1,45 @@
+parameters:
+  - $ref: '#/components/parameters/repo_id'
+post:
+  tags:
+    - Webhooks
+  summary: Disable a webhook
+  description: Disable a repository webhook.
+  operationId: repo_webhook_disable
+  responses:
+    '200':
+      description: OK
+      headers:
+        X-Rate-Limit:
+          $ref: '#/components/headers/RateLimit'
+        X-Expires-After:
+          $ref: '#/components/headers/ExpiresAfter'
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              message:
+                type: string
+          examples:
+            response:
+              value:
+                message: '(Host: Github) Hook 1127877 was deleted from repo 113454.'
+    '500':
+      description: Exception
+      headers:
+        X-Rate-Limit:
+          $ref: '#/components/headers/RateLimit'
+        X-Expires-After:
+          $ref: '#/components/headers/ExpiresAfter'
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              message:
+                type: string
+          examples:
+            response:
+              value:
+                message: Webhooks integration failure.

spec/paths/repos@{repo_id}@enable-hook.yaml

@@ -0,0 +1,47 @@
+parameters:
+  - $ref: '#/components/parameters/repo_id'
+post:
+  tags:
+    - Webhooks
+  summary: Enable a webhook
+  description: >-
+    Enable a repository webhook, allowing communication between the remore
+    repository and its local copy.
+  operationId: repo_webhook_enable
+  responses:
+    '200':
+      description: OK
+      headers:
+        X-Rate-Limit:
+          $ref: '#/components/headers/RateLimit'
+        X-Expires-After:
+          $ref: '#/components/headers/ExpiresAfter'
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              message:
+                type: string
+          examples:
+            response:
+              value:
+                message: '(Host: Github) Hook 1127877 was created in repo 113454.'
+    '500':
+      description: Exception
+      headers:
+        X-Rate-Limit:
+          $ref: '#/components/headers/RateLimit'
+        X-Expires-After:
+          $ref: '#/components/headers/ExpiresAfter'
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              message:
+                type: string
+          examples:
+            response:
+              value:
+                message: Webhooks integration failure.

spec/paths/repos@{repo_id}@get-snapshots.yaml

@@ -0,0 +1,42 @@
+parameters:
+  - $ref: '#/components/parameters/repo_id'
+post:
+  tags:
+    - Webhooks
+  summary: Get a list of the available snapshots of the repo.
+  description: >-
+    If a repo is connected through a webhook to GitHub/GitLab, CAP will keep an
+    archiove of the previous changes, so that the researcher can download a
+    specific commit/release.
+  operationId: repo_webhook_get_snapshots
+  responses:
+    '200':
+      description: OK
+      headers:
+        X-Rate-Limit:
+          $ref: '#/components/headers/RateLimit'
+        X-Expires-After:
+          $ref: '#/components/headers/ExpiresAfter'
+      content:
+        application/json:
+          schema:
+            type: array
+            items:
+              type: object
+              properties:
+                event:
+                  type: string
+                tag:
+                  type: string
+                branch:
+                  type: string
+                url:
+                  type: string
+          examples:
+            response:
+              value:
+                - event: push
+                  tag: 0.1
+                  branch: master
+                  url: >-
+                    https://codeload.github.com/cap/test-repo/legacy.tar.gz/c43red11