openapi.osdu.yaml

#  ***************************************************************************
#  Copyright 2017 - 2021, Schlumberger
#
#  Licensed under the Apache License, Version 2.0(the "License");
#  you may not use this file except in compliance with the License.
#  You may obtain a copy of the License at
#
#   http://www.apache.org/licenses/LICENSE-2.0
#
#  Unless required by applicable law or agreed to in writing, software
#  distributed under the License is distributed on an "AS IS" BASIS,
#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
#  See the License for the specific language governing permissions and
#  limitations under the License.
#  ***************************************************************************

# ===========================================================================
# Endpoints Description
# ===========================================================================

swagger: "2.0"

info:
  title: "Seismic DMS Service"
  version: "3.0.0"
  description: "Seismic Data Management APIs to store and manage seismic datasets ."
  license:
    name: "Apache 2.0"
    url: "https://www.apache.org/licenses/LICENSE-2.0.html"

consumes:
  - application/json
produces:
  - application/json
schemes:
  - https

# ===========================================================================
# Endpoints Paths Section
# ===========================================================================

basePath: /seistore-svc/api/v3

paths:
  /svcstatus:
    get:
      summary: "Seismic store service status (fast check)."
      description: "<ul><li>Return the seismic store service status.</li><li>Required roles: none</li></ul>"
      security:
        - api-key: []
      operationId: service-status
      tags:
        - General
      responses:
        200:
          description: "Service status."
          schema:
            type: string
            example: "service OK"

  /svcstatus/access:
    get:
      summary: "Seismic store service status."
      description: "<ul><li>Return the seismic store service status.</li><li>Required roles: none</li></ul>"
      operationId: service-status-check
      tags:
        - General
      responses:
        200:
          description: "Seismic store service status."
          schema:
            $ref: "#/definitions/Status"
        401:
          description: "Unauthorized."
        403:
          description: "Forbidden."

  /dataset/tenant/{tenantid}/subproject/{subprojectid}/dataset/{datasetid}:
    post:
      summary: "Register a new dataset."
      description: "<ul><li>Register a new dataset in the seismic store.</li><li>Required roles: subproject.admin, subproject.editor</li></ul>"
      operationId: dataset-register
      tags:
        - Dataset
      parameters:
        - description: "Legal tag of the dataset."
          in: header
          name: ltag
          type: string
          required: false
        - description: "Name of the tenant."
          in: path
          name: tenantid
          required: true
          type: string
        - description: "Name of the subproject."
          in: path
          name: subprojectid
          required: true
          type: string
        - description: "Hierarchical path of the dataset."
          in: query
          name: path
          required: true
          type: string
        - description: "Name of the dataset."
          in: path
          name: datasetid
          required: true
          type: string
        - description: "Request body"
          in: body
          name: request body
          required: false
          schema:
            $ref: "#/definitions/DatasetRegisterBody"
      responses:
        200:
          description: "Registered dataset metadata."
          schema:
            $ref: "#/definitions/Dataset"
        400:
          description: "Bad request."
        401:
          description: "Unauthorized."
        403:
          description: "Forbidden."
        404:
          description: "Not found."
        409:
          description: "Conflict."
        423:
          description: "Locked. The error message contains the Reason in the form <b>[RCODE:REASON(2-char-code)TTL(sec-number)]</b>. Possible Reasons code are: <ul>
          <li>WL (Write Locked).</li>
          <li>RL (Read Locked).</li>
          <li>CL (Cannot be Locked).</li>
          <li>UL (Cannot be Unlocked).</ul>\nFor example the reason code <b>[RCODE:RL3600]</b> indicates the dataset is Read Locked with a TTL of 3600 seconds."
    get:
      summary: "Retrieve a dataset."
      description: "<ul><li>Return the dataset metadata from the seismic store.</li><li>Required roles: subproject.admin, subproject.editor, subproject.viewer</li></ul>"
      operationId: dataset-get
      tags:
        - Dataset
      parameters:
        - description: "Name of the tenant."
          in: path
          name: tenantid
          required: true
          type: string
        - description: "Name of the subproject."
          in: path
          name: subprojectid
          required: true
          type: string
        - description: "Hierarchical path of the dataset."
          in: query
          name: path
          required: true
          type: string
        - description: "Name of the dataset."
          in: path
          name: datasetid
          required: true
          type: string
        - description: "Include the seismic storage metadata record if it exists."
          in: query
          name: seismicmeta
          required: false
          type: boolean
      responses:
        200:
          description: "Metadata of the dataset."
          schema:
            $ref: "#/definitions/Dataset"
        400:
          description: "Bad request."
        401:
          description: "Unauthorized."
        403:
          description: "Forbidden."
        404:
          description: "Not found."

    delete:
      summary: "Delete a dataset."
      description: "<ul><li>Delete a dataset in the seismic store.</li><li>Required roles: subproject.admin, subproject.editor</li></ul>"
      operationId: dataset-delete
      tags:
        - Dataset
      parameters:
        - description: "Name of the tenant."
          in: path
          name: tenantid
          required: true
          type: string
        - description: "Name of the subproject."
          in: path
          name: subprojectid
          required: true
          type: string
        - description: "Hierarchical path of the dataset."
          in: query
          name: path
          required: true
          type: string
        - description: "Name of the dataset."
          in: path
          name: datasetid
          required: true
          type: string
      responses:
        200:
          description: "The resource was deleted successfully."
        400:
          description: "Bad request."
        401:
          description: "Unauthorized."
        403:
          description: "Forbidden."
        404:
          description: "Not found."

    patch:
      summary: "Patch the dataset metadata."
      description: "<ul>
      <li>Update the dataset meta information in the seismic store or close (unlock) the dataset. If the endpoint is used without the close parameter, at least one body field is required or the endpoint will return an error.</li>
      <li>Required roles: subproject.admin, subproject.editor</li>
      <li>Patchable fields: <ul>
      <li><b>dataset_new_name:</b> new name to use for the dataset (rename).</li>
      <li><b>filemetadata:</b> This is a seismic store specific field and describes how the physical data is stored in the cloud storage system (GCS/AzureContainer etc.). This metadata is mainly used by client libraries to correctly reconstruct the dataset. For example you can store a dataset as truncated in multiple objects of 64MB each, name them from 0 to N and save the filemetadata = “{nObject: N, totalSize: 1024, objsize: 64, sizeUnit: MB}”.</li>
      <li><b>last_modified_date:</b> Mark this field as true to update the dataset last modified date.</li>
      <li><b>gtags:</b> Upsert tags to an existing dataset metadata. If the dataset metadata already has gtags, then new gtags are appended to this list.</li>
      <li><b>ltag:</b> Update the existing legalTag value.</b></li>
      <li><b>readonly:</b> Update the dataset mode to readonly (true) or to read/write (false).</li>
      <li><b>seismicmeta:</b> Update the Data Ecosystem storage metadata. (Refer to the Data Ecosystem storage service tutorial for more information.)</b></li></ul></li></ul>"
      operationId: dataset-patch
      tags:
        - Dataset
      parameters:
        - description: "Name of the tenant."
          in: path
          name: tenantid
          required: true
          type: string
        - description: "Name of the subproject."
          in: path
          name: subprojectid
          required: true
          type: string
        - description: "Hierarchical path of the dataset."
          in: query
          name: path
          required: true
          type: string
        - description: "Name of the dataset."
          in: path
          name: datasetid
          required: true
          type: string
        - description: "Request body"
          in: body
          name: request body
          schema:
            $ref: "#/definitions/DatasetPatch"
        - description: "Non null sbit value of the dataset. Using this value here will close the dataset."
          in: query
          name: close
          required: false
          type: string
      responses:
        200:
          description: "Metadata of the patched dataset."
          schema:
            $ref: "#/definitions/Dataset"
        400:
          description: "Bad request."
        401:
          description: "Unauthorized."
        403:
          description: "Forbidden."
        404:
          description: "Not found."
        409:
          description: "Conflict."
        423:
          description: "Locked. The error message contains the Reason in the form <b>[RCODE:REASON(2-char-code)TTL(sec-number)]</b>. Possible Reasons code are: <ul>
          <li>WL (Write Locked).</li>
          <li>RL (Read Locked).</li>
          <li>CL (Cannot be Locked).</li>
          <li>UL (Cannot be Unlocked).</ul>\nFor example the reason code <b>[RCODE:RL3600]</b> indicates the dataset is Read Locked with a TTL of 3600 seconds."

  /dataset/tenant/{tenantid}/subproject/{subprojectid}/dataset/{datasetid}/lock:
    put:
      summary: "Acquire a lock for a dataset id."
      description: "<ul>
      <li>Open a dataset for read or write and lock its state.</li>
      <li>Required roles open lock for write: subproject.admin, subproject.editor</li>
      <li>Required roles open lock for read: subproject.admin, subproject.editor, subproject.viewer</ul>"
      operationId: dataset-lock
      tags:
        - Dataset
      parameters:
        - description: "Name of the tenant."
          in: path
          name: tenantid
          required: true
          type: string
        - description: "Name of the subproject."
          in: path
          name: subprojectid
          required: true
          type: string
        - description: "Hierarchical path of the dataset."
          in: query
          name: path
          required: true
          type: string
        - description: "Name of the dataset."
          in: path
          name: datasetid
          required: true
          type: string
        - description: "Type of the lock which can be set to 'read' (default) or 'write'."
          in: query
          name: openmode
          required: false
          type: string
        - description: "Session identifier issued for a previous write lock acquisition operation."
          in: query
          name: wid
          required: false
          type: number
      responses:
        200:
          description: "Acquired a lock and the return value is the dataset metadata with session identifier stored in the 'sbit' attribute."
          schema:
            $ref: "#/definitions/Dataset"
        400:
          description: "Bad request."
        401:
          description: "Unauthorized."
        403:
          description: "Forbidden."
        404:
          description: "Not found."
        423:
          description: "Locked. The error message contains the Reason in the form <b>[RCODE:REASON(2-char-code)TTL(sec-number)]</b>. Possible Reasons code are: <ul>
          <li>WL (Write Locked).</li>
          <li>RL (Read Locked).</li>
          <li>CL (Cannot be Locked).</li>
          <li>UL (Cannot be Unlocked).</ul>\nFor example the reason code <b>[RCODE:RL3600]</b> indicates the dataset is Read Locked with a TTL of 3600 seconds."

  /dataset/tenant/{tenantid}/subproject/{subprojectid}/dataset/{datasetid}/unlock:
    put:
      summary: "Remove the lock associated with a dataset id."
      description: "<ul><li>Removes the lock for a dataset id.</li><li>Required roles: subproject.admin</li></ul>"
      operationId: dataset-lock-rm
      tags:
        - Dataset
      parameters:
        - description: "Name of the tenant."
          in: path
          name: tenantid
          required: true
          type: string
        - description: "Name of the subproject."
          in: path
          name: subprojectid
          required: true
          type: string
        - description: "Hierarchical path for the dataset."
          in: query
          name: path
          required: true
          type: string
        - description: "Name of the dataset."
          in: path
          name: datasetid
          required: true
          type: string
      responses:
        200:
          description: "Removed the lock value associated with dataset id."
        400:
          description: "Bad request."
        401:
          description: "Unauthorized."
        403:
          description: "Forbidden."
        404:
          description: "Not found."
        423:
          description: "Locked. The error message contains the Reason in the form <b>[RCODE:REASON(2-char-code)TTL(sec-number)]</b>. Possible Reasons code are: <ul>
          <li>WL (Write Locked).</li>
          <li>RL (Read Locked).</li>
          <li>CL (Cannot be Locked).</li>
          <li>UL (Cannot be Unlocked).</ul>\nFor example the reason code <b>[RCODE:RL3600]</b> indicates the dataset is Read Locked with a TTL of 3600 seconds."

  /dataset/tenant/{tenantid}/subproject/{subprojectid}/dataset/{datasetid}/permission:
    get:
      summary: "Retrieve the access permissions of a user on a dataset id."
      description: "<ul><li>Retrieve the access permission of a user on a dataset.</li><li>Required roles: subproject.admin, subproject.editor, subproject.viewer</li></ul>"
      operationId: dataset-permission
      tags:
        - Dataset
      parameters:
        - description: "Name of the tenant."
          in: path
          name: tenantid
          required: true
          type: string
        - description: "Name of the subproject."
          in: path
          name: subprojectid
          required: true
          type: string
        - description: "Hierarchical path for the dataset."
          in: query
          name: path
          required: true
          type: string
        - description: "Name of the dataset."
          in: path
          name: datasetid
          required: true
          type: string
      responses:
        200:
          description: "User access permission on the dataset."
          schema:
            $ref: "#/definitions/DatasetPermission"
        400:
          description: "Bad request."
        401:
          description: "Unauthorized."
        403:
          description: "Forbidden."
        404:
          description: "Not found."

  /dataset/tenant/{tenantid}/subproject/{subprojectid}/dataset/{datasetid}/ctagcheck:
    get:
      summary: "Validate if a dataset ctag matches the pre-existing ctag in metadata catalog."
      description: "<ul><li>Check if the provided dataset cTag match the one stored in the metadata catalog.</li><li>Required roles: subproject.admin, subproject.editor, subproject.viewer</li></ul>"
      operationId: ctag-check
      tags:
        - Dataset
      parameters:
        - description: "Name of the tenant."
          in: path
          name: tenantid
          required: true
          type: string
        - description: "Name of the subproject."
          in: path
          name: subprojectid
          required: true
          type: string
        - description: "Hierarchical path of the dataset."
          in: query
          name: path
          required: true
          type: string
        - description: "Name of the dataset."
          in: path
          name: datasetid
          required: true
          type: string
        - description: "Ctag to be validated."
          in: query
          name: ctag
          required: true
          type: string
      responses:
        200:
          description: "Return true if the ctag is valid or false if it is invalid."
          schema:
            type: boolean
            example: "true"
        400:
          description: "Bad request."
        401:
          description: "Unauthorized."
        403:
          description: "Forbidden."
        404:
          description: "Not found."

  /dataset/tenant/{tenantid}/subproject/{subprojectid}/dataset/{datasetid}/gtags:
    put:
      summary: "Upsert tags to a dataset."
      description: "<ul>
      <li>Upsert tags to an existing dataset metadata. If the dataset metadata already has gtags, then  new gtags are appended to this list.</li>
      <li>Required roles: subproject.admin, subproject.editor</li></ul>"
      operationId: add-tag
      tags:
        - Dataset
      parameters:
        - description: "Name of the tenant."
          in: path
          name: tenantid
          required: true
          type: string
        - description: "Name of the subproject."
          in: path
          name: subprojectid
          required: true
          type: string
        - description: "Hierarchical path of the dataset."
          in: query
          name: path
          required: true
          type: string
        - description: "Name of the dataset."
          in: path
          name: datasetid
          required: true
          type: string
        - description: "Gtags array list."
          in: query
          name: gtag
          required: true
          type: array
          items:
            type: string
            default: "tag1"
          collectionFormat: multi
      responses:
        200:
          description: "Gtags were upserted to the dataset metadata."
        400:
          description: "Bad request."
        401:
          description: "Unauthorized."
        403:
          description: "Forbidden."
        404:
          description: "Not found."

  # To deprecate in favor of /utility/ls
  /dataset/tenant/{tenantid}/subproject/{subprojectid}/readdsdirfulllist:
    get:
      summary: "Content list."
      description: "<ul>
      <li>List datasets and sub-directories for a directory path.</li>
      <li>Required roles: subproject.admin, subproject.editor, subproject.viewer</li></ul>"
      operationId: dataset-read-directory
      tags:
        - Dataset
      parameters:
        - description: "The tenant project name."
          in: path
          name: tenantid
          required: true
          type: string
        - description: "The sub-project name."
          in: path
          name: subprojectid
          required: true
          type: string
        - description: "The hierarchy path."
          in: query
          name: path
          required: true
          type: string
      responses:
        200:
          description: "The list of datasets and directories in the requested directory path."
          schema:
            $ref: "#/definitions/DatasetAndDirectories"

  /dataset/tenant/{tenantid}/subproject/{subprojectid}:
    get:
      summary: "Get the list of datasets in a subproject."
      description: "<ul>
      <li>Return the list of datasets in a sub-project. If gtags are in the request parameters, then get only those datasets that have the exact list of gtags.</li>
      <li>Required roles: subproject.admin, subproject.editor, subproject.viewer</li></ul>"
      operationId: dataset-list
      tags:
        - Dataset
      parameters:
        - description: "Name of the tenant."
          in: path
          name: tenantid
          required: true
          type: string
        - description: "Name of the subproject."
          in: path
          name: subprojectid
          required: true
          type: string
        - description: "Gtags associated with dataset metadata."
          in: query
          name: gtag
          type: array
          items:
            type: string
          collectionFormat: multi

      responses:
        200:
          description: "The list of all datasets in the subproject if no gtags are in the request parameters. If gtags exist in the request parameters, then list all datasets that have the same list of gtags."
          schema:
            type: array
            items:
              $ref: "#/definitions/Dataset"
        400:
          description: "Bad request."
        401:
          description: "Unauthorized."
        403:
          description: "Forbidden."
        404:
          description: "Not found."

  /dataset/tenant/{tenantid}/subproject/{subprojectid}/exist:
    post:
      summary: "Check to see if a list of datasets exists in the subproject."
      description: "<ul>
      <li>Check if the dataset exists.</li>
      <li>Required roles: subproject.admin, subproject.editor, subproject.viewer</li></ul>"
      operationId: dataset-exist
      tags:
        - Dataset
      parameters:
        - description: "Name of the tenant."
          in: path
          name: tenantid
          required: true
          type: string
        - description: "Name of the subproject."
          in: path
          name: subprojectid
          required: true
          type: string
        - description: "Request body"
          in: body
          name: request body
          required: true
          schema:
            $ref: "#/definitions/DatasetCheckList"
      responses:
        200:
          description: "A list of Boolean values for all the input datasets in the request body. If a value is true, then the corresponding dataset exists and if it is false, then the dataset does not exist."
          schema:
            type: array
            items:
              type: boolean
            example: [true, false]
        400:
          description: "Bad request."
        401:
          description: "Unauthorized."
        403:
          description: "Forbidden."
        404:
          description: "Not found."

  /dataset/tenant/{tenantid}/subproject/{subprojectid}/sizes:
    post:
      summary: "Retrieve the size of datasets."
      description: "<ul>
      <li>Return a list with the sizes of the requested datasets.</li>
      <li>Required roles: subproject.admin, subproject.editor, subproject.viewer</li></ul>"
      operationId: dataset-sizes
      tags:
        - Dataset
      parameters:
        - description: "Name of the tenant."
          in: path
          name: tenantid
          required: true
          type: string
        - description: "Name of the subproject."
          in: path
          name: subprojectid
          required: true
          type: string
        - description: "Request body"
          in: body
          name: request body
          required: true
          schema:
            $ref: "#/definitions/DatasetCheckList"
      responses:
        200:
          description: "The list of sizes of all the datasets. If the dataset does not exist, the size returns -1."
          schema:
            type: array
            items:
              type: number
            example: [1024, -1]
        400:
          description: "Bad request."
        401:
          description: "Unauthorized."
        403:
          description: "Forbidden."
        404:
          description: "Not found."

  /utility/ls:
    get:
      summary: "Retrieve the list of datasets and sub-directories inside a seismic store path."
      description: "<ul>
      <li>Return the list of datasets and sub-directories of a seismic store path.</li>
      <li>Required roles: subproject.admin, subproject.editor, subproject.viewer</li></ul>"
      operationId: ls
      tags:
        - Utility
      parameters:
        - description: "Seismic store path, sd://tenant/sub-project/path."
          in: query
          name: sdpath
          required: true
          type: string
          default: sd://common/carbon/a/b/c
        - description: "Working mode, directories or datasets or undefined for both."
          in: query
          name: wmode
          required: false
          type: string
        - description: "Limits the total number of datasets to return."
          in: query
          name: limit
          required: false
          type: number
        - description: "Pagination token - this query parameter can be omitted on first call."
          in: query
          name: cursor
          required: false
          type: string
      responses:
        200:
          description: "Seismic store path content."
          schema:
            $ref: "#/definitions/LsDatasets"
        201:
          description: "Paginated seismic store path content - For documentation purposes, if limit or cursor is given, status code here is 200."
          schema:
            $ref: "#/definitions/LsPaginatedDatasets"
        400:
          description: "Bad request."
        401:
          description: "Unauthorized."
        403:
          description: "Forbidden."
        404:
          description: "Not found."

  /utility/cp:
    post:
      summary: "Copy dataset."
      description: "<ul>
      <li>Copy a seismic store dataset. The source and destination dataset must be in the same sub-project.</li>
      <li>Required roles: subproject.admin, subproject.editor</li></ul>"
      operationId: cp
      tags:
        - Utility
      parameters:
        - description: "Seismic store source dataset path."
          in: query
          name: sdpath_from
          required: true
          type: string
        - description: "Seismic store destination dataset path."
          in: query
          name: sdpath_to
          required: true
          type: string
        - description: "Lock source and destination while copying."
          in: query
          name: lock
          required: false
          type: boolean
      responses:
        200:
          description: "Copy operation succeeded."
          schema:
            type: object
        400:
          description: "Bad request."
        401:
          description: "Unauthorized."
        403:
          description: "Forbidden."
        404:
          description: "Not found."
        409:
          description: "Conflict."
        423:
          description: "Locked. The error message contains the Reason in the form <b>[RCODE:REASON(2-char-code)TTL(sec-number)]</b>. Possible Reasons code are: <ul>
          <li>WL (Write Locked)</li>
          <li>RL (Read Locked)</li>
          <li>CL (Cannot be Locked)</li>
          <li>UL (Cannot be Unlocked)</ul>\nFor example the reason code <b>[RCODE:RL3600]</b> indicates the dataset is Read Locked with a TTL of 3600 seconds."

  /utility/gcs-access-token:
    get:
      summary: "Generate a GCS access token."
      description: "<ul><li>Generate a GCS access token for a specified seismic store resource. The source and destination dataset must be in the same sub-project.</li><li>Required roles: subproject.admin, subproject.editor, subproject.viewer</li></ul>"
      operationId: gcs-access-token
      tags:
        - Utility
      parameters:
        - description: "Seismic store path in the format sd://tenant/sub-project."
          in: query
          name: sdpath
          type: string
          required: true
          default: sd://common/carbon
        - description: "Readonly access, true(default) or false."
          in: query
          name: readonly
          type: boolean
      responses:
        200:
          description: "The GCS access token."
          schema:
            $ref: "#/definitions/AccessToken"
        400:
          description: "Bad request."
        401:
          description: "Unauthorized."
        403:
          description: "Forbidden."
        404:
          description: "Not found."

  /imptoken:
    post:
      summary: "Generate impersonation credentials token."
      description: "<ul>
      <li>Generate an impersonation credential token of a user for a set of subproject resources.</li>
      <li>Required roles: app.trusted</li></ul>"
      operationId: imp-token
      tags:
        - Impersonation Token (Obsolete)
      parameters:
        - description: "Request body"
          in: body
          name: request body
          required: true
          schema:
            $ref: "#/definitions/ImpersonationToken"
      responses:
        200:
          description: "Generated a impersonation credentials token successfully."
          schema:
            $ref: "#/definitions/ImpersonationToken"
        400:
          description: "Bad request."
        401:
          description: "Unauthorized."
        403:
          description: "Forbidden."
        404:
          description: "Not found."

    put:
      summary: "Refresh an impersonation credential token."
      description: "<ul><li>Refresh an impersonation credential token.</li><li>Required roles: none</li></ul>"
      security:
        - api-key: []
      operationId: imp-token-refresh
      tags:
        - Impersonation Token (Obsolete)
      parameters:
        - description: "Request body"
          in: body
          name: request body
          required: true
          schema:
            $ref: "#/definitions/RefreshTokenRequest"
      responses:
        200:
          description: "Refreshed impersonation credential token successfully."
          schema:
            $ref: "#/definitions/ImpersonationToken"
        400:
          description: "Bad request."
        401:
          description: "Unauthorized."
        403:
          description: "Forbidden."
        404:
          description: "Not found."

    patch:
      summary: "Patch an impersonation credential token's refresh url and generate a new impersonation token."
      description: "<ul>
      <li>Patch an impersonation credential token's refresh url and generate a new impersonation token.</li>
      <li>Required roles: none</li></ul>"
      operationId: imp-token-patch
      tags:
        - Impersonation Token (Obsolete)
      parameters:
        - description: "Request body"
          in: body
          name: request body
          required: true
          schema:
            $ref: "#/definitions/ImpTokenPatchRequest"
      responses:
        200:
          description: "Generated impersonation token successfully and its refresh url is updated."
          schema: