Document Git read API

public/api/definitions/_paths.yml

@@ -788,6 +788,11 @@
     responses:
       "200":
         description: Success
+        content:
+          application/octet-stream:
+            schema:
+              type: string
+              format: binary
       "403":
         description: Forbidden
         content:
@@ -3109,4 +3114,169 @@
       "403":
         $ref: "#/components/responses/forbidden"
       "404":
-        $ref: "#/components/responses/notFound"
+        $ref: "#/components/responses/notFound"
+"/workflows/{id}/git/{version}/tree/{path}":
+  parameters:
+    - name: id
+      in: path
+      required: true
+      description: The ID of the workflow.
+      schema:
+        type: integer
+      example: 138
+    - name: version
+      in: path
+      required: true
+      description: The version number of the workflow.
+      schema:
+        type: integer
+      example: 2
+    - name: path
+      in: path
+      required: false
+      description: The path of the tree (directory) to retrieve, or omit to get the root.
+      schema:
+        type: string
+      example: "assets/images"
+  get:
+    operationId: readGitTree
+    summary: Fetch a Git tree (directory)
+    description:
+      $ref: ../descriptions/readGitTree.md
+    tags:
+      - read
+      - git
+      - workflows
+    responses:
+      "200":
+        description: OK
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/gitTreeResponse"
+            examples:
+              response:
+                value:
+                  $ref: ../examples/gitTreeResponse.json
+      "403":
+        description: Forbidden
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/gitErrorResponse"
+      "404":
+        $ref: "#/components/responses/notFound"
+        description: Not found
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/gitErrorResponse"
+"/workflows/{id}/git/{version}/blob/{path}":
+  parameters:
+    - name: id
+      in: path
+      required: true
+      description: The ID of the workflow.
+      schema:
+        type: integer
+      example: 138
+    - name: version
+      in: path
+      required: true
+      description: The version number of the workflow.
+      schema:
+        type: integer
+      example: 2
+    - name: path
+      in: path
+      required: true
+      description: The path of the blob (file) to retrieve.
+      schema:
+        type: string
+      example: "assets/images/logo.png"
+  get:
+    operationId: readGitBlob
+    summary: Fetch a Git blob (file)
+    description:
+      $ref: ../descriptions/readGitBlob.md
+    tags:
+      - read
+      - git
+      - workflows
+    responses:
+      "200":
+        description: OK
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/gitBlobResponse"
+            examples:
+              response:
+                value:
+                  $ref: ../examples/gitBlobResponse.json
+      "403":
+        description: Forbidden
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/gitErrorResponse"
+      "404":
+        $ref: "#/components/responses/notFound"
+        description: Not found
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/gitErrorResponse"
+"/workflows/{id}/git/{version}/download/{path}":
+  parameters:
+    - name: id
+      in: path
+      required: true
+      description: The ID of the workflow.
+      schema:
+        type: integer
+      example: 138
+    - name: version
+      in: path
+      required: true
+      description: The version number of the workflow.
+      schema:
+        type: integer
+      example: 2
+    - name: path
+      in: path
+      required: true
+      description: The path of the blob (file) to download.
+      schema:
+        type: string
+      example: "assets/images/logo.png"
+  get:
+    operationId: downloadGitBlob
+    summary: Download a Git blob (file)
+    description:
+      $ref: ../descriptions/downloadGitBlob.md
+    tags:
+      - read
+      - git
+      - workflows
+    responses:
+      "200":
+        description: Success
+        content:
+          application/octet-stream:
+            schema:
+              type: string
+              format: binary
+      "403":
+        description: Forbidden
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/gitErrorResponse"
+      "404":
+        $ref: "#/components/responses/notFound"
+        description: Not found
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/gitErrorResponse"

public/api/definitions/_schemas.yml

@@ -5176,3 +5176,82 @@ workflowtool:
       $ref: "#/components/schemas/nullableNonEmptyString"
   required:
     - id
+gitTreeResponse:
+  type: object
+  description: A Git tree (directory) within a repository (or the root of the repository).
+  properties:
+    id:
+      type: string
+      description: The internal Git object ID for this tree.
+    path:
+      type: string
+      description: The full path of the tree within the repository.
+    tree:
+      type: array
+      description:
+      minItems: 0
+      items:
+        $ref: "#/components/schemas/gitTreeEntry"
+gitTreeEntry:
+  type: object
+  description: A Git object within a tree, pointing to either a blob (file) or tree (directory) using a path.
+  properties:
+    id:
+      type: string
+      description: The internal Git object ID for the file/directory pointed to by this entry.
+    name:
+      type: string
+      description: The filename of this file/directory within the current tree.
+    path:
+      type: string
+      description: The full path of the file/directory within the repository.
+    type:
+      type: string
+      description: The type of object pointed to by this entry, either a blob (file) or tree (directory).
+      enum:
+        - blob
+        - tree
+    mode:
+      type: string
+      description: UNIX mode of this entry, e.g. 100755 for an executable file etc.
+gitBlobResponse:
+  type: object
+  description: A Git blob (file) within a repository.
+  properties:
+    id:
+      type: string
+      description: The internal Git object ID for the file.
+    path:
+      type: string
+      description: The full path of the file within the repository.
+    size:
+      type: integer
+      description: The size of the file in bytes.
+    binary:
+      type: boolean
+      description: Whether this file is binary or not.
+    content:
+      type: string
+      description: The base64-encoded content of the file.
+    annotations:
+      type: array
+      minItems: 0
+      items:
+        $ref: "#/components/schemas/gitAnnotation"
+gitAnnotation:
+  type: object
+  description: An annotation on a file/directory indicating some kind of special use, e.g. to signify that this is the main workflow in a workflow repository.
+  properties:
+    key:
+      type: string
+      description: The key that indicates the type of this annotation, e.g. "main_workflow".
+    value:
+      type:
+        - 'null'
+        - string
+      description: The optional value of this annotation, e.g. in the case of a remote file, it would be the URL where the file is located.
+gitErrorResponse:
+  type: object
+  properties:
+    error:
+      type: string

public/api/descriptions/downloadGitBlob.md

@@ -0,0 +1 @@
+<a name="downloadGitBlob"></a>Download the content of the identified Git blob (file)

public/api/descriptions/readGitBlob.md

@@ -0,0 +1,3 @@
+<a name="readGitBlob"></a>A **readGitBlob** operation will return a <a href="#gitBlob">Git blob (file)</a> at a given path under a resource (e.g. a workflow), provided the authenticated user has "download" rights.
+
+The response includes some metadata about the blob (e.g. file size) as well as the base64-encoded file contents.

public/api/descriptions/readGitTree.md

@@ -0,0 +1,3 @@
+<a name="readGitTree"></a>A **readGitTree** operation will return the <a href="#gitTree">Git tree (directory)</a> at a given path (or root) of a resource (e.g. a workflow), provided the authenticated user has "download" rights. 
+
+The response includes some metadata and a listing of all the blobs (files) or subtrees (sub-directories) under the tree.

public/api/examples/gitBlobResponse.json

@@ -0,0 +1,13 @@
+{
+  "id": "5a199969223d8a17c0070cefd1c7d237aff55751",
+  "path": "sort-and-change-case.ga",
+  "size": 3862,
+  "binary": false,
+  "content": "ewogICAgInV1aWQiOiAiZTJhODU2NmMtYzAyNS00MTgxLTllOTAtN2VkMjlk\nNGU0ZGYxIiwKICAgICJ0YWdzIjogW10sCiAgICAiZm9ybWF0LXZlcnNpb24i\nOiAiMC4xIiwKICAgICJuYW1lIjogInNvcnQtYW5kLWNoYW5nZS1jYXNlIiwK\nICAgICJ2ZXJzaW9uIjogMCwKICAgICJzdGVwcyI6IHsKICAgICAgICAiMCI6\nIHsKICAgICAgICAgICAgInRvb2xfaWQiOiBudWxsLAogICAgICAgICAgICAi\ndG9vbF92ZXJzaW9uIjogbnVsbCwKICAgICAgICAgICAgIm91dHB1dHMiOiBb\nXSwKICAgICAgICAgICAgIndvcmtmbG93X291dHB1dHMiOiBbXSwKICAgICAg\nICAgICAgImlucHV0X2Nvbm5lY3Rpb25zIjoge30sCiAgICAgICAgICAgICJ0\nb29sX3N0YXRlIjogInt9IiwKICAgICAgICAgICAgImlkIjogMCwKICAgICAg\nICAgICAgInV1aWQiOiAiNWEzNmZhZDItNjZjNy00YjllLTg3NTktMGZiY2Fl\nOWI4NTQxIiwKICAgICAgICAgICAgImVycm9ycyI6IG51bGwsCiAgICAgICAg\nICAgICJuYW1lIjogIklucHV0IGRhdGFzZXQiLAogICAgICAgICAgICAibGFi\nZWwiOiAiYmVkX2lucHV0IiwKICAgICAgICAgICAgImlucHV0cyI6IFtdLAog\nICAgICAgICAgICAicG9zaXRpb24iOiB7CiAgICAgICAgICAgICAgICAidG9w\nIjogMjAwLAogICAgICAgICAgICAgICAgImxlZnQiOiAyMDAKICAgICAgICAg\nICAgfSwKICAgICAgICAgICAgImFubm90YXRpb24iOiAiIiwKICAgICAgICAg\nICAgImNvbnRlbnRfaWQiOiBudWxsLAogICAgICAgICAgICAidHlwZSI6ICJk\nYXRhX2lucHV0IgogICAgICAgIH0sCiAgICAgICAgIjEiOiB7CiAgICAgICAg\nICAgICJ0b29sX2lkIjogInNvcnQxIiwKICAgICAgICAgICAgInRvb2xfdmVy\nc2lvbiI6ICIxLjEuMCIsCiAgICAgICAgICAgICJvdXRwdXRzIjogWwogICAg\nICAgICAgICAgICAgewogICAgICAgICAgICAgICAgICAgICJ0eXBlIjogImlu\ncHV0IiwKICAgICAgICAgICAgICAgICAgICAibmFtZSI6ICJvdXRfZmlsZTEi\nCiAgICAgICAgICAgICAgICB9CiAgICAgICAgICAgIF0sCiAgICAgICAgICAg\nICJ3b3JrZmxvd19vdXRwdXRzIjogWwogICAgICAgICAgICAgICAgewogICAg\nICAgICAgICAgICAgICAgICJvdXRwdXRfbmFtZSI6ICJvdXRfZmlsZTEiLAog\nICAgICAgICAgICAgICAgICAgICJ1dWlkIjogIjgyMzdmNzFhLWJjMmEtNDk0\nZS1hNjNjLTA5YzFlNjVlZjdjOCIsCiAgICAgICAgICAgICAgICAgICAgImxh\nYmVsIjogInNvcnRlZF9iZWQiCiAgICAgICAgICAgICAgICB9CiAgICAgICAg\nICAgIF0sCiAgICAgICAgICAgICJpbnB1dF9jb25uZWN0aW9ucyI6IHsKICAg\nICAgICAgICAgICAgICJpbnB1dCI6IHsKICAgICAgICAgICAgICAgICAgICAi\nb3V0cHV0X25hbWUiOiAib3V0cHV0IiwKICAgICAgICAgICAgICAgICAgICAi\naWQiOiAwCiAgICAgICAgICAgICAgICB9CiAgICAgICAgICAgIH0sCiAgICAg\nICAgICAgICJ0b29sX3N0YXRlIjogIntcIl9fcGFnZV9fXCI6IG51bGwsIFwi\nc3R5bGVcIjogXCJcXFwiYWxwaGFcXFwiXCIsIFwiY29sdW1uXCI6IFwiXFxc\nIjFcXFwiXCIsIFwiX19yZXJ1bl9yZW1hcF9qb2JfaWRfX1wiOiBudWxsLCBc\nImNvbHVtbl9zZXRcIjogXCJbXVwiLCBcImlucHV0XCI6IFwie1xcXCJfX2Ns\nYXNzX19cXFwiOiBcXFwiUnVudGltZVZhbHVlXFxcIn1cIiwgXCJoZWFkZXJf\nbGluZXNcIjogXCJcXFwiMFxcXCJcIiwgXCJvcmRlclwiOiBcIlxcXCJBU0Nc\nXFwiXCJ9IiwKICAgICAgICAgICAgImlkIjogMSwKICAgICAgICAgICAgInV1\naWQiOiAiMGI2YjNjZGEtYzc1Zi00NTJiLTg1YjEtOGFlNGYzMzAyYmE0IiwK\nICAgICAgICAgICAgImVycm9ycyI6IG51bGwsCiAgICAgICAgICAgICJuYW1l\nIjogIlNvcnQiLAogICAgICAgICAgICAicG9zdF9qb2JfYWN0aW9ucyI6IHt9\nLAogICAgICAgICAgICAibGFiZWwiOiAic29ydCIsCiAgICAgICAgICAgICJp\nbnB1dHMiOiBbCiAgICAgICAgICAgICAgICB7CiAgICAgICAgICAgICAgICAg\nICAgIm5hbWUiOiAiaW5wdXQiLAogICAgICAgICAgICAgICAgICAgICJkZXNj\ncmlwdGlvbiI6ICJydW50aW1lIHBhcmFtZXRlciBmb3IgdG9vbCBTb3J0Igog\nICAgICAgICAgICAgICAgfQogICAgICAgICAgICBdLAogICAgICAgICAgICAi\ncG9zaXRpb24iOiB7CiAgICAgICAgICAgICAgICAidG9wIjogMjAwLAogICAg\nICAgICAgICAgICAgImxlZnQiOiA0MjAKICAgICAgICAgICAgfSwKICAgICAg\nICAgICAgImFubm90YXRpb24iOiAiIiwKICAgICAgICAgICAgImNvbnRlbnRf\naWQiOiAic29ydDEiLAogICAgICAgICAgICAidHlwZSI6ICJ0b29sIgogICAg\nICAgIH0sCiAgICAgICAgIjIiOiB7CiAgICAgICAgICAgICJ0b29sX2lkIjog\nIkNoYW5nZUNhc2UiLAogICAgICAgICAgICAidG9vbF92ZXJzaW9uIjogIjEu\nMC4wIiwKICAgICAgICAgICAgIm91dHB1dHMiOiBbCiAgICAgICAgICAgICAg\nICB7CiAgICAgICAgICAgICAgICAgICAgInR5cGUiOiAidGFidWxhciIsCiAg\nICAgICAgICAgICAgICAgICAgIm5hbWUiOiAib3V0X2ZpbGUxIgogICAgICAg\nICAgICAgICAgfQogICAgICAgICAgICBdLAogICAgICAgICAgICAid29ya2Zs\nb3dfb3V0cHV0cyI6IFsKICAgICAgICAgICAgICAgIHsKICAgICAgICAgICAg\nICAgICAgICAib3V0cHV0X25hbWUiOiAib3V0X2ZpbGUxIiwKICAgICAgICAg\nICAgICAgICAgICAidXVpZCI6ICJjMzFjZDczMy1kYWI2LTRkNTAtOWZlYy1i\nNjQ0ZDE2MjM5N2IiLAogICAgICAgICAgICAgICAgICAgICJsYWJlbCI6ICJ1\ncHBlcmNhc2VfYmVkIgogICAgICAgICAgICAgICAgfQogICAgICAgICAgICBd\nLAogICAgICAgICAgICAiaW5wdXRfY29ubmVjdGlvbnMiOiB7CiAgICAgICAg\nICAgICAgICAiaW5wdXQiOiB7CiAgICAgICAgICAgICAgICAgICAgIm91dHB1\ndF9uYW1lIjogIm91dF9maWxlMSIsCiAgICAgICAgICAgICAgICAgICAgImlk\nIjogMQogICAgICAgICAgICAgICAgfQogICAgICAgICAgICB9LAogICAgICAg\nICAgICAidG9vbF9zdGF0ZSI6ICJ7XCJfX3BhZ2VfX1wiOiBudWxsLCBcImNh\nc2luZ1wiOiBcIlxcXCJ1cFxcXCJcIiwgXCJfX3JlcnVuX3JlbWFwX2pvYl9p\nZF9fXCI6IG51bGwsIFwiY29sc1wiOiBcIlxcXCJjMVxcXCJcIiwgXCJkZWxp\nbWl0ZXJcIjogXCJcXFwiVEFCXFxcIlwiLCBcImlucHV0XCI6IFwie1xcXCJf\nX2NsYXNzX19cXFwiOiBcXFwiUnVudGltZVZhbHVlXFxcIn1cIn0iLAogICAg\nICAgICAgICAiaWQiOiAyLAogICAgICAgICAgICAidXVpZCI6ICI5Njk4YmNk\nZS0wNzI5LTQ4ZmUtYjg4ZC1jY2ZiNmY2MTUzYjQiLAogICAgICAgICAgICAi\nZXJyb3JzIjogbnVsbCwKICAgICAgICAgICAgIm5hbWUiOiAiQ2hhbmdlIENh\nc2UiLAogICAgICAgICAgICAicG9zdF9qb2JfYWN0aW9ucyI6IHt9LAogICAg\nICAgICAgICAibGFiZWwiOiAiY2hhbmdlX2Nhc2UiLAogICAgICAgICAgICAi\naW5wdXRzIjogWwogICAgICAgICAgICAgICAgewogICAgICAgICAgICAgICAg\nICAgICJuYW1lIjogImlucHV0IiwKICAgICAgICAgICAgICAgICAgICAiZGVz\nY3JpcHRpb24iOiAicnVudGltZSBwYXJhbWV0ZXIgZm9yIHRvb2wgQ2hhbmdl\nIENhc2UiCiAgICAgICAgICAgICAgICB9CiAgICAgICAgICAgIF0sCiAgICAg\nICAgICAgICJwb3NpdGlvbiI6IHsKICAgICAgICAgICAgICAgICJ0b3AiOiAy\nMDAsCiAgICAgICAgICAgICAgICAibGVmdCI6IDY0MAogICAgICAgICAgICB9\nLAogICAgICAgICAgICAiYW5ub3RhdGlvbiI6ICIiLAogICAgICAgICAgICAi\nY29udGVudF9pZCI6ICJDaGFuZ2VDYXNlIiwKICAgICAgICAgICAgInR5cGUi\nOiAidG9vbCIKICAgICAgICB9CiAgICB9LAogICAgImFubm90YXRpb24iOiAi\nIiwKICAgICJhX2dhbGF4eV93b3JrZmxvdyI6ICJ0cnVlIgp9Cg==\n",
+  "annotations": [
+    {
+      "key": "main_workflow",
+      "value": null
+    }
+  ]
+}

public/api/examples/gitTreeResponse.json

@@ -0,0 +1,41 @@
+{
+  "id": "5fdf837f5936c801529f41a8e6e83165ca118b69",
+  "path": "/",
+  "tree": [
+    {
+      "id": "68c771a099958211169377d766a7389422f5573d",
+      "name": "LICENSE",
+      "type": "blob",
+      "path": "LICENSE",
+      "mode": "100644"
+    },
+    {
+      "id": "b4fe1f3b00d26561b3b3b947b2b262abfd367b6c",
+      "name": "README.md",
+      "type": "blob",
+      "path": "README.md",
+      "mode": "100644"
+    },
+    {
+      "id": "f7769031984e005a92c34c24272d69ad3c6c808b",
+      "name": "ro-crate-metadata.json",
+      "type": "blob",
+      "path": "ro-crate-metadata.json",
+      "mode": "100644"
+    },
+    {
+      "id": "5a199969223d8a17c0070cefd1c7d237aff55751",
+      "name": "sort-and-change-case.ga",
+      "type": "blob",
+      "path": "sort-and-change-case.ga",
+      "mode": "100644"
+    },
+    {
+      "id": "b80641f610fccaabbc8330817c958729d09d7281",
+      "name": "test",
+      "type": "tree",
+      "path": "test",
+      "mode": "040000"
+    }
+  ]
+}

test/integration/api/git_api_test.rb

@@ -0,0 +1,29 @@
+require 'test_helper'
+
+class GitApiTest < ActionDispatch::IntegrationTest
+  include ApiTestHelper
+
+  def setup
+    @resource = FactoryBot.create(:ro_crate_git_workflow_with_tests)
+  end
+
+  test 'write tree example' do
+    skip unless write_examples?
+
+    user_login(@resource.contributor)
+    get workflow_git_tree_path(@resource), as: :json
+    assert_response :success
+
+    write_examples(JSON.pretty_generate(JSON.parse(response.body)), 'gitTreeResponse.json')
+  end
+
+  test 'write blob example' do
+    skip unless write_examples?
+
+    user_login(@resource.contributor)
+    get workflow_git_blob_path(@resource, path: 'sort-and-change-case.ga'), as: :json
+    assert_response :success
+
+    write_examples(JSON.pretty_generate(JSON.parse(response.body)), 'gitBlobResponse.json')
+  end
+end