swagger.yaml

openapi: '3.0.2'
info:
  title: ORR API Documentation
  description: >
    The main ORR documentation is located at: https://mmisw.org/orrdoc/


    __Please note__:

    - The ORR API is approaching a stable version but is still work in progress.
      Please [let us know](https://github.com/mmisw/mmiorr-docs/issues) if you have any
      questions or suggestions.

    - Besides the documentation itself, this page lets you directly exercise and test the API.
      Click on any operation header below to learn more details about it, and see a "Try it out" button.

    - You can click on the "Authorize" button at the top right of this page
      (or the `!` icon under the particular operation)
      to retrieve an authentication token corresponding to your ORR instance credentials (username and password).
      Once authorized, the authentication token will be automatically included in the corresponding request.
      You will be able to not only perform the basic `GET` operations,
      but also see expanded responses according to your access privileges
      as well as perform other operations.

    - The "Try it out" button will also show the corresponding API call that you can submit
      from the command line using [`curl`](https://curl.haxx.se/).

    - This API includes administrative operations related with the triple store.
      The SPARQL endpoint itself
      (located at `http://cor.esipfed.org/sparql` for the MMI ORR instance)
      is not described here.
      (General SPARQL information can be found [here](https://en.wikipedia.org/wiki/SPARQL),
      and regarding the current service used by the ORR to support the SPARQL interface
      [here](http://franz.com/agraph/support/documentation/current/http-protocol.html).)

    - Actual requests from this page are against the specific endpoint at
      `http://cor.esipfed.org/ont`.

  termsOfService: 'https://marinemetadata.org/orr/tou'
  contact: 
    name: 'COR API Support'
    url: 'http://cor.esipfed.org'
    email: 'esip-cor@lists.esipfed.org'
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  version: 1.0.0

servers:
- url: http://cor.esipfed.org/v1

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 corresponds to an
        ontology in a recognized format,
        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 IRIs found in the file.

      operationId: uploadOnt
      parameters:
        - name: file
          in: query
          description: The file to be uploaded.
          required: true
          schema:
            type: string
            format: binary
        - name: format
          in: query
          description: |
            Format of the file.
            The supported formats are described in [this section](https://mmisw.org/orrdoc/ontology/new/#supported-ontology-formats) of the documentation.
            The special value `"_guess"` (without quotes)
            can be given to let the ORR automatically determine the format.
            (A future version of this API may allow this parameter to be omitted, in such
            case implying the guess-format behavior.)
          required: true
          schema:
            type: string
            format: base64
      responses:
        '200':
          description: |
            Information about the uploaded file.
            The `possibleOntologyIris` object will indicate the possible ontology IRI (or IRIs)
            of the uploaded file. For each IRI, it will indicate some explanation for the
            extraction of such IRI, and the associated metadata, if any.
            On the other hand, the `userName` and `filename` attributes of
            this object are to be used in the subsequent registration to properly refer to
            the uploaded file.

            An example of an actual response:

            ```
            {
              "userName": "carueda",
              "filename": "1477537138555._guess",
              "format": "rdf",
              "possibleOntologyIris": {
                "https://www.w3.org/ns/ssn": {
                  "explanations": [
                    "Resource of type http://www.w3.org/2002/07/owl#Ontology"
                  ],
                  "metadata": {
                    "http://purl.org/dc/elements/1.1/title": [
                      "Semantic Sensor Network Ontology"
                    ],
                    "http://www.w3.org/2000/01/rdf-schema#comment": [
                      "This ontology describes sensors and observations, and related concepts. It does not describe domain concepts, time, locations, etc. as these are intended to be included from other ontologies via OWL imports.",
                      "This ontology is based on the SSN Ontology by the W3C Semantic Sensor Networks Incubator Group (SSN-XG).",
                      "New modular version of the SSN ontology independent of DUL."
                    ],
                    "http://www.w3.org/1999/02/22-rdf-syntax-ns#type": [
                      "http://www.w3.org/2002/07/owl#Ontology"
                    ]
                  }
                }
              }
            }
            ```
      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 `iri`, `oiri`, or `tiri` parameter indicates a request for a
        particular ontology or term.

        If none of the `iri`, `oiri`, and `tiri` 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: iri
          in: query
          required: false
          description: |
            With this parameter the backend will first try an "ontology
            request." If no ontlogy is registered by the given IRI, then it
            will try a "term request."
          schema:
            type: string
            format: base64

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

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

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

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

      responses:
        '200':
          description: Successful response

    post:
      tags: [ontology]
      summary: Registers a brand new ontology
      description: |
        Performs the registration of a brand new ontology in the registry by
        the IRI given in the `iri` attribute of the object in the body.
      operationId: addOnt
      parameters:
        - in: query
          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: "#/components/schemas/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: query
          name: body
          description: |
            Ontology object that needs to be registered.
            Provide the `metadata` attribute to create a new version of
            an existing ontology solely based on changes on the metadata.
            For full contents, use `contents`/`format`, or
            `uploadedFilename`/`uploadedFormat` as described in the `POST /ont`
            operation.
          schema:
            $ref: "#/components/schemas/PutOnt"
      responses:
        "405":
          description: Invalid input
      security:
       - basicAuth: []

    delete:
      tags: [ontology]
      summary: Deletes a particular version or a whole ontology entry
      description: |
        This operation allows to unregister a particular version (if the
        `version` object attribute is given) or a whole ontoloy entry.
        Besides admins, only an owner of the ontology can perform this
        operation.
      operationId: deleteOnt
      parameters:
        - in: query
          name: iri
          description: Ontology IRI
          required: true
          schema:
            type: string
            format: base64
        - in: query
          name: version
          description: |
            Particular version to be deleted.
            If omitted, the whole entry by the given IRI will be unregistered.
          schema:
            type: string
            format: base64
        - in: query
          name: userName
          required: true
          description: |
            Registered user making the request. Must be an owner of the ontology.
          schema:
            type: string
            format: base64

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

  /ont/term:
    post:
      tags: [ontology, term]
      summary: Adds a term to an existing ORR vocabulary
      description: |
        This operation allows to add a new term to an ORR vocabulary.
        This addition does not generate a new version of the vocabulary.
      operationId: addTerm
      parameters:
        - in: query
          name: body
          description: |
            Object with information for the term to be added.
            See the `PostOnt` object description for more details.
          schema:
            $ref: "#/components/schemas/PostTerm"
          required: true
      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

    post:
      tags: [organization]
      summary: Registers an organization
      description: |
        Only admins can perform this operation.
      operationId: addOrg
      parameters:
        - in: query
          name: body
          description: Organization object that needs to be registered
          schema:
            $ref: "#/components/schemas/PostOrg"
      responses:
        "201":
          description: Successful registration
        "405":
          description: Invalid input
      security:
       - basicAuth: []

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

    put:
      tags: [organization]
      summary: Updates information about a registered organization
      operationId: updateOrg
      parameters:
        - name: orgName
          in: path
          required: true
          description: The code (short name) of the organization to be updated.
          schema:
            type: string
            format: base64
        - in: query
          name: body
          description: Object with information for the organization to be updated.
          schema:
            $ref: "#/components/schemas/PutOrg"
      responses:
        "200":
          description: Successful update
        "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
          required: true
          schema:
            type: string
            format: base64

      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

    post:
      tags: [user]
      summary: Registers a user
      description: |
        This operation allows to register a new user in the system.

        **NOTE**: This operation cannot be completed here if the endpoint is configured to
        required a ReCAPTCHA code, which is currently not captured in this interface.
        Please use the ORR Portal interface associated with the endpoint to register
        the new user.

      operationId: addUser
      parameters:
        - in: query
          name: body
          description: User object that needs to be registered
          schema:
            $ref: "#/components/schemas/PostUser"
      responses:
        "400":
          description: |
            If the endpoint is configured to require a ReCAPTCHA code,
            which is not captured in this API interface.
        "405":
          description: Invalid input

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

    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
          required: true
          description: The identifier of the user to be updated.
          schema:
            type: string
            format: base64
        - in: query
          name: body
          description: Object with information for the user to be updated.
          schema:
            $ref: "#/components/schemas/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
          required: true
          schema:
            type: string
            format: base64
      responses:
        "200":
          description: Successful unregistration
        "404":
          description: No such user
      security:
       - basicAuth: []


  ######################################################################
  # Term search
  ######################################################################
  /term:
    get:
      tags: [term]
      summary: Simplified semantic search queries against the triple store
      description: |
        This endpoint route is intended to provide some common semantic search
        operations against the triple store.

        **NOTE**: This is an experimental operation.
        The SPARQL interface remains the most complete and powerful semantic search mechanism.

        Provide one of `containing` or `predicate` as main parameter, along with associated
        auxiliary and optional parameters as described.

      parameters:
        - name: containing
          in: query
          required: false
          description: |
            Searches the given string in the indicated parts of the triples as
            determined by the `in` parameter.
          schema:
            type: string
            format: base64

        - name: in
          in: query
          required: false
          description: |
            Only used in combination with the `containing` parameter, the `in` parameter
            determines where to perform the search: subject, predicate, and/or object.
            Use the 1-character abbreviations: `s` for subject, `p` for predicate, `o` for object.
            Any combination of these characters can be used as value for the `in` parameter.
            For example, to search the given `containing` string in all parts of the triple use `spo`.
            The default value is `s`, meaning the search will only be on the subject.
          schema:
            type: string
            format: base64

        - name: predicate
          in: query
          required: false
          description: |
            Desired predicate to retrieve entities related with a given subject or object.
            The following common namespace prefixes are recognized:
            `skos:`, `owl:`, `rdfs:`, `rdf:`.
            So possible values of this parameter include `skos:relatedMatch` and `owl:sameAs`.
            If the value does not start with any of the recognized prefixes, then it is assumed
            to be a full IRI, e.g., `http://purl.org/dc/terms/description`.

            This parameter is to be used in combination with one of the `subject` or `object` parameters.
            If `subject` is given, the underlying SPARQL query is basically
            `<subject> <predicate> ?object` and the resulting list of objects is returned.
            Otherwise the underlying SPARQL query is basically
            `?subject <predicate> <object>` and the resulting list of subjects is returned.
          schema:
            type: string
            format: base64

        - name: subject
          in: query
          required: false
          description: |
            IRI of the subject for underlying SPARQL query.
            Required when any of the _predicate_ parameters is given and **no** object parameter is given.
          schema:
            type: string
            format: base64

        - name: object
          in: query
          required: false
          description: |
            IRI of the object for underlying SPARQL query.
            Required when any of the _predicate_ parameters is given and **no** subject parameter is given.
          schema:
            type: string
            format: base64

        - name: limit
          in: query
          required: false
          description: |
            Maximum number of solutions to be returned.
            The default value is 30.
            A non-positive value means no limit, so all solutions will be returned.
          schema:
            type: integer
            format: int32

        - name: offset
          in: query
          required: false
          description: |
            Solutions returned will start after the specified number of solutions.
            Ignored if the value is non-positive.
            By default, no offset.
          schema:
            type: integer
            format: int32

      responses:
        '200':
          description: Successful response


  ######################################################################
  # Triplestore
  ######################################################################
  /ts:
    get:
      tags: [triplestore]
      summary: Gets the size of the store or the size of a particular named graph
      description: |
        Provide one of the `iri` or `context` parameters to get the size of a particular graph.
        If none of these parameters is provided, the size of the whole triplestore will be responded.
        Only admins can perform this operation.
      operationId: getTriplestoreSize
      parameters:
        - name: iri
          in: query
          required: false
          description: |
            IRI of particular context
          schema:
            type: string
            format: base64

        - name: context
          in: query
          required: false
          description: |
            IRI of particular context
          schema:
            type: string
            format: base64

      responses:
        '200':
          description: Successful response

    post:
      tags: [triplestore]
      summary: Loads an ontology in the triplestore
      description: |
        Only admins can perform this operation.
      operationId: loadOntInTriplestore
      parameters:
        - name: iri
          in: query
          required: true
          description: |
            IRI of the ontology to be loaded
          schema:
            type: string
            format: base64

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

    put:
      tags: [triplestore]
      summary: Reloads an ontology or all ontologies in the triplestore
      description: |
        Provide the `iri` parameter to reload a particular ontology.
        Otherwise all registered ontologies will be reloaded in the triplestore.
        Only admins can perform this operation.
      operationId: reloadOntsInTriplestore
      parameters:
        - name: iri
          in: query
          required: false
          description: |
            IRI of the ontology to be reloaded
          schema:
            type: string
            format: base64

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

    delete:
      tags: [triplestore]
      summary: Unloads an ontology or all ontologies from the triplestore
      description: |
        Provide the `iri` parameter to unload a particular ontology.
        Otherwise all registered ontologies will be unloaded from the triplestore.
        Only admins can perform this operation.
      operationId: unloadOntsInTriplestore
      parameters:
        - name: iri
          in: query
          required: false
          description: |
            IRI of the ontology to be unloaded
          schema:
            type: string
            format: base64

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


components:
    schemas:
    ######################################################################
    # 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.
          possibleOntologyIris:
            type: object
            description: The format of the file.

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


      PostOnt:
        type: object
        properties:
          iri:
            type: string
            description: |
              The IRI of the ontology.
    
          originalIri:
            type: string
            description: |
              In case of a fully-hosted registration, enter this field to indicate
              the original IRI in the provided contents to be used for the "migration"
              of corresponding entities to the new IRI.
    
          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:
          iri:
            type: string
            description: The IRI 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.
    
          originalIri:
            type: string
            description: |
              In case a fully-hosted registration and ontology contents are provided for this update, enter this field to indicate
              the original IRI to be used for the "migration" of corresponding entities to the IRI 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.
    
      PostTerm:
        type: object
        properties:
          vocIri:
            type: string
            description: |
              The IRI of the affected ORR vocabulary.
    
          version:
            type: string
            description: |
              The version to be affected. By default, latest version.
    
          classIri:
            type: string
            description: |
              IRI of the specific class to be affected within the vocabulary.
              Can be ommitted if the vocabulary only contains one class (which
              will be the one affected).
    
          termName:
            type: string
            description: |
              Simple name of the new term.
    
          termIri:
            type: string
            description: |
              Full IRI of the new term.
    
          attributes:
            type: array
            items:
              type: array
              items:
                type: string
            description: |
              Values for the properties defined for the vocabulary class.
    
      Ont:
        type: object
        properties:
          iri:
            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:
          orgName:
            type: string
          name:
            type: string
          members:
            type: array
            items:
              type: string
    
      OrgNew:
        type: object
        properties:
          orgName:
            type: string
          name:
            type: string
          url:
            type: string
          members:
            type: array
            items:
              type: string
          registeredBy:
            type: string
    
      OrgUpdated:
        type: object
        properties:
          orgName:
            type: string
          name:
            type: string
          url:
            type: string
          members:
            type: array
            items:
              type: string
          updated:
            type: string  # why dateTime fails?
          updatedBy:
            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
          recaptchaResponse:
            type: string
            description: |
              Response provided by a [ReCAPCTHA](https://www.google.com/recaptcha)
              client library. Only required if the ORR Ont endpoint has been configured
              to validate the registration of users in this manner.
    
      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