University of Padua object-advanced API

openapi: 3.0.2
info:
  description: Documentation of the PHAIDRA API.
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  title: PHAIDRA datastream object-advanced API
  version: '3.0'
servers:
- description: API endpoint
  url: https://phaidra.unipd.it/api
tags:
- description: Additional requests for the manipulation of digital objects
  name: object-advanced
paths:
  /authz/check/{pid}/{op}:
    get:
      description: Checks if the authenticated user has appropriate rights for an operation on the object (readable/writable). Can also be checked for unauthenticated user.
      parameters:
      - description: pid - object id
        in: path
        name: pid
        schema:
          required: false
          type: string
      - description: rights for operation
        in: path
        name: op
        schema:
          enum:
          - ro
          - rw
          required: true
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  alerts:
                    items:
                      properties:
                        msg:
                          type: string
                        type:
                          type: string
                      type: object
                    type: array
                  status:
                    type: string
                type: object
          description: readable/writable, depending on parameter 'op'. This method can be used to check if an object is readable/writable. The authentication is optional, as you might want to know if an object is readable for an unauthenticated user. An object is never writable for an unauthenticated user, so checking 'rw' only makes sense with authentication. Typically, an object is only writable for its owner.
        '403':
          content:
            application/json:
              schema:
                properties:
                  alerts:
                    items:
                      properties:
                        msg:
                          type: string
                        type:
                          type: string
                      type: object
                    type: array
                  status:
                    type: string
                type: object
          description: not op
      security:
      - basicAuth: []
      summary: Checks rights
      tags:
      - object-advanced
  '/index ':
    post:
      description: Post a list of objects which should be re-indexed - needs admin credentials
      responses:
        '200':
          content:
            application/json:
              schema: {}
          description: object info
      security:
      - basicAuth: []
      summary: Re-index multiple objects at once
      tags:
      - object-advanced
  /object/create:
    post:
      requestBody:
        content:
          multipart/form-data:
            schema:
              properties:
                file:
                  format: binary
                  required: true
                  type: string
                metadata:
                  description: a structure containing metadata; refer to the wiki (see above) for further details
                  example:
                    json-ld:
                      dce:title:
                      - '@type': bf:Title
                        bf:mainTitle:
                        - '@language': deu
                          '@value': Title
                      edm:rights:
                      - https://rightsstatements.org/page/InC/1.0/
                      role:aut:
                      - '@type': schema:Person
                        schema:familyName:
                        - '@value': Last Name
                        schema:givenName:
                        - '@value': First name
                  required: true
                  type: object
                mimetype:
                  description: 'mimetype is optional: if not provided, heuristics is used on server side'
                  example: application/json
                  required: false
                  type: string
              type: object
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  alerts:
                    items:
                      properties:
                        msg:
                          type: string
                        type:
                          type: string
                      type: object
                    type: array
                  pid:
                    type: string
                  status:
                    type: number
                type: object
          description: empty object created
        '404':
          content:
            application/json:
              schema:
                type: object
          description: error creating object
      security:
      - basicAuth: []
      summary: Create empty object, without a specified cmodel
      tags:
      - object-advanced
  /object/create/{cmodel}:
    post:
      parameters:
      - description: object cmodel
        in: path
        name: cmodel
        schema:
          enum:
          - cmodel:Picture
          - cmodel:PDFDocument
          - cmodel:Video
          - cmodel:Audio
          - cmodel:Collection
          - cmodel:Asset
          - cmodel:Container
          - cmodel:Paper
          - cmodel:Collection
          - cmodel:LaTeXDocument
          - cmodel:Resource
          - cmodel:Book
          - cmodel:Page
          required: true
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  alerts:
                    items:
                      properties:
                        msg:
                          type: string
                        type:
                          type: string
                      type: object
                    type: array
                  pid:
                    type: string
                  status:
                    type: number
                type: object
          description: empty object created
        '404':
          content:
            application/json:
              schema:
                type: object
          description: error creating object
      security:
      - basicAuth: []
      summary: Create empty object, with cmodel
      tags:
      - object-advanced
  /object/{pid}/annotations:
    get:
      description: Retrieve annotations datastream.
      parameters:
      - description: the requested object id
        in: path
        name: pid
        schema:
          required: true
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  alerts:
                    items:
                      properties:
                        msg:
                          type: string
                        type:
                          type: string
                      type: object
                    type: array
                  annotations:
                    $ref: '#/components/schemas/annotations'
                  status:
                    type: string
                type: object
          description: JSON with annotations (saved as XML but currently only returned as JSON)
        '404':
          content:
            application/json:
              schema:
                type: object
          description: Failed to fetch data
      summary: Get annotations.
      tags:
      - object-advanced
    post:
      description: This method can save annotations to an object. The format chosen is taken from IIPMooViewer.
      parameters:
      - description: object pid
        in: path
        name: pid
        schema:
          required: true
          type: string
      requestBody:
        content:
          multipart/form-data:
            schema:
              properties:
                metadata:
                  $ref: '#/components/schemas/annotations'
              type: object
        description: Adds annotation JSON. See datastream examples for the [annotations.json](https://github.com/phaidra/phaidra-api/wiki/Annotations).
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  alerts:
                    items:
                      properties:
                        msg:
                          type: string
                        type:
                          type: string
                      type: object
                    type: array
                  status:
                    type: string
                type: object
          description: Annotation saved
      security:
      - basicAuth: []
      summary: Saves annotations.
      tags:
      - object-advanced
  /object/{pid}/cmodel:
    get:
      description: Returns the object cmodel
      parameters:
      - description: object id
        in: path
        name: pid
        schema:
          required: true
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  alerts:
                    items:
                      properties:
                        msg:
                          type: string
                        type:
                          type: string
                      type: object
                    type: array
                  cmodel:
                    type: string
                  status:
                    type: number
                type: object
          description: cmodel (e.g. collection)
      summary: Get cmodel
      tags:
      - object-advanced
  /object/{pid}/data:
    post:
      parameters:
      - description: object pid
        in: path
        name: pid
        schema:
          required: true
          type: string
      - description: object mimetype
        in: query
        name: mimetype
        schema:
          required: false
          type: string
      requestBody:
        content:
          multipart/form-data:
            schema:
              properties:
                file:
                  format: binary
                  type: string
              type: object
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  alerts:
                    items:
                      properties:
                        msg:
                          type: string
                        type:
                          type: string
                      type: object
                    type: array
                  pid:
                    type: string
                  status:
                    type: number
                type: object
          description: data added to object
        '404':
          content:
            application/json:
              schema:
                type: object
          description: error
      security:
      - basicAuth: []
      summary: Replace data (add a new version of OCTETS datastream)
      tags:
      - object-advanced
  /object/{pid}/datacite:
    get:
      parameters:
      - description: object id
        in: path
        name: pid
        schema:
          required: true
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  alerts:
                    items:
                      properties:
                        msg:
                          type: string
                        type:
                          type: string
                      type: object
                    type: array
                  datacite:
                    $ref: '#/components/schemas/datacite'
                  status:
                    type: string
                type: object
          description: DataCite metadata
        '404':
          content:
            application/json:
              schema:
                type: object
          description: Failed to fetch data
      summary: Transforms metadata to DataCite.
      tags:
      - object-advanced
  /object/{pid}/datastream/{dsid}:
    post:
      parameters:
      - description: the requested object id
        in: path
        name: pid
        schema:
          required: true
          type: string
      - description: datastream id
        example: IIIF-MANIFEST
        in: path
        name: dsid
        schema:
          required: true
          type: string
      requestBody:
        content:
          multipart/form-data:
            schema:
              properties:
                controlgroup:
                  description: One of X, M, R, or E (Inline XML, Managed Content, Redirect, or External Referenced)
                  enum:
                  - X
                  - M
                  - R
                  - E
                  required: true
                  type: string
                dscontent:
                  format: binary
                  type: string
                dslabel:
                  description: For OCTETS datastream it should be the original filename (e.g. my_test.pdf). For other datastreams any string, it's not used by PHAIDRA.
                  required: false
                  type: string
                location:
                  description: location of managed or external datastream content
                  required: false
                  type: string
                mimetype:
                  example: application/json
                  required: false
                  type: string
              type: object
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  alerts:
                    items:
                      properties:
                        msg:
                          type: string
                        type:
                          type: string
                      type: object
                    type: array
                  status:
                    type: string
                type: object
          description: Datastream added or modified
        '404':
          content:
            application/json:
              schema:
                type: object
          description: Failed to fetch data
      security:
      - basicAuth: []
      summary: Add or modify datastream
      tags:
      - object-advanced
  /object/{pid}/fulltext:
    get:
      parameters:
      - description: requested pid - object id
        in: path
        name: pid
        schema:
          required: true
          type: string
      - description: specifies the  desired format for the return
        in: query
        name: format
        schema:
          default: txt
          required: false
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  alerts:
                    items:
                      properties:
                        msg:
                          type: string
                        type:
                          type: string
                      type: object
                    type: array
                  status:
                    type: number
                  streaming:
                    type: object
                type: object
          description: requested objects fulltext data
        '404':
          content:
            application/json:
              schema:
                type: object
          description: object has not been found
      security:
      - basicAuth: []
      summary: 'Retrieves the FULLTEXT datastream of a specified object. It returns this datastream as it was saved: this is not a method which extracts fulltext from object''s data.'
      tags:
      - object-advanced
  /object/{pid}/geo:
    get:
      description: Retrieves geo datastream of object.
      parameters:
      - description: the requested object id
        in: path
        name: pid
        schema:
          required: true
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  alerts:
                    items:
                      properties:
                        msg:
                          type: string
                        type:
                          type: string
                      type: object
                    type: array
                  geo:
                    $ref: '#/components/schemas/geo'
                  status:
                    type: string
                type: object
          description: JSON of geo metadata. The datastream is saved as OGC-KML XML but currently only returned as JSON.
        '404':
          content:
            application/json:
              schema:
                type: object
          description: Failed to fetch data
      summary: Get geo.
      tags:
      - object-advanced
    post:
      description: This method saves information about the object's geolocation.
      parameters:
      - description: object pid
        in: path
        name: pid
        schema:
          required: true
          type: string
      requestBody:
        content:
          multipart/form-data:
            schema:
              properties:
                metadata:
                  $ref: '#/components/schemas/geo'
              type: object
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  alerts:
                    items:
                      properties:
                        msg:
                          type: string
                        type:
                          type: string
                      type: object
                    type: array
                  status:
                    type: string
                type: object
          description: geolocation data saved
      security:
      - basicAuth: []
      summary: Saves geo.
      tags:
      - object-advanced
  /object/{pid}/id:
    get:
      description: Get a list of identifiers that are saved in Dublin Core as [http://purl.org/dc/terms/identifier](http://purl.org/dc/terms/identifier).
      parameters:
      - description: object id
        in: path
        name: pid
        schema:
          required: true
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  alerts:
                    items:
                      properties:
                        msg:
                          type: string
                        type:
                          type: string
                      type: object
                    type: array
                  ids:
                    items:
                      type: string
                    type: array
                  status:
                    type: string
                type: object
          description: ids
      summary: Get Dublin Core identifiers.
      tags:
      - object-advanced
  /object/{pid}/id/add:
    post:
      description: Add an identifier to the triples (as a relationship with the predicate 'http://purl.org/dc/terms/identifier'). It is then available in the Dublin Core and index automatically, but will not be added to metadata. IDs added this way are usually added by PHAIDRA (for Handles), while the IDs in metadata are added and controlled by the user.
      parameters:
      - description: the requested object id
        in: path
        name: pid
        schema:
          required: true
          type: string
      requestBody:
        content:
          multipart/form-data:
            schema:
              properties:
                doi:
                  description: the DOI identifier
                  example: 10.5194/bg-11-1491-2014
                  required: false
                  type: string
                hdl:
                  description: 'the handle identifier '
                  example: 11353/10.448537
                  required: false
                  type: string
                urn:
                  description: the URN identifier
                  example: urn:nbn:at:at-ubw-30020.78240.320264-3
                  required: false
                  type: string
              type: object
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  alerts:
                    items:
                      properties:
                        msg:
                          type: string
                        type:
                          type: string
                      type: object
                    type: array
                  status:
                    type: string
                type: object
          description: Identifyer added
        '404':
          content:
            application/json:
              schema:
                type: object
          description: Failed to fetch data
      security:
      - basicAuth: []
      summary: Add an identifier triple
      tags:
      - object-advanced
  /object/{pid}/id/remove:
    post:
      parameters:
      - description: the requested object id
        in: path
        name: pid
        schema:
          required: true
          type: string
      requestBody:
        content:
          multipart/form-data:
            schema:
              properties:
                doi:
                  description: the DOI identifier
                  example: 10.5194/bg-11-1491-2014
                  required: false
                  type: string
                hdl:
                  description: 'the handle identifier '
                  example: 11353/10.448537
                  required: false
                  type: string
                urn:
                  description: the URN identifier
                  example: urn:nbn:at:at-ubw-30020.78240.320264-3
                  required: false
                  type: string
              type: object
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  alerts:
                    items:
                      properties:
                        msg:
                          type: string
                        type:
                          type: string
                      type: object
                    type: array
                  status:
                    type: string
                type: object
          description: Identifyer removed
        '404':
          content:
            application/json:
              schema:
                type: object
          description: Failed to fetch data
      security:
      - basicAuth: []
      summary: Remove identifier from triples
      tags:
      - object-advanced
  /object/{pid}/iiifmanifest:
    get:
      description: Retrieves the iiifmanifest datastream.
      parameters:
      - description: requested pid
        in: path
        name: pid
        schema:
          required: true
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/iiifmanifest'
          description: iiifmanifest data
      summary: Get iiifmanifest.
      tags:
      - object-advanced
    post:
      parameters:
      - description: object pid
        in: path
        name: pid
        schema:
          required: true
          type: string
      requestBody:
        content:
          multipart/form-data:
            schema:
              properties:
                metadata:
                  properties:
                    metadata:
                      properties:
                        IIIF-MANIFEST:
                          $ref: '#/components/schemas/iiifmanifest'
                      type: object
                  type: object
              type: object
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  alerts:
                    items:
                      properties:
                        msg:
                          type: string
                        type:
                          type: string
                      type: object
                    type: array
                  status:
                    type: string
                type: object
          description: ''
      security:
      - basicAuth: []
      summary: Saves the iiifmanifest.
      tags:
      - object-advanced
  /object/{pid}/index/dc:
    get:
      description: Get metadata exported (and significantly reduced) in Dublin Core standard
      parameters:
      - description: object id
        in: path
        name: pid
        schema:
          required: true
          type: string
      responses:
        '200':
          content:
            text/xml:
              example: <oai_dc:dc xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:oai_dc="http://www.openarchives.org/OAI/2.0/oai_dc/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.openarchives.org/OAI/2.0/oai_dc/ http://www.openarchives.org/OAI/2.0/oai_dc.xsd"></oai_dc:dc>
              schema:
                type: string
          description: dc - in XML
        '404':
          content:
            application/json:
              schema:
                type: object
          description: Failed to fetch data
      summary: Get DC
      tags:
      - object-advanced
  /object/{pid}/index/members:
    get:
      description: Get object's members using indexed data.
      parameters:
      - description: object id
        in: path
        name: pid
        schema:
          required: true
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  alerts:
                    items:
                      properties:
                        msg:
                          type: string
                        type:
                          type: string
                      type: object
                    type: array
                  members:
                    type: array
                  status:
                    type: string
                type: object
          description: members
        '404':
          content:
            application/json:
              schema:
                type: object
          description: Failed to fetch data
      summary: Get object's members.
      tags:
      - object-advanced
  /object/{pid}/index/relationships:
    get:
      description: Retrieves the object's relationships using indexed data.
      parameters:
      - description: object id
        in: path
        name: pid
        schema:
          required: true
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  alerts:
                    items:
                      properties:
                        msg:
                          type: string
                        type:
                          type: string
                      type: object
                    type: array
                  alternativeformats:
                    items:
                      type: string
                    type: array
                  alternativeversions:
                    items:
                      type: string
                    type: array
                  relationships:
                    $ref: '#/components/schemas/index_relationship'
                  status:
                    type: string
                  versions:
                    items:
                      type: string
                    type: array
                type: object
          description: relationships, from index
        '404':
          content:
            application/json:
              schema:
                type: object
          description: Failed to fetch data
      summary: Get relationships, from index.
      tags:
      - object-advanced
  /object/{pid}/json-ld:
    get:
      description: Retrieve full object JSON-LD, with `@context` header, etc.
      parameters:
      - description: the requested object id
        in: path
        name: pid
        schema:
          required: true
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  alerts:
                    items:
                      properties:
                        msg:
                          type: string
                        type:
                          type: string
                      type: object
                    type: array
                  jsonld:
                    $ref: '#/components/schemas/json-ld'
                  status:
                    type: string
                type: object
          description: JSON-LD metadata
        '404':
          content:
            application/json:
              schema:
                type: object
          description: failed to fetch data
      summary: Get full JSON-LD.
      tags:
      - object-advanced
  /object/{pid}/jsonld:
    get:
      description: Retrieve object JSON-LD metadata.
      parameters:
      - description: the requested object id
        in: path
        name: pid
        schema:
          required: true
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  alerts:
                    items:
                      properties:
                        msg:
                          type: string
                        type:
                          type: string
                      type: object
                    type: array
                  jsonld:
                    $ref: '#/components/schemas/jsonld'
                  status:
                    type: string
                type: object
          description: JSON-LD metadata
        '404':
          content:
            application/json:
              schema:
                type: object
          description: failed to fetch data
      summary: Get JSON-LD.
      tags:
      - object-advanced
    post:
      description: This method saves the metadata if you are using JSON-LD as a metadata structure.
      parameters:
      - description: object pid
        in: path
        name: pid
        schema:
          required: true
          type: string
      requestBody:
        content:
          multipart/form-data:
            schema:
              properties:
                metadata:
                  properties:
                    metadata:
                      properties:
                        json-ld:
                          $ref: '#/components/schemas/json-ld'
                      type: object
                  type: object
              type: object
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  alerts:
                    items:
                      properties:
                        msg:
                          type: string
                        type:
                          type: string
                      type: object
                    type: array
                  status:
                    type: string
                type: object
          description: JSON-LD metadata saved
      security:
      - basicAuth: []
      summary: Saves JSON-LD.
      tags:
      - object-advanced
  /object/{pid}/jsonldprivate:
    get:
      parameters:
      - description: object pid
        in: path
        name: pid
        schema:
          required: true
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  alerts:
                    items

# --- truncated at 32 KB (73 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/university-of-padua/refs/heads/main/openapi/university-of-padua-object-advanced-api-openapi.yml