Clarivate Data - Entity API

openapi: 3.2.0
info:
  title: Converis Web Services Data - Entity API
  description: This API Specification describes how to read data from Converis in order to use it in other systems.
  contact:
    email: converis-info@clarivate.com
  version: '2.0'
servers:
- url: https://api.clarivate.com/converisreadapi
tags:
- name: Data - Entity
  description: Get the entity data
paths:
  /data/entities/{type}:
    get:
      tags:
      - Data - Entity
      summary: Get all data of an entity
      description: 'Get all data of an entity by ___type___ name. Additionally, you can


        * specify language of attribute values through the query parameter ___language___

        * include (excluded by default) linkentity reference API path through HTTP header ___Converis-linkentity-references___. The information about link entities can be requested through the responded paths.

        * include (only basic attributes by default) specific or all attributes definitions of the entity through HTTP Header ___Converis-attribute-definition___


        This endpoint doesn''t require authentication for public data'
      parameters:
      - name: type
        in: path
        description: the entity type name
        required: true
        style: simple
        explode: false
        schema:
          type: string
          example: Publication
      - name: startRecord
        in: query
        description: Starting record.
        required: false
        style: form
        explode: true
        schema:
          minimum: 1
          type: integer
          format: int32
          default: 1
      - name: count
        in: query
        description: maximum number of records to return
        required: false
        style: form
        explode: true
        schema:
          maximum: 50
          minimum: 1
          type: integer
          format: int32
          default: 10
      - name: sort
        in: query
        description: Sort by attributes of the entity. __Currently only BASIC attributes are supported__.
        required: false
        style: form
        explode: true
        schema:
          type: string
          default: Updated on
      - name: sortOrder
        in: query
        description: "Sort order:\n * ___ASC___ - Ascending, from A to Z\n * ___DESC___ - Descending, from Z to A\n"
        required: false
        style: form
        explode: true
        schema:
          type: string
          default: ASC
          enum:
          - ASC
          - DESC
      - name: language
        in: query
        description: Return only labels or attribute data of specific configured language. Display all configured languages if null, eg. en_GB
        required: false
        style: form
        explode: true
        schema:
          type: string
          example: en_GB
      - name: Converis-attribute-definition
        in: header
        description: "The CSV list of attributes to be returned. Possible values BASIC, ALL, csv list of attributes comma separated\n\nBASIC includes\n  * Created by\n  * Created on\n  * Updated by\n  * Updated on\n  * Status\n  * Short description\n  * Public visible\n  * Left sequence (only for link entitites)\n  * Right sequence (only for link entities)\n"
        required: false
        style: simple
        explode: false
        schema:
          default: BASIC
          example: publYear,srcAuthors
          oneOf:
          - type: string
            default: BASIC
            enum:
            - BASIC
            - ALL
          - type: string
            example: publYear, srcAuthors
      - name: Converis-linkentity-references
        in: header
        description: Set true if link entity references (href) should be returned.
        required: false
        style: simple
        explode: false
        schema:
          type: boolean
          example: false
          default: false
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityDataList'
        default:
          description: Error response 400+
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DefaultResponse'
      security:
      - BasicAuth: []
      operationId: getDataEntitiesByType
      x-operation-id-source: derived
  /data/entities/{type}/query:
    post:
      tags:
      - Data - Entity
      summary: Get all data of an entity filtered by query
      description: 'Get all data of an entity by ___type___ name and query. Additionally, you can


        * specify language of attribute values through the query parameter ___language___

        * include (excluded by default) linkentity reference API path through HTTP header ___Converis-linkentity-references___. The information about link entities can be requested through the responded paths.

        * include (only basic attributes by default) specific or all attributes definitions of the entity through HTTP Header ___Converis-attribute-definition___


        This endpoint requires authentication'
      parameters:
      - name: type
        in: path
        description: the entity type name
        required: true
        style: simple
        explode: false
        schema:
          type: string
          example: Publication
      - name: startRecord
        in: query
        description: Starting record.
        required: false
        style: form
        explode: true
        schema:
          minimum: 1
          type: integer
          format: int32
          default: 1
      - name: count
        in: query
        description: maximum number of records to return
        required: false
        style: form
        explode: true
        schema:
          maximum: 50
          minimum: 1
          type: integer
          format: int32
          default: 10
      - name: sort
        in: query
        description: Sort by attributes of the entity. __Currently only BASIC attributes are supported__.
        required: false
        style: form
        explode: true
        schema:
          type: string
          default: Updated on
      - name: sortOrder
        in: query
        description: "Sort order:\n * ___ASC___ - Ascending, from A to Z\n * ___DESC___ - Descending, from Z to A\n"
        required: false
        style: form
        explode: true
        schema:
          type: string
          default: ASC
          enum:
          - ASC
          - DESC
      - name: language
        in: query
        description: Return only labels or attribute data of specific configured language. Display all configured languages if null, eg. en_GB
        required: false
        style: form
        explode: true
        schema:
          type: string
          example: en_GB
      - name: Converis-attribute-definition
        in: header
        description: "The CSV list of attributes to be returned. Possible values BASIC, ALL, csv list of attributes comma separated\n\nBASIC includes\n  * Created by\n  * Created on\n  * Updated by\n  * Updated on\n  * Status\n  * Short description\n  * Public visible\n  * Left sequence (only for link entitites)\n  * Right sequence (only for link entities)\n"
        required: false
        style: simple
        explode: false
        schema:
          default: BASIC
          example: publYear,srcAuthors
          oneOf:
          - type: string
            default: BASIC
            enum:
            - BASIC
            - ALL
          - type: string
            example: publYear, srcAuthors
      - name: Converis-linkentity-references
        in: header
        description: Set true if link entity references (href) should be returned.
        required: false
        style: simple
        explode: false
        schema:
          type: boolean
          example: false
          default: false
      requestBody:
        description: Content of the filter query.
        required: true
        content:
          application/vnd.converis.ql+plain; charset=utf-8:
            schema:
              type: string
              example: '-- POST /converis-apis/data/entities/Publication/query

                -- we assume that Publication has an attribute named openAccess of type BOOLEAN

                openAccess = true AND [publication type] = "Journal Article"

                '
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityDataList'
        default:
          description: Error response 400+
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DefaultResponse'
      security:
      - BasicAuth: []
      operationId: postDataEntitiesByTypeQuery
      x-operation-id-source: derived
  /data/entities/{type}/{id}:
    get:
      tags:
      - Data - Entity
      summary: Get an entity data object
      description: 'Get one entity object by ___type___ name and by ___id___. Additionally, you can


        * specify language of attribute values through the query parameter ___language___

        * include (excluded by default) linkentity reference API path through HTTP header ___Converis-linkentity-references___. The information about link entities can be requested through the responded paths.

        * include (only basic attributes by default) specific or all attributes definitions of the entity through HTTP Header ___Converis-attribute-definition___.


        This endpoint doesn''t require authentication for public data.'
      parameters:
      - name: type
        in: path
        description: entity type name
        required: true
        style: simple
        explode: false
        schema:
          type: string
          example: Publication
      - name: id
        in: path
        description: entry id
        required: true
        style: simple
        explode: false
        schema:
          type: integer
      - name: language
        in: query
        description: Return only labels or attribute data of specific configured language. Display all configured languages if null, eg. en_GB
        required: false
        style: form
        explode: true
        schema:
          type: string
          example: en_GB
      - name: Converis-attribute-definition
        in: header
        description: "The CSV list of attributes to be returned. Possible values BASIC, ALL, csv list of attributes comma separated\n\nBASIC includes\n  * Created by\n  * Created on\n  * Updated by\n  * Updated on\n  * Status\n  * Short description\n  * Public visible\n  * Left sequence (only for link entitites)\n  * Right sequence (only for link entities)\n"
        required: false
        style: simple
        explode: false
        schema:
          example: publYear,srcAuthors
          oneOf:
          - type: string
            default: BASIC
            enum:
            - BASIC
            - ALL
          - type: string
            example: publYear, srcAuthors
      - name: Converis-linkentity-references
        in: header
        description: Set true if link entity references (href) should be returned.
        required: false
        style: simple
        explode: false
        schema:
          type: boolean
          example: false
          default: false
      responses:
        '200':
          description: search results matching criteria
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityData'
        default:
          description: Error response 400+
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DefaultResponse'
      security:
      - BasicAuth: []
      operationId: getDataEntitiesByTypeById
      x-operation-id-source: derived
  /data/entities/{type}/linked/{link_type}/{id}:
    get:
      tags:
      - Data - Entity
      summary: Get the linked data entity entries
      description: 'Get data entity entries of __type__ name that are linked to ___link_type___ filtered by ___id___. Additionally, you can


        * specify language of attribute values through the query parameter ___language___

        * include (excluded by default) linkentity reference API path through HTTP header ___Converis-linkentity-references___. The information about link entities can be requested through the responded paths.

        * include (only basic attributes by default) specific or all attributes definitions of the entity through HTTP Header ___Converis-attribute-definition___


        Please note that this endpoint returns the entity data. For link entity data use _/data/linkentities/{link_type}/linked/{type}/{id}_


        Examples

        ***


        Get the publications which are linked to the Journal 123

        ```

        $curl https://converis.myuniversity.com/converis-apis/ws/v2/data/entities/Publication/linked/PUBL_has_JOUR/123

        ```'
      parameters:
      - name: type
        in: path
        description: Type of the target entity
        required: true
        style: simple
        explode: false
        schema:
          type: string
          example: Publication
      - name: link_type
        in: path
        description: 'linkType represents the link path that helps in getting the target type. The path could be either direct link with or without direction.


          PUBL_has_JOUR - Direct link without direction


          PUBL_has_PUBL - Direct link with same entity on both sides. `direction` necessary'
        required: true
        style: simple
        explode: false
        schema:
          type: string
          example: PUBL_has_JOUR
      - name: id
        in: path
        description: The id of the source entity whose linked item has to be returned. The type of source is determined from the type of linked object to be returned
        required: true
        style: simple
        explode: false
        schema:
          type: integer
          format: int64
      - name: direction
        in: query
        description: "Explaination:\n * ___DIRECT___ - Direct link, i.e. the direction is clear because link entity includes two different entity types\n * ___L2R___ - Direct link with same entity on both sides with direction of traversal Left-2-Right\n * ___R2L___ - Direct link with same entity on both sides with direction of traversal Right-2-Left\n"
        required: false
        style: form
        explode: true
        schema:
          type: string
          default: DIRECT
          enum:
          - DIRECT
          - L2R
          - R2L
      - name: startRecord
        in: query
        description: record to start for pagination
        required: false
        style: form
        explode: true
        schema:
          minimum: 1
          type: integer
          format: int32
          default: 1
      - name: count
        in: query
        description: maximum number of records to return
        required: false
        style: form
        explode: true
        schema:
          maximum: 50
          minimum: 1
          type: integer
          format: int32
          default: 10
      - name: sort
        in: query
        description: Sort by attributes of the entity. __Currently only BASIC attributes are supported__.
        required: false
        style: form
        explode: true
        schema:
          type: string
          default: The sequence id of the entity as it is shown by Browse or Edit page
      - name: sortOrder
        in: query
        description: "Sort order:\n * ___ASC___ - Ascending, from A to Z\n * ___DESC___ - Descending, from Z to A\n"
        required: false
        style: form
        explode: true
        schema:
          type: string
          default: ASC
          enum:
          - ASC
          - DESC
      - name: language
        in: query
        description: Return only labels or attribute data of specific configured language. Display all configured languages if null, eg. en_GB
        required: false
        style: form
        explode: true
        schema:
          type: string
          example: en_GB
      - name: Converis-attribute-definition
        in: header
        description: "The CSV list of attributes to be returned. Possible values BASIC, ALL, csv list of attributes comma separated\n\nBASIC includes\n  * Created by\n  * Created on\n  * Updated by\n  * Updated on\n  * Status\n  * Short description\n  * Public visible\n  * Left sequence (only for link entitites)\n  * Right sequence (only for link entities)\n"
        required: false
        style: simple
        explode: false
        schema:
          example: publYear,srcAuthors
          oneOf:
          - type: string
            default: BASIC
            enum:
            - BASIC
            - ALL
          - type: string
            example: publYear, srcAuthors
      - name: Converis-linkentity-references
        in: header
        description: Set true if link entity references (href) should be returned.
        required: false
        style: simple
        explode: false
        schema:
          type: boolean
          example: false
          default: false
      responses:
        '200':
          description: search results matching criteria
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityDataList'
        default:
          description: Error response 400+
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DefaultResponse'
      security:
      - BasicAuth: []
      operationId: getDataEntitiesByTypeLinkedByLinkTypeById
      x-operation-id-source: derived
components:
  schemas:
    AttributeData:
      required:
      - attributeName
      - attributeType
      - value
      type: object
      properties:
        attributeName:
          type: string
          description: Attribute name
          example: cfTitle
        attributeType:
          type: string
          description: Data type of the Attribute
          example: STRING
          enum:
          - STRING
          - TEXT
          - CGV
          - NUMBER
          - DATE
          - BOOLEAN
        language:
          type: string
          description: language code of this attribute. Empty if not translatable
          example: en_GB
        value:
          type: string
          description: The value of the attribute data
          example: An example Publication title
        choiceGroupData:
          $ref: '#/components/schemas/ChoiceGroupData'
    LabelDefinition:
      required:
      - language
      - value
      type: object
      properties:
        language:
          type: string
          description: The system language abbreviation
          example: en_US
        value:
          type: string
          description: The value of the label
          example: Publication
    EntityData:
      required:
      - createdBy
      - createdOn
      - entityName
      - id
      - intern
      - public
      - shortDescription
      - status
      - updatedBy
      - updatedOn
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: Converis ID of the data entity
          example: 56893426
        entityName:
          type: string
          description: Entity name of this data
          example: Publication
        status:
          type: integer
          description: Status of the given data
          example: 3
        statusLabels:
          type: array
          description: list of short descriptions in different languages
          example:
          - language: en_GB
            value: Validated
          - language: de_DE
            value: Validiert
          items:
            $ref: '#/components/schemas/LabelDefinition'
        public:
          type: boolean
          description: Is the data visible for public
          example: true
        intern:
          type: boolean
          description: Is the data visible for intern
          example: true
        createdBy:
          type: string
          description: User who created this data
          example: configadmin
        createdOn:
          type: string
          description: Creation date of this data
          format: date-time
        updatedBy:
          type: string
          description: User who last updated this data
          example: configadmin
        updatedOn:
          type: string
          description: Last updation date of this data
          format: date-time
        shortDescription:
          type: array
          description: list of short descriptions in different languages
          example:
          - language: en_GB
            value: Some short description
          items:
            $ref: '#/components/schemas/LabelDefinition'
        attributes:
          type: array
          description: list of attributes data for this entity data
          items:
            $ref: '#/components/schemas/AttributeData'
        links:
          type: array
          example:
          - rel: Card
            href: /converis-api/ws/v2/data/entities/Card/linked/PUBL_has_CARD/56893426
          - rel: Organisation
            href: /converis-api/ws/v2/data/entities/Card/linked/PUBL_has_ORGA/56893426
          - rel: Publication
            href: /converis-api/ws/v2/data/entities/Publication/linked/PUBL_has_PUBL/56893426?directon=r2l
          - rel: Publication
            href: /converis-api/ws/v2/data/entities/Publication/linked/PUBL_has_PUBL/56893426?directon=l2r
          items:
            $ref: '#/components/schemas/LinkReference'
    ChoiceGroupData:
      type: object
      properties:
        choiceGroupName:
          type: string
          description: If the attribute is of type ChoiceGroup, then this should be filled.
          example: Publication type
        choiceGroupValue:
          type: string
          description: default value
          example: Journal article
        choiceGroupValueLabels:
          type: array
          example:
          - language: de_DE
            value: Zeitschrift
          items:
            $ref: '#/components/schemas/LabelDefinition'
    DefaultResponse:
      required:
      - statusDescirption
      - message
      - path
      - status
      - timestamp
      type: object
      properties:
        timestamp:
          type: string
          description: The date-time notation as defined by RFC 3339, section 5.6, e.g. "2017-07-21T17:32:28Z"
          format: date-time
        path:
          type: string
          description: The path which is used by user, e.g./converis-apis/ws/v2/data/entities/Publication
          format: uri
        status:
          type: integer
          description: HTTP Status code,e.g. 400+
          example: 400
        statusDescription:
          type: string
          description: Description of HTTP Status code, e.g. Bad Request
          example: Bad Request
        message:
          type: string
          description: The detailed description of the error
    LinkReference:
      required:
      - rel
      - href
      type: object
      properties:
        rel:
          type: string
          description: Describes the type of relationship.
          example: Publication
        href:
          type: string
          description: is the complete endpoint path that uniquely defines the resource.
          example: /converis-apis/ws/v2/data/Publication/linked/PUBL_has_JOUR/1234
    EntityDataList:
      required:
      - count
      - nrRecordsAll
      - nrRecordsFound
      - startRecord
      type: object
      properties:
        startRecord:
          type: integer
          example: 1
        count:
          type: integer
          example: 50
        nrRecordsAll:
          type: integer
          example: 1540
        nrRecordsFound:
          type: integer
          example: 50
        data:
          type: array
          items:
            $ref: '#/components/schemas/EntityData'
  securitySchemes:
    BasicAuth:
      type: http
      description: The authentication information has to be provided by the client application as Basic authentication header. This can be configured by an admin in Converis under Configuration -> API Authentication Info.
      scheme: basic