RWTH Aachen University Tree API

openapi: 3.2.0
info:
  title: Coscine Web Admin Tree API
  description: Coscine (short for <b>CO</b>llaborative <b>SC</b>ientific <b>IN</b>tegration <b>E</b>nvironment) is the research data management platform for your research project.
  termsOfService: https://about.coscine.de/en/termsofuse/
  contact:
    name: Coscine Team
    email: servicedesk@rwth-aachen.de
  version: '2.0'
servers:
- url: https://coscine.rwth-aachen.de/coscine
security:
- Bearer: []
tags:
- name: Tree
  description: Endpoints for the file and metadata trees.
paths:
  /api/v2/projects/{projectId}/resources/{resourceId}/trees/files:
    get:
      tags:
      - Tree
      summary: Retrieves the file tree associated with a resource.
      description: The `OrderBy` query is currently not supported.
      operationId: GetFileTree
      parameters:
      - name: projectId
        in: path
        description: The unique identifier or slug of the project.
        required: true
        schema:
          type: string
      - name: resourceId
        in: path
        description: The unique identifier of the resource.
        required: true
        schema:
          type: string
          format: uuid
      - name: Path
        in: query
        description: Gets or sets the path of the file tree.
        schema:
          type: string
      - name: PageNumber
        in: query
        description: Gets or sets the desired page number. Should be greater than or equal to 1. Default is 1.
        schema:
          type: integer
          format: int32
      - name: PageSize
        in: query
        description: Gets or sets the desired page size. Should be between 1 and the maximum allowed page size (50). Default is 10.
        schema:
          type: integer
          format: int32
      - name: OrderBy
        in: query
        description: 'Gets or sets the field name used for ordering the results.

          The order is constructed by an order string.

          Use the property followed by "asc" or "desc" and separate properties by commas. Default is asc.

          Can be used like this: "propertyA asc, propertyB desc".'
        schema:
          type: string
      responses:
        '200':
          description: Returns the file tree of a resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileTreeDtoPagedResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/FileTreeDtoPagedResponse'
        '403':
          description: User is missing authorization requirements.
        '400':
          description: Provided input has a bad format.
        '404':
          description: Project does not exist or has been deleted.
      deprecated: true
  /api/v2/projects/{projectId}/resources/{resourceId}/trees/metadata:
    get:
      tags:
      - Tree
      summary: Retrieves the metadata tree associated with a resource.
      operationId: GetMetadataTree
      parameters:
      - name: projectId
        in: path
        description: The unique identifier or slug of the project.
        required: true
        schema:
          type: string
      - name: resourceId
        in: path
        description: The unique identifier of the resource.
        required: true
        schema:
          type: string
          format: uuid
      - name: Path
        in: query
        description: Gets or sets the path of the metadata tree.
        schema:
          type: string
      - name: Format
        in: query
        description: Gets or sets the format of the RDF data.
        schema:
          $ref: '#/components/schemas/RdfFormat'
      - name: IncludeExtractedMetadata
        in: query
        description: Gets or sets if extracted metadata should be included.
        schema:
          type: boolean
      - name: IncludeProvenance
        in: query
        description: Gets or sets if provenance metadata should be included.
        schema:
          type: boolean
      - name: PageNumber
        in: query
        description: Gets or sets the desired page number. Should be greater than or equal to 1. Default is 1.
        schema:
          type: integer
          format: int32
      - name: PageSize
        in: query
        description: Gets or sets the desired page size. Should be between 1 and the maximum allowed page size (50). Default is 10.
        schema:
          type: integer
          format: int32
      - name: OrderBy
        in: query
        description: 'Gets or sets the field name used for ordering the results.

          The order is constructed by an order string.

          Use the property followed by "asc" or "desc" and separate properties by commas. Default is asc.

          Can be used like this: "propertyA asc, propertyB desc".'
        schema:
          type: string
      responses:
        '200':
          description: Returns the metadata tree of a resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetadataTreeDtoPagedResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/MetadataTreeDtoPagedResponse'
        '403':
          description: User is missing authorization requirements.
        '400':
          description: Provided input has a bad format.
        '404':
          description: Project does not exist or has been deleted.
      deprecated: true
    post:
      tags:
      - Tree
      summary: Creates a new metadata tree for a resource.
      operationId: CreateMetadataTree
      parameters:
      - name: projectId
        in: path
        description: The unique identifier or slug of the project.
        required: true
        schema:
          type: string
      - name: resourceId
        in: path
        description: The unique identifier of the resource.
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        description: The metadata tree data for creation.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MetadataTreeForCreationDto'
          text/json:
            schema:
              $ref: '#/components/schemas/MetadataTreeForCreationDto'
          application/*+json:
            schema:
              $ref: '#/components/schemas/MetadataTreeForCreationDto'
      responses:
        '201':
          description: Metadata tree created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetadataTreeDtoResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/MetadataTreeDtoResponse'
        '403':
          description: User is missing authorization requirements.
        '400':
          description: Provided input has a bad format.
        '404':
          description: Provided input refers to entries that do not exist or have been deleted.
      deprecated: true
    put:
      tags:
      - Tree
      summary: Updates an existing metadata tree of a resource.
      operationId: UpdateMetadataTree
      parameters:
      - name: projectId
        in: path
        description: The unique identifier or slug of the project.
        required: true
        schema:
          type: string
      - name: resourceId
        in: path
        description: The unique identifier of the resource.
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        description: The updated metadata tree data.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MetadataTreeForUpdateDto'
          text/json:
            schema:
              $ref: '#/components/schemas/MetadataTreeForUpdateDto'
          application/*+json:
            schema:
              $ref: '#/components/schemas/MetadataTreeForUpdateDto'
      responses:
        '204':
          description: Metadata tree updated.
        '403':
          description: User is missing authorization requirements.
        '400':
          description: Provided input has a bad format or the resource is write-protected due to its archived status.
        '404':
          description: Provided input refers to entries that do not exist or have been deleted.
      deprecated: true
    delete:
      tags:
      - Tree
      summary: Deletes (invalidates) a metadata tree associated with a resource.
      description: <p><strong>Required JWT roles for access:</strong> <code>administrator</code>.</p>
      operationId: DeleteMetadataTree
      parameters:
      - name: projectId
        in: path
        description: The unique identifier or slug of the project.
        required: true
        schema:
          type: string
      - name: resourceId
        in: path
        description: The unique identifier of the resource.
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        description: The dto for the deletion.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MetadataTreeForDeletionDto'
          text/json:
            schema:
              $ref: '#/components/schemas/MetadataTreeForDeletionDto'
          application/*+json:
            schema:
              $ref: '#/components/schemas/MetadataTreeForDeletionDto'
      responses:
        '204':
          description: Metadata tree deleted.
        '403':
          description: User is missing authorization requirements.
        '400':
          description: Provided input has a bad format or the resource is write-protected due to its archived status.
        '404':
          description: Provided input refers to entries that do not exist or have been deleted.
      deprecated: true
  /api/v2/projects/{projectId}/resources/{resourceId}/trees/metadata/specific:
    get:
      tags:
      - Tree
      summary: Retrieves the specific metadata tree associated with a resource.
      operationId: GetSpecificMetadataTree
      parameters:
      - name: projectId
        in: path
        description: The unique identifier or slug of the project.
        required: true
        schema:
          type: string
      - name: resourceId
        in: path
        description: The unique identifier of the resource.
        required: true
        schema:
          type: string
          format: uuid
      - name: Path
        in: query
        description: Gets or sets the path of the metadata tree.
        required: true
        schema:
          type: string
      - name: Format
        in: query
        description: Gets or sets the format of the RDF data.
        schema:
          $ref: '#/components/schemas/RdfFormat'
      - name: IncludeExtractedMetadata
        in: query
        description: Gets or sets if extracted metadata should be included.
        schema:
          type: boolean
      - name: IncludeProvenance
        in: query
        description: Gets or sets if provenance should be included.
        schema:
          type: boolean
      - name: Version
        in: query
        description: 'Gets or sets the desired version.

          If the version is null, the newest will be returned.'
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: Returns the specific metadata tree of a resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetadataTreeDtoResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/MetadataTreeDtoResponse'
        '403':
          description: User is missing authorization requirements.
        '400':
          description: Provided input has a bad format.
        '404':
          description: Project does not exist or has been deleted.
      deprecated: true
  /api/v2/projects/{projectId}/resources/{resourceId}/trees/metadata/extracted:
    post:
      tags:
      - Tree
      summary: Creates a new extracted metadata tree for a resource.
      description: <p><strong>Required JWT roles for access:</strong> <code>administrator</code>.</p>
      operationId: CreateExtractedMetadataTree
      parameters:
      - name: projectId
        in: path
        description: The unique identifier or slug of the project.
        required: true
        schema:
          type: string
      - name: resourceId
        in: path
        description: The unique identifier of the resource.
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        description: The metadata tree data for creation.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExtractedMetadataTreeForCreationDto'
          text/json:
            schema:
              $ref: '#/components/schemas/ExtractedMetadataTreeForCreationDto'
          application/*+json:
            schema:
              $ref: '#/components/schemas/ExtractedMetadataTreeForCreationDto'
      responses:
        '201':
          description: Extracted Metadata tree created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetadataTreeDtoResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/MetadataTreeDtoResponse'
        '403':
          description: User is missing authorization requirements.
        '400':
          description: Provided input has a bad format.
        '404':
          description: Provided input refers to entries that do not exist or have been deleted.
      deprecated: true
    put:
      tags:
      - Tree
      summary: Updates an existing metadata tree of a resource.
      description: <p><strong>Required JWT roles for access:</strong> <code>administrator</code>.</p>
      operationId: UpdateExtractedMetadataTree
      parameters:
      - name: projectId
        in: path
        description: The unique identifier or slug of the project.
        required: true
        schema:
          type: string
      - name: resourceId
        in: path
        description: The unique identifier of the resource.
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        description: The updated metadata tree data.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExtractedMetadataTreeForUpdateDto'
          text/json:
            schema:
              $ref: '#/components/schemas/ExtractedMetadataTreeForUpdateDto'
          application/*+json:
            schema:
              $ref: '#/components/schemas/ExtractedMetadataTreeForUpdateDto'
      responses:
        '204':
          description: Metadata tree updated.
        '403':
          description: User is missing authorization requirements.
        '400':
          description: Provided input has a bad format or the resource is write-protected due to its archived status.
        '404':
          description: Provided input refers to entries that do not exist or have been deleted.
      deprecated: true
  /api/v2/projects/{projectId}/resources/{resourceId}/trees:
    options:
      tags:
      - Tree
      summary: Responds with the HTTP methods allowed for the endpoint.
      parameters:
      - name: projectId
        in: path
        required: true
        schema:
          type: string
      - name: resourceId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
components:
  schemas:
    FileActionDto:
      type: object
      properties:
        url:
          type: string
          description: Gets or sets the presigned URL associated with the file action.
          format: uri
        method:
          $ref: '#/components/schemas/FileActionHttpMethod'
      additionalProperties: false
      description: Represents a Data Transfer Object (DTO) for file actions, including the URL and HTTP method.
    MetadataTreeDtoPagedResponse:
      type: object
      properties:
        data:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/MetadataTreeDto'
        isSuccess:
          type: boolean
          readOnly: true
        statusCode:
          type:
          - integer
          - 'null'
          format: int32
        traceId:
          type:
          - string
          - 'null'
        pagination:
          $ref: '#/components/schemas/Pagination'
      additionalProperties: false
    ProvenanceDto:
      required:
      - id
      - variants
      - wasRevisionOf
      type: object
      properties:
        id:
          type: string
          description: Gets or sets the id of the current metadata graph.
          format: uri
        generatedAt:
          type:
          - string
          - 'null'
          description: Gets or sets the date and time when the metadata was generated.
          format: date-time
        wasRevisionOf:
          type: array
          items:
            type: string
            format: uri
          description: Gets or sets the adapted versions from the specific metadata tree.
        variants:
          type: array
          items:
            $ref: '#/components/schemas/VariantDto'
          description: Gets or sets the variants of the specific metadata tree.
        similarityToLastVersion:
          type:
          - number
          - 'null'
          description: The similarity to the last version.
          format: double
        wasInvalidatedBy:
          type:
          - string
          - 'null'
          description: Information if the specific metadata tree was invalidated by something.
          format: uri
        hashParameters:
          $ref: '#/components/schemas/HashParametersDto'
      additionalProperties: false
      description: Represents a data transfer object (DTO) for provenance information.
    RdfDefinitionForManipulationDto:
      required:
      - content
      - type
      type: object
      properties:
        content:
          minLength: 1
          type: string
          description: The content of the RDF definition.
        type:
          $ref: '#/components/schemas/RdfFormat'
      additionalProperties: false
      description: Represents the data transfer object (DTO) used for manipulating RDF definitions.
    FileTreeDtoPagedResponse:
      type: object
      properties:
        data:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/FileTreeDto'
        isSuccess:
          type: boolean
          readOnly: true
        statusCode:
          type:
          - integer
          - 'null'
          format: int32
        traceId:
          type:
          - string
          - 'null'
        pagination:
          $ref: '#/components/schemas/Pagination'
      additionalProperties: false
    RdfFormat:
      enum:
      - text/turtle
      - application/ld+json
      - application/x-trig
      - application/n-quads
      type: string
      description: Specifies the RDF <i>(Resource Description Framework)</i> format.
    TreeDataType:
      enum:
      - Tree
      - Leaf
      type: string
      description: Represents the types of nodes within a hierarchical tree structure.
    MetadataTreeExtractedDto:
      type: object
      properties:
        path:
          type: string
          description: Gets the path of the tree item.
        type:
          $ref: '#/components/schemas/TreeDataType'
        metadataId:
          type: string
          description: Gets the identifier of the metadata extraction graph.
          format: uri
        rawDataId:
          type:
          - string
          - 'null'
          description: Gets the identifier of the raw data extraction graph.
          format: uri
        definition:
          $ref: '#/components/schemas/RdfDefinitionDto'
      additionalProperties: false
      description: Represents a data transfer object (DTO) for extracted metadata within a tree structure, extending the base TreeDto.
    FileTreeDto:
      type: object
      properties:
        path:
          type: string
          description: Gets the path of the tree item.
        type:
          $ref: '#/components/schemas/TreeDataType'
        directory:
          type: string
          description: Gets or sets the directory of the file.
        name:
          type: string
          description: Gets or sets the name of the file.
        extension:
          type: string
          description: Gets or sets the extension of the file.
        size:
          type: integer
          description: Gets or sets the size of the file in bytes.
          format: int64
        creationDate:
          type:
          - string
          - 'null'
          description: Gets or sets the creation date of the file.
          format: date-time
        changeDate:
          type:
          - string
          - 'null'
          description: Gets or sets the last change date of the file.
          format: date-time
        actions:
          $ref: '#/components/schemas/FileActionsDto'
        hidden:
          type: boolean
          description: Determines if the specific tree entry is hidden.
      additionalProperties: false
      description: Represents a Data Transfer Object (DTO) for a file within a tree structure, extending the base TreeDto.
    ProvenanceParametersDto:
      type: object
      properties:
        wasRevisionOf:
          type: array
          items:
            type: string
            format: uri
          description: Gets or sets the adapted versions from the specific metadata tree.
        variants:
          type: array
          items:
            $ref: '#/components/schemas/VariantDto'
          description: Gets or sets the variants of the specific metadata tree.
        wasInvalidatedBy:
          type:
          - string
          - 'null'
          description: Information if the specific metadata tree was invalidated by something.
          format: uri
        similarityToLastVersion:
          type:
          - number
          - 'null'
          description: The similarity to the last version.
          format: double
        metadataExtractorVersion:
          type:
          - string
          - 'null'
          description: Gets or initializes the version of the metadata extractor.
        hashParameters:
          $ref: '#/components/schemas/HashParametersDto'
      additionalProperties: false
      description: Data transfer object (DTO) representing Provenance Parameters in a request.
    Pagination:
      type: object
      properties:
        currentPage:
          type: integer
          description: Gets or sets the current page number.
          format: int32
        totalPages:
          type: integer
          description: Gets or sets the total number of pages.
          format: int32
        pageSize:
          type: integer
          description: Gets or sets the number of items per page.
          format: int32
        totalCount:
          type: integer
          description: Gets or sets the total count of items across all pages.
          format: int64
        hasPrevious:
          type: boolean
          description: Gets a value indicating whether there is a previous page.
          readOnly: true
        hasNext:
          type: boolean
          description: Gets a value indicating whether there is a next page.
          readOnly: true
      additionalProperties: false
      description: Represents pagination information for a collection of items.
    VariantDto:
      type: object
      properties:
        graphName:
          type: string
          description: Name of the graph.
          format: uri
        similarity:
          type: number
          description: Similarity value 0-1
          format: double
      additionalProperties: false
      description: Represents the variants of this specific metadata tree.
    HashParametersDto:
      required:
      - algorithmName
      - value
      type: object
      properties:
        algorithmName:
          minLength: 1
          type: string
          description: Gets or initializes the hash algorithm name.
        value:
          minLength: 1
          type: string
          description: Gets or initializes the hash value.
      additionalProperties: false
      description: Data transfer object (DTO) representing Hash Parameters in a request.
    ExtractedMetadataTreeForUpdateDto:
      required:
      - definition
      - id
      - path
      - provenance
      type: object
      properties:
        path:
          minLength: 1
          type: string
          description: Gets or initializes the path of the metadata tree.
        id:
          type: string
          description: Gets or sets the id of the to update metadata tree.
          format: uri
        definition:
          $ref: '#/components/schemas/RdfDefinitionForManipulationDto'
        provenance:
          $ref: '#/components/schemas/ProvenanceParametersDto'
        forceNewMetadataVersion:
          type: boolean
          description: Gets or initializes a flag for creating a new metadata version.
      additionalProperties: false
      description: 'Data transfer object (DTO) representing the update of a metadata tree.

        Inherits from the base class Coscine.Api.Core.Shared.DataTransferObjects.ParameterObjects.MetadataTreeForManipulationDto.'
    MetadataTreeDto:
      type: object
      properties:
        path:
          type: string
          description: Gets the path of the tree item.
        type:
          $ref: '#/components/schemas/TreeDataType'
        id:
          type: string
          description: Gets or sets the id of the specific metadata tree.
          format: uri
        version:
          type: string
          description: Gets or sets the version associated with the metadata.
        availableVersions:
          type: array
          items:
            type: string
          description: Gets or sets the collection of available versions related to the metadata.
        definition:
          $ref: '#/components/schemas/RdfDefinitionDto'
        extracted:
          $ref: '#/components/schemas/MetadataTreeExtractedDto'
        provenance:
          $ref: '#/components/schemas/ProvenanceDto'
      additionalProperties: false
      description: Represents a data transfer object (DTO) for metadata within a tree structure, extending the base TreeDto.
    FileActionHttpMethod:
      enum:
      - GET
      - POST
      - PUT
      - DELETE
      type: string
      description: Represents the possible HTTP methods associated with file actions.
    MetadataTreeDtoResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/MetadataTreeDto'
        isSuccess:
          type: boolean
          readOnly: true
        statusCode:
          type:
          - integer
          - 'null'
          format: int32
        traceId:
          type:
          - string
          - 'null'
      additionalProperties: false
    MetadataTreeForUpdateDto:
      required:
      - definition
      - path
      type: object
      properties:
        path:
          minLength: 1
          type: string
          description: Gets or initializes the path of the metadata tree.
        definition:
          $ref: '#/components/schemas/RdfDefinitionForManipulationDto'
      additionalProperties: false
      description: 'Data transfer object (DTO) representing the update of a metadata tree.

        Inherits from the base class Coscine.Api.Core.Shared.DataTransferObjects.ParameterObjects.MetadataTreeForManipulationDto.'
    ExtractedMetadataTreeForCreationDto:
      required:
      - definition
      - id
      - path
      - provenance
      type: object
      properties:
        path:
          minLength: 1
          type: string
          description: Gets or initializes the path of the metadata tree.
        id:
          type: string
          description: Gets or sets the id of the new metadata tree.
          format: uri
        definition:
          $ref: '#/components/schemas/RdfDefinitionForManipulationDto'
        provenance:
          $ref: '#/components/schemas/ProvenanceParametersDto'
      additionalProperties: false
      description: 'Data transfer object (DTO) representing the creation of a metadata tree.

        Extends the base class Coscine.Api.Core.Shared.DataTransferObjects.ParameterObjects.MetadataTreeForManipulationDto.'
    MetadataTreeForDeletionDto:
      required:
      - invalidatedBy
      - path
      - version
      type: object
      properties:
        path:
          minLength: 1
          type: string
          description: Gets or initializes the path of the metadata tree.
        version:
          type: integer
          description: Gets or initializes the version of the metadata tree to be deleted.
          format: int64
        invalidatedBy:
          type: string
          description: Gets or initializes the invalidation entity.
          format: uri
      additionalProperties: false
      description: Data transfer object (DTO) for deleting a specific version of metadata.
    RdfDefinitionDto:
      type: object
      properties:
        content:
          type:
          - string
          - 'null'
          description: The content of the RDF definition.
        type:
          type:
          - string
          - 'null'
          description: The type of the RDF definition.
      additionalProperties: false
      description: Represents a Data Transfer Object (DTO) for RDF (Resource Description Framework) definition details.
    FileActionsDto:
      type: object
      properties:
        download:
          $ref: '#/components/schemas/FileActionDto'
      additionalProperties: false
      description: Represents a Data Transfer Object (DTO) for a collection of file actions, including download action details.
    MetadataTreeForCreationDto:
      required:
      - definition
      - path
      type: object
      properties:
        path:
          minLength: 1
          type: string
          description: Gets or initializes the path of the metadata tree.
        definition:
          $ref: '#/components/schemas/RdfDefinitionForManipulationDto'
      additionalProperties: false
      description: 'Data transfer object (DTO) representing the creation of a metadata tree.

        Extends the base class Coscine.Api.Core.Shared.DataTransferObjects.ParameterObjects.MetadataTreeForManipulationDto.'
  securitySchemes:
    Bearer:
      type: apiKey
      description: JWT Authorization header using the Bearer scheme.
      name: Authorization
      in: header