swagger.yaml

swagger: '2.0'
info:
  version: v0
  title: ORR Ont API Documentation
  description: >
    The main ORR documentation is located at: http://mmisw.org/orrdoc/

    ```
    ######################################################
    # NOTE
    #   OUT-OF-DATE for the time being.
    # Currently the swagger spec is maintained in the
    # https://github.com/mmisw/mmiorr-docs repo, which
    # is served at http://mmisw.org/orrdoc/api/
    ######################################################
    ```

    __Note__:

    - We are in the process of writing this API documentation.
      Please [let us know](https://github.com/mmisw/mmiorr-docs/issues) if you have any
      questions or suggestions.

    - Besides the documentation itself, this page also allows to directly exercise the API.

    - Actual requests from this page are against the endpoint at
      `http://cor.esipfed.org/sparql`. This may change in a future version in
      particular regarding a more general way of exercising the API (regardless
      of concrete endpoint), or by allowing the selection of the particular endpoint.

    - You can use the "Authorize" button above and enter your COR credentials to login
      in this API interface. In this way you will be able to perform not only the basic
      `GET` operations, but see expanded responses according to your access priviliges
      and ontology visibility settings, as well as perform other operations as listed below.

  termsOfService: 'https://marinemetadata.org/orr/tou'
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html

host: cor.esipfed.org
basePath: /ont/api/v0
schemes:
  - http

consumes:
  - application/json
produces:
  - application/json

securityDefinitions:
  basicAuth:
    type: basic
    description: HTTP Basic Authentication.

paths:
  #
  # Ontology
  #
  /ont/upload:
    post:
      tags: [ontology]
      summary: Uploads an ontology file for subsequent registration
      description: |
        This operation allows to upload an ontology file as a preliminary step
        for subsequent registration via a `POST /ont` request.


        Before having to provide other required information for registration,
        this separated step helps not only in determining that the file is a valid ontology,
        but also in terms of the returned associated information that the user or
        client application can use for actual registration, for example, regarding possible
        ontology URIs found in the file.

      operationId: uploadOnt
      parameters:
        - in: formData
          name: file
          description: The file to be uploaded.
          required: true
          type: file
        - in: formData
          name: format
          description: |
            Format of the file. The special value `"guess"` can be given to let the ORR
            automatically determine the format.
            (A future version of this API may allow this parameter to be skipped, in such
            case with the "guess format" behavior implied.)
          required: true
          type: string
      responses:
        '200':
          description: |
            Information about the uploaded file. The `userName` and `filename` attributes of
            this object are to be used in the subsequent registration to property refer to
            the uploaded file.
          schema:
            $ref: '#/definitions/UploadedFileInfo'
      security:
       - basicAuth: []

  /ont:
    get:
      tags: [ontology]
      summary: Gets information about registered ontologies or terms
      description: |
        General ontology or term report according to given parameters,
        associated ontology visibility,
        and privilege of the requesting user.
        All parameters are optional.


        Any given `uri`, `ouri`, or `turi` parameter indicates a request for a
        particular ontology or term.

        If none of the `uri`, `ouri`, and `turi` parameters is given,
        this will indicate a query for a list of ontologies. In this case, only
        a metadata summary is provided for each reported ontology (in particular,
        no ontology contents per se is reported). Also, other supplied
        parameters will be used to query for the desired ontologies.
        For example, with the query paramenter and value `ownerName=acme`, all
        ontologies owned by the `acme` organization will be considered for reporting.


      parameters:
        - name: uri
          in: query
          type: string
          required: false
          description: |
            With this parameter the backend will first try an "ontology
            request." If no ontlogy is registered by the given URI, then it
            will try a "term request."

        - name: ouri
          in: query
          type: string
          required: false
          description: |
            Use this parameter to exclusively make a "ontology request."

        - name: version
          in: query
          type: string
          required: false
          description: |
            Desired version in the case of an "ontology request."

        - name: turi
          in: query
          type: string
          required: false
          description: |
            Use this parameter to exclusively make a "term request."

        - name: format
          in: query
          type: string
          required: false
          description: |
            Desired format for the response in the case of a single ontology
            or term request.

      responses:
        '200':
          description: Successful response
          schema:
            type: array
            items:
              $ref: '#/definitions/Ont'

    post:
      tags: [ontology]
      summary: Registers a brand new ontology
      description: |
        Performs the registration of a brand new ontology in the registry by
        the URI given in the `uri` attribute of the object in the body.
      operationId: addOnt
      parameters:
        - in: body
          name: body
          description: |
            Object with information for the ontology to be registered.

            To provide the contents of the ontology you have two options:

            - Specify a previously uploaded file (via `POST /ont/upload`) by
              providing the corresponding reported filename (in the `uploadedFilename`
              field) and format (`uploadedFormat`). There's no need to upload the file
              itself again.
            - Embbed the complete contents in the `contents` field, and provide the associated
              format in `format`.

            See the `PostOnt` object description for more details.

          schema:
            $ref: "#/definitions/PostOnt"
          required: true
      responses:
        "405":
          description: Invalid input
      security:
       - basicAuth: []

    put:
      tags: [ontology]
      summary: Updates a given ontology version or adds a new version
      description: |
        Use this operation to create a new version for a registered ontology,
        or to update an exisiting version.

      operationId: updateOnt
      parameters:
        - in: body
          name: body
          description: Ontology object that needs to be registered
          schema:
            $ref: "#/definitions/PutOnt"
      responses:
        "405":
          description: Invalid input
      security:
       - basicAuth: []

    delete:
      tags: [ontology]
      summary: Deletes a particular version or a whole ontology entry
      operationId: deleteOnt
      parameters:
        - in: query
          name: uri
          description: Ontology URI
          type: string
          required: true
        - in: query
          name: version
          description: |
            Particular version to be deleted.
            If omitted, the whole entry by the given URI will be unregistered.
          type: string
        - in: query
          name: userName
          type: string
          required: true
          description: |
            Registered user making the request. Must be an owner of the ontology.

      responses:
        "405":
          description: Invalid input
      security:
       - basicAuth: []

  #
  # Organization
  #
  /org:
    get:
      tags: [organization]
      summary: Gets information about registered organizations
      description: |
        Gets basic information of all registered organizations.
        This will include additional information depending on privileges of requesting user.
      responses:
        '200':
          description: Successful response
          schema:
            type: array
            items:
              $ref: '#/definitions/Org'

    post:
      tags: [organization]
      summary: Registers an organization
      description: ""
      operationId: addOrg
      parameters:
        - in: body
          name: body
          description: Organization object that needs to be registered
          schema:
            $ref: "#/definitions/PostOrg"
      responses:
        "405":
          description: Invalid input
      security:
       - basicAuth: []

  '/org/{orgName}':
    get:
      tags: [organization]
      summary: Gets basic information of a particular organization
      parameters:
        - name: orgName
          in: path
          type: string
          required: true
          description: The code (short name) of the organization.
      responses:
        '200':
          description: Successful response
          schema:
            $ref: '#/definitions/Org'

    put:
      tags: [organization]
      summary: Updates information about a registered organization
      operationId: updateOrg
      parameters:
        - name: orgName
          in: path
          type: string
          required: true
          description: The code (short name) of the organization to be updated.
        - in: body
          name: body
          description: Object with information for the organization to be updated.
          schema:
            $ref: "#/definitions/PutOrg"
      responses:
        "405":
          description: Invalid input
      security:
       - basicAuth: []

    delete:
      tags: [organization]
      summary: Unregisters an organization
      description: |
        Only users with administrative privilege can perform this operation.
      operationId: deleteOrg
      parameters:
        - in: path
          name: orgName
          description: Identifier of the organization
          type: string
          required: true

      responses:
        "200":
          description: Successful unregistration
        "404":
          description: No such organization
      security:
       - basicAuth: []

  #
  # User
  #
  /user:
    get:
      tags: [user]
      summary: Gets information about registered users
      description: |
        Gets information about registered users.
        This will include additional information depending on privileges of requesting user.
      responses:
        '200':
          description: Successful response
          schema:
            type: array
            items:
              $ref: '#/definitions/User'

    post:
      tags: [user]
      summary: Registers a user
      description: ""
      operationId: addUser
      parameters:
        - in: body
          name: body
          description: User object that needs to be registered
          schema:
            $ref: "#/definitions/PostUser"
      responses:
        "405":
          description: Invalid input
      security:
       - basicAuth: []

  '/user/{userName}':
    get:
      tags: [user]
      summary: Gets basic information of a particular user
      parameters:
        - name: userName
          in: path
          type: string
          required: true
          description: The login (short name) of the user.
      responses:
        '200':
          description: Successful response
          schema:
            $ref: '#/definitions/User'

    put:
      tags: [user]
      summary: Updates information about a registered user
      description: |
        Only the same user and users with administrative privilege can perform this operation.
      operationId: updateUser
      parameters:
        - name: userName
          in: path
          type: string
          required: true
          description: The identifier of the user to be updated.
        - in: body
          name: body
          description: Object with information for the user to be updated.
          schema:
            $ref: "#/definitions/PutUser"
      responses:
        "405":
          description: Invalid input
      security:
       - basicAuth: []

    delete:
      tags: [user]
      summary: Unregisters a user
      description: |
        Only users with administrative privilege can perform this operation.
      operationId: deleteUser
      parameters:
        - in: path
          name: userName
          description: Identifier of the user
          type: string
          required: true

      responses:
        "200":
          description: Successful unregistration
        "404":
          description: No such user
      security:
       - basicAuth: []

#####################################################################################
definitions:
  #
  # Ontology
  #
  UploadedFileInfo:
    type: object
    properties:
      userName:
        type: string
        description: The user that requested the upload.
      filename:
        type: string
        description: The name associated with the file.
      format:
        type: string
        description: The format of the file.
      possibleOntologyUris:
        type: object
        description: The format of the file.
        additionalProperties:
          $ref: '#/definitions/PossibleOntologyInfo'

  PossibleOntologyInfo:
    type: object
    properties:
      explanations:
        type: array
        items:
          type: string
        description: |
          Explanations for the extraction of the given possible ontology URI.
      metadata:
        type: object
        description: Metadata associated to the ontology URI.
        additionalProperties:
          type: array
          items:
            type: string


  PostOnt:
    type: object
    properties:
      uri:
        type: string
        description: |
          The URI of the ontology.

      originalUri:
        type: string
        description: |
          In case of a fully-hosted registration, enter this field to indicate
          the original URI in the provided contents to be used for the "migration"
          of corresponding entities to the new URI.

      name:
        type: string
        description: |
          The name for the ontology. If omitted, the ORR will try to get this
          information from standard metadata in the submitted ontology contents.

      orgName:
        type: string
        description: |
          ID of the organization that will own the ontology registration.
          If omitted, the owner will be the submitting user.

      visibility:
        type: string
        description: |
          One of: `owner` or `public`. The default visibility is `owner`.

      status:
        type: string
        description: |
          One of: `draft`, `unstable`, `testing`, `stable`,  `deprecated`, `archaic`.
          There's no default value.

      userName:
        type: string
        description: |
          Registered user making the request.

      uploadedFilename:
        type: string
        description: |
          Name of file previously uploaded via prior `POST /ont/upload` request.
      uploadedFormat:
        type: string
        description: |
          Format of the file previously uploaded via prior `POST /ont/upload` request.

      contents:
        type: string
        description: |
          Direct contents of the ontology.
      format:
        type: string
        description: |
          Format of the `contents`.

  PutOnt:
    type: object
    properties:
      uri:
        type: string
        description: The URI of the ontology to be updated.

      version:
        type: string
        description: |
          If given, this particular version will be updated.
          Otherwise, a new version (which is generated by the ORR) is created.

      originalUri:
        type: string
        description: |
          In case a fully-hosted registration and ontology contents are provided for this update, enter this field to indicate
          the original URI to be used for the "migration" of corresponding entities to the URI used for registration.

      name:
        type: string
        description: |
          If given, this will be the new name for the ontology.

      visibility:
        type: string
        description: |
          One of: `owner` or `public`.

      status:
        type: string
        description: |
          One of: `draft`, `unstable`, `testing`, `stable`,  `deprecated`, `archaic`.

      metadata:
        type: string
        description: |
          Ontology metadata as a JSON formatted object.
          This parameter allows to perform the update solely based on changes
          to the metadata.

      uploadedFilename:
        type: string
        description: |
          Name of file previously uploaded via prior `POST /ont/upload` request.
      uploadedFormat:
        type: string
        description: |
          Format of the file previously uploaded via prior `POST /ont/upload` request.

      contents:
        type: string
        description: |
          Direct contents of the ontology.
      format:
        type: string
        description: |
          Format of the `contents`.

      userName:
        type: string
        description: |
          Registered user making the request.

  Ont:
    type: object
    properties:
      uri:
        type: string
      name:
        type: string
      version:
        type: string
      ownerName:
        type: string
      status:
        type: string
      format:
        type: string
      visibility:
        type: string

  #
  # Organization
  #
  PostOrg:
    type: object
    properties:
      name:
        type: string
      orgName:
        type: string
      members:
        type: array
        items:
          type: string
        description: Members of this organization
      url:
        type: string
        description: Website URL of the organization

  PutOrg:
    type: object
    properties:
      name:
        type: string
      orgName:
        type: string
      members:
        type: array
        items:
          type: string
        description: Members of this organization
      url:
        type: string
        description: Website URL of the organization

  Org:
    type: object
    properties:
      name:
        type: string
      orgName:
        type: string
      members:
        type: array
        items:
          type: string

  #
  # User
  #
  PostUser:
    type: object
    properties:
      userName:
        type: string
      email:
        type: string
      firstName:
        type: string
      lastName:
        type: string
      password:
        type: string
        format: password
      phone:
        type: string

  PutUser:
    type: object
    properties:
      email:
        type: string
      firstName:
        type: string
      lastName:
        type: string
      password:
        type: string
        format: password
      phone:
        type: string

  User:
    type: object
    properties:
      userName:
        type: string
      firstName:
        type: string
      lastName:
        type: string