swagger.yaml

openapi: 3.0.0

info:
  title: iRODS REST API
  description: This is the iRODS REST API
  version: 0.1.0
  contact:
    email: info@irods.org
  license:
    name: BSD 3-Clause
    url: https://opensource.org/licenses/BSD-3-Clause

servers:
  - url: /v1

security:
  - BearerAuth:
      - read
      - write
  - BasicAuth:
      - read
      - write
  - ApiKeyAuth: []

tags:
  - name: auth
    description: Authentication endpoint
  - name: rodsadmin
    description: Secured Admin-only calls
  - name: rodsuser
    description: Operations available to regular users

paths:
  /ticket:
    post:
      tags:
        - auth
        - rodsuser
      summary:
        obtain an iRODS ticket and url for a given object
      operationId: ticket
      description:
        obtain an iRODS ticket and url for a given object
      parameters:
        - in: query
          name: path
          description: irods absolute logical path of the object
          required: true
          schema:
            type: string
      security: []
      responses:
        200:
          description: token acquired
          content:
            text/plain:
              schema:
                type: string
                description: iRODS ticket and url to use in subsequent operations
        '401':
          description: token acquisition failed

  /admin:
    get:
      tags:
        - rodsadmin
      summary: Administration interface for changes to zone configuration
      description: |
        Interface for zone administration including modification of users, resources, and
        zone federation.
      operationId: admin
      parameters:
        - in: query
          name: action
          description: dictates the action taken - add, modify, or remove
          required: true
          schema:
            type: string
        - name: target
          in: query
          description: the subject of the action - user, zone, resource, childtoresc, childfromresc, token, group, rebalance, unusedAVUs, specificQuery
          required: true
          schema:
            type: string
        - name: arg2
          in: query
          description: generic argument, could be user name, resource name, etc.
          required: true
          schema:
            type: string
        - name: arg3
          in: query
          description: generic argument
          required: true
          schema:
            type: string
        - name: arg4
          in: query
          description: generic argument
          required: true
          schema:
            type: string
        - name: arg5
          in: query
          description: generic argument
          required: true
          schema:
            type: string
        - name: arg6
          in: query
          description: generic argument
          required: true
          schema:
            type: string
        - name: arg7
          in: query
          description: generic argument
          required: true
          schema:
            type: string

      responses:
        200:
          description: OK
        400:
          description: bad input parameter

  /list:
    get:
      tags:
        - rodsuser
      summary: Recursively list the contents of a logical collection
      description: |
        Recursively list the contents of a logical collection
      operationId: list
      parameters:
        - name: path
          in: query
          description: irods absolute logical path of the collection
          required: true
          schema:
            type: string
        - name: stat
          in: query
          description: flag to include status information
          schema:
            type: boolean
        - name: permissions
          in: query
          description: flag to include permission information
          schema:
            type: boolean
        - name: metadata
          in: query
          description: flag to include metadata information
          schema:
            type: boolean
        - name: offset
          in: query
          description: number of records to skip for pagination
          schema:
            type: integer
            format: int32
            minimum: 0
        - name: limit
          in: query
          description: maximum number of records to return
          schema:
            type: integer
            format: int32
            minimum: 1
      security:
        - BasicAuth: [read]
        - ApiKeyAuth: [read]
        - BearerAuth: [read]

      responses:
        '200':
          description: listing of logical collection
          content:
            application/json:
              schema:
                type: string
        '400':
          description: bad input parameter
        '404':
          description: data not found/no access

  /stream:
    get:
      tags:
        - rodsuser
      summary: Obtains an HTTP stream of file bytes
      description: |
        Obtains an HTTP stream of file bytes
      operationId: stream
      parameters:
        - name: path
          in: query
          description: absolute logical path of the data object
          required: true
          schema:
            type: string
        - name: offset
          in: query
          description: number of bytes to skip for pagination
          schema:
            type: integer
            format: int32
            minimum: 0
        - name: limit
          in: query
          description: maximum number of bytes to return
          schema:
            type: integer
            format: int32
            minimum: 1
      security:
        - BasicAuth: [read]
        - ApiKeyAuth: [read]
        - BearerAuth: [read]

      responses:
        '200':
          description: bytestream of the (partial) data object
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '400':
          description: bad input parameter
        '404':
          description: data not found/no access

    put:
      tags:
        - rodsuser
      summary: Sends an HTTP stream of file bytes
      description: |
        Sends an HTTP stream of file bytes
      operationId: stream_put
      parameters:
        - in: query
          name: path
          description: absolute logical path of the data object
          required: true
          schema:
            type: string
        - in: query
          name: offset
          description: number of bytes to skip for pagination
          schema:
            type: integer
            format: int32
            minimum: 0
        - in: query
          name: limit
          description: maximum number of bytes to return
          schema:
            type: integer
            format: int32
            minimum: 1
      security:
        - BasicAuth: [read]
        - ApiKeyAuth: [read]
        - BearerAuth: [read]

      responses:
        '200':
          description: OK
        '400':
          description: bad input parameter
        '404':
          description: data not found/no access

  /query:
    get:
      tags:
        - rodsuser
      summary: searches iRODS Catalog using the General Query Language
      description: |
        By passing in the appropriate options, you can search for
        anything within the iRODS Catalog
      operationId: catalogQuery
      parameters:
      - name: query_string
        in: query
        description: an iRODS general query string or iRODS specific query string or iRODS specific query alias
        required: true
        schema:
          type: string
      - name: query_limit
        in: query
        description: maximum number of records to return
        required: false
        schema:
          type: integer
          maximum: 50
          minimum: 0
          format: string
      - name: row_offset
        in: query
        description: number of records to skip for pagination
        required: false
        schema:
          type: integer
          minimum: 0
          format: string
      - name: query_type
        in: query
        description: which type of query to perform
        required: true
        schema:
          type: string
          enum: ['general', 'specific']

      responses:
        200:
          description: search results matching criteria
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/query_results'

        400:
          description: bad input parameter

  /zonereport:
    get:
      tags:
        - rodsadmin
      summary: produces a json description of an iRODS Zone
      description: |
        Produces an iRODS Zone Report, a json description of the entire
        zone, including all configuration.  This API is for administrators
        only.
      operationId: zonereport

      responses:
        200:
          description: json description of an iRODS Zone
          content:
            application/json:
              schema:
                type: string
                description: json representation of irods zone
        400:
          description: bad input parameter

components:
  securitySchemes:

    BasicAuth:
      type: http
      scheme: basic

    ApiKeyAuth:        # arbitrary name for the security scheme
      type: apiKey
      in: header       # can be "header", "query" or "cookie"
      name: X-API-KEY  # name of the header, query parameter or cookie

    BearerAuth:
        type: http
        scheme: bearer
        bearerFormat: JWT

  schemas:
    query_results:
      type: object
      properties:
        results:
          type: string
          example: { "results" : [ [], [] ] }
      required:
        - results