api.yaml

openapi: "3.0.1"
info:
  description: "This is a set of APIs that are provided for Domain Data Management Service (DDMS) developers."
  version: "1.0.0"
  title: "DELFI Data Ecosystem Domain Extensions Services"
  termsOfService: "http://osdu.opengroup.org/terms/"
  contact:
    email: "osdu-sre@opengroup.org"
servers:
  - url: https://api.{environment}.csp.opengroup.org/dataecosystem
    variables:
      environment:
        default: p4d
        enum:
          - evd
          - evt
          - p4d

tags:
  - name: "registration"
    description: "APIs for registration"
    externalDocs:
      description: "Find out more"
      url: "https://test.devportal.apigee.io/solutions/dataecosystem/tutorials"

security:
  - Bearer: []

paths:
  "/registration/v1/ddms":
    post:
      tags:
        - "registration"
      summary: "Add a new DDMS to the Data Ecosystem"
      description: "Create a DDMS registration."
      operationId: "postDMS"
      parameters:
        - $ref: "#/components/parameters/correlation-id"
        - $ref: "#/components/parameters/data-partition-id"
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/DMSOpenAPISpec'
                - $ref: '#/components/schemas/DMSBasicSpec'
            example:
              name: logDMS
              description: "This DDMS is used to manage log data."
              contact:
                email: "osdu-sre@opengroup.org"
              servers:
                - url: "https://logstore/v1"
                  spec: "REST"
                  description: "Global logstore deployment"
                  isMultiDataPartition: true

      responses:
        '200':
          description: "Given DDMS has been registered."
          headers:
            "correlation-id":
              $ref: "#/components/headers/correlation-id"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DMSId'
        default:
          description: "Unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

    get:
      tags:
        - "registration"
      summary: "List DMSs registered in the Data Ecosystem"
      description: "List DMSs registrations."
      operationId: "listDMS"
      parameters:
        - $ref: "#/components/parameters/correlation-id"
        - $ref: "#/components/parameters/data-partition-id"

      responses:
        '200':
          description: "List of registered DMSs."
          headers:
            "correlation-id":
              $ref: "#/components/headers/correlation-id"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DMSList'
        default:
          description: "Unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  "/registration/v1/ddms/{id}":
    get:
      tags:
        - "registration"
      summary: "Get DMSs registered in the Data Ecosystem"
      description: "Get DDMS registration."
      operationId: "getDMS"
      parameters:
        - $ref: "#/components/parameters/correlation-id"
        - $ref: "#/components/parameters/data-partition-id"
        - name: id
          in: path
          required: true
          description: The id of the DDMS to retrieve
          schema:
            type: string
      responses:
        '200':
          description: "Registered DDMS."
          headers:
            "correlation-id":
              $ref: "#/components/headers/correlation-id"
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/DMSOpenAPISpec'
                  - $ref: '#/components/schemas/DMSBasicSpec'
        default:
          description: "Unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  "/registration/v1/types":
    get:
      tags:
        - "registration"
      summary: "List types registered in the Data Ecosystem"
      description: "List types registrations."
      operationId: "listTypes"
      parameters:
        - $ref: "#/components/parameters/correlation-id"
        - $ref: "#/components/parameters/data-partition-id"
        - name: dmsId
          in: query
          description: The id of the DDMS to filter the types on
          schema:
            type: string
      responses:
        '200':
          description: "List of registered types."
          headers:
            "correlation-id":
              $ref: "#/components/headers/correlation-id"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TypeList'
        default:
          description: "Unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  "/registration/v1/types/{id}":
    get:
      tags:
        - "registration"
      summary: "Get type registered in the Data Ecosystem"
      description: "Get type registration."
      operationId: "getType"
      parameters:
        - $ref: "#/components/parameters/correlation-id"
        - $ref: "#/components/parameters/data-partition-id"
        - name: id
          in: path
          required: true
          description: The id of the type to retrieve
          schema:
            type: string
      responses:
        '200':
          description: "Registered type."
          headers:
            "correlation-id":
              $ref: "#/components/headers/correlation-id"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Type'
        default:
          description: "Unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

components:
  headers:
    correlation-id:
      description: "Shared DELFI correlation id. Same as input one if provided, a new one otherwise."
      required: true
      schema:
        type: string
      examples:
        basic:
          value: "123456789"
  parameters:
    correlation-id:
      name: "correlation-id"
      in: "header"
      description: "Shared DELFI correlation id"
      schema:
        type: string
      examples:
        basic:
          value: "123456789"
    data-partition-id:
      name: "data-partition-id"
      in: "header"
      description: "DELFI data partition id"
      required: true
      schema:
        type: string
      examples:
        osdu:
          value: "opendes"
        customer:
          value: "my-NAM"
    Osdu-Data-Legal:
      name: "Osdu-Data-Legal"
      in: "header"
      description: "Stringified json of legal object associated with this wellbore"
      schema:
        type: string
      examples:
        basic:
          value: "{\"tag\":\"osdu-default\"}"
          summary: "Basic legal information"
        withAncestry: # Distinct name
          value: "{\"tag\":\"osdu-default\",\"ancestry\":{}}"
          summary: "Legal information containing ancestry applicable to derived data"
    Osdu-Data-Acl:
      name: "Osdu-Data-Acl"
      in: "header"
      schema:
        description: "Stringified json of access control list associated with this wellbore"
        type: string
      examples:
        basic:
          value: "[{\"role\":\"viewer\", \"members\":[\"data.default.viewers@my-company-nam.osdu.opengroup.org\"]}]"
          summary: "Basic legal information"


  schemas:
    DMSOpenAPISpec:
      description: "OpenAPI specification for a DDMS. Root level annotation with x-osdu-data-ddms-name and x-osdu-data-isMultiDataPartition is required. x-osdu-data-ddms-name must match the name parameter."
      title: "DMSOpenAPISpec"
      type: object
      properties:
        id:
          type: string
          example: "logDMS"
        name:
          type: string
          example: "logDMS"
        openAPI:
          type: object
          example:
            {}
    DMSBasicSpec:
      description: "Basic registration details for a DDMS."
      title: "DMSBasicSpec"
      type: object
      properties:
        id:
          type: string
          example: "logDMS"
        name:
          type: string
          example: "logDMS"
        description:
          type: string
          example: "This DDMS is used to manage log data."
        contact:
          type: object
          properties:
            email:
              type: string
              example: "osdu-sre@opengroup.org"
        servers:
          type: array
          items:
            properties:
              url:
                type: string
                description: "A URL to the target host."
                example: "https://logstore/v1"
              type:
                type: string
                description: "Type of the endpoints server is providing."
                enum:
                  - REST
                  - gRPC
                example: REST
              description:
                type: string
                description: "An optional string describing the host designated by the URL."
                example: "Global logstore endpoint"
              isMultiDataPartition:
                type: boolean
                description: "Indicating if DDMS is single or multitenant. Set to true if it is multitenant."
                example: false
              apiKey:
                type: string
                description: "An optional apiKey for the DDMS."
                example: "12345678"
            required:
              - url
              - type
              - isMultiDataPartition
    DMSId:
      description: "Id of the registered DDMS"
      properties:
        id:
          type: string
          example: "logDMS1"
    DMSList:
      type: array
      items:
        anyOf:
          - $ref: "#/components/schemas/DMSOpenAPISpec"
          - $ref: "#/components/schemas/DMSBasicSpec"
    Type:
      description: "OpenAPI specification for a DDMS. Root level annotation with x-osdu-data-ddms-name is required and it must match name parameter."
      title: "DMSOpenAPISpec"
      type: object
      properties:
        id:
          type: string
          example: "logDMS:log"
        name:
          type: string
          example: "log"
        server:
          type: string
          example: "https://logstore/v1"
        operations:
          type: object
          properties:
            get:
              type: object
              properties:
                path:
                  type: string
                  example: "/logs/{id}"
                parameters:
                  type: array
                  items:
                    $ref: "#/components/schemas/Parameter"
                  example:
                    - name: "data-partition-id"
                      in: "header"
                    - name: "id"
                      in: "path"


    TypeList:
      type: array
      items:
        $ref: "#/components/schemas/Type"
    Parameter:
      required:
        - name
        - in
      properties:
        name:
          type: string
          example: "id"
        in:
          type: string
          enum:
            - header
            - path
            - query
          example: "path"
    Error:
      required:
        - code
        - message
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
  securitySchemes:
    # This section configures basic authentication with an API key.
    Bearer:
      type: apiKey
      name: "Authorization"
      in: "header"
    googleIdToken:
      description: "This API uses OAuth2 Google Id Token implicit grant flow."
      type: oauth2
      flows:
        implicit:
          authorizationUrl: ""
          x-google-issuer: "https://accounts.google.com"
          x-google-jwks_uri: "https://www.googleapis.com/oauth2/v3/certs"
          x-google-audiences: "245464679631-ktfdfpl147m1mjpbutl00b3cmffissgq.apps.googleusercontent.com"
          scopes: {}