openapi: 3.0.1
info:
  title: Coscine Web Admin Pid 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: Pid
  description: Endpoints for the pids.
paths:
  /api/v2/pids/{prefix}/{suffix}:
    get:
      tags:
      - Pid
      summary: Retrieves the Persistent Identifier (PID) for a given prefix and suffix.
      operationId: GetPid
      parameters:
      - name: prefix
        in: path
        description: The PID prefix. Limited to the values provided by the API.
        required: true
        schema:
          type: string
      - name: suffix
        in: path
        description: The PID suffix of a project or a resource, represented as a GUID.
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Successful response with the PID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PidDtoResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/PidDtoResponse'
        '404':
          description: The specified PID does not exist
        '410':
          description: The PID is no longer valid (e.g., resource deleted)
  /api/v2/pids/{prefix}/{suffix}/requests:
    post:
      tags:
      - Pid
      summary: Sends an inquiry to the owner of the given PID.
      operationId: SendRequestToOwner
      parameters:
      - name: prefix
        in: path
        description: The PID prefix of a project or a resource to validate
        required: true
        schema:
          type: string
      - name: suffix
        in: path
        description: The PID body of a project or a resource to validate
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        description: The data transfer object containing the inquiry details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PidRequestDto'
          text/json:
            schema:
              $ref: '#/components/schemas/PidRequestDto'
          application/*+json:
            schema:
              $ref: '#/components/schemas/PidRequestDto'
      responses:
        '204':
          description: Email sent successfully
        '400':
          description: PID has a bad format
        '404':
          description: PID does not exist or is invalid
  /api/v2/pids:
    get:
      tags:
      - Pid
      summary: Retrieves all PIDs.
      description: <p><strong>Required JWT roles for access:</strong> <code>administrator</code>.</p>
      operationId: GetPids
      parameters:
      - name: IncludeProjects
        in: query
        description: Gets or sets a value indicating whether to include projects when retrieving pid information.
        schema:
          type: boolean
      - name: IncludeResources
        in: query
        description: Gets or sets a value indicating whether to include resources when retrieving pid information.
        schema:
          type: boolean
      - name: IncludeDeleted
        in: query
        description: Gets or sets a value indicating whether to include deleted pid information.
        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.\r\nThe order is constructed by an order string.\r\nUse the property followed by \"asc\" or \"desc\" and separate properties by commas. Default is asc.\r\nCan be used like this: \"propertyA asc, propertyB desc\"."
        schema:
          type: string
      responses:
        '200':
          description: Returns the PIDs.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PidDtoPagedResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/PidDtoPagedResponse'
        '403':
          description: User is missing authorization requirements.
    options:
      tags:
      - Pid
      summary: Responds with the HTTP methods allowed for the endpoint.
      responses:
        '200':
          description: OK
components:
  schemas:
    PidType:
      enum:
      - project
      - resource
      type: string
      description: Specifies the type of PID.
    PidDto:
      required:
      - prefix
      - suffix
      type: object
      properties:
        prefix:
          type: string
          description: Gets or sets the prefix of the PID.
        suffix:
          type: string
          description: Gets or sets the suffix of the PID.
        identifier:
          type: string
          description: Gets the constructed PID by combining the prefix and suffix ("{Prefix}/{Suffix}").
          readOnly: true
        type:
          $ref: '#/components/schemas/PidType'
        isEntityValid:
          type: boolean
          description: Gets or sets a value indicating whether the linked entity is considered valid.
      additionalProperties: false
      description: Represents a data transfer object (DTO) for a PID (Persistent Identifier).
    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.
    PidRequestDto:
      required:
      - email
      - message
      - name
      type: object
      properties:
        name:
          minLength: 1
          type: string
          description: Gets or initializes the name associated with the PID request.
        email:
          minLength: 1
          type: string
          description: Gets or initializes the email associated with the PID request.
          format: email
        message:
          maxLength: 5000
          minLength: 1
          type: string
          description: Gets or initializes the message for the PID request.
        sendConfirmationEmail:
          type: boolean
          description: Gets or initializes whether to send a confirmation email for the PID request.
      additionalProperties: false
      description: Data transfer object (DTO) representing a PID request.
    PidDtoPagedResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/PidDto'
          nullable: true
        isSuccess:
          type: boolean
          readOnly: true
        statusCode:
          type: integer
          format: int32
          nullable: true
        traceId:
          type: string
          nullable: true
        pagination:
          $ref: '#/components/schemas/Pagination'
      additionalProperties: false
    PidDtoResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/PidDto'
        isSuccess:
          type: boolean
          readOnly: true
        statusCode:
          type: integer
          format: int32
          nullable: true
        traceId:
          type: string
          nullable: true
      additionalProperties: false
  securitySchemes:
    Bearer:
      type: apiKey
      description: JWT Authorization header using the Bearer scheme.
      name: Authorization
      in: header