# /api/v3/storages/{id}
---
get:
  summary: Get a storage
  operationId: get_storage
  tags:
    - File links
  description: |-
    Gets a storage resource. As a side effect, a live connection to the storages origin is established to retrieve
    connection state data.
  parameters:
    - name: id
      description: Storage id
      in: path
      required: true
      schema:
        type: integer
      example: 1337
  responses:
    '200':
      description: OK
      content:
        application/hal+json:
          schema:
            $ref: '../components/schemas/storage_read_model.yml'
          examples:
            'Nextcloud storage':
              $ref: '../components/examples/storage-nextcloud-response.yml'
            'Freshly created Nextcloud storage':
              $ref: '../components/examples/storage-nextcloud-response-for-creation.yml'
            'OneDrive storage':
              $ref: '../components/examples/storage-one-drive-response.yml'
            'Incomplete OneDrive storage':
              $ref: '../components/examples/storage-one-drive-incomplete-response.yml'
            'Unauthorized Nextcloud storage':
              $ref: '../components/examples/storage-nextcloud-unauthorized-response.yml'
    '404':
      content:
        application/hal+json:
          schema:
            $ref: '../components/schemas/error_response.yml'
          example:
            _type: Error
            errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
            message: The requested resource could not be found.
      description: |-
        Returned if the storage does not exist or the client does not have sufficient permissions to see it.

        **Required permission:** view file links
        
patch:
  summary: Update a storage
  operationId: update_storage
  tags:
    - File links
  description: |-
    Updates a storage resource. Only data that is not generated by the server can be updated. This excludes the OAuth 2
    application data.
  parameters:
    - name: id
      description: Storage id
      in: path
      required: true
      schema:
        type: integer
      example: 1337
  requestBody:
    content:
      application/json:
        schema:
          $ref: '../components/schemas/storage_write_model.yml'
  responses:
    '200':
      description: OK
      content:
        application/hal+json:
          schema:
            $ref: '../components/schemas/storage_read_model.yml'
    '403':
      content:
        application/hal+json:
          schema:
            $ref: '../components/schemas/error_response.yml'
          example:
            _type: Error
            errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
            message: You are not authorized to access this resource.
      description: |-
        Returned if the client does not have sufficient permissions.

        **Required permission:** admin
    '404':
      content:
        application/hal+json:
          schema:
            $ref: '../components/schemas/error_response.yml'
          example:
            _type: Error
            errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
            message: The requested resource could not be found.
      description: |-
        Returned if the storage does not exist or the client does not have sufficient permissions to see it.

        **Required permission:** view file links

delete:
  summary: Delete a storage
  operationId: delete_storage
  tags:
    - File links
  description: |-
    Deletes a storage resource. This also deletes all related records, like the created oauth application, client, and
    any file links created within this storage.
  parameters:
    - name: id
      description: Storage id
      in: path
      required: true
      schema:
        type: integer
      example: 1337
  responses:
    '204':
      description: No content
    '403':
      content:
        application/hal+json:
          schema:
            $ref: '../components/schemas/error_response.yml'
          example:
            _type: Error
            errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
            message: You are not authorized to access this resource.
      description: |-
        Returned if the client does not have sufficient permissions.

        **Required permission:** admin
    '404':
      content:
        application/hal+json:
          schema:
            $ref: '../components/schemas/error_response.yml'
          example:
            _type: Error
            errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
            message: The requested resource could not be found.
      description: |-
        Returned if the storage does not exist or the client does not have sufficient permissions to see it.

        **Required permission:** view file links
