Clarivate References API

openapi: 3.2.0
info:
  title: EndNote REST References API
  description: Create and update references in an Endnote library
  contact:
    name: EndNote API Beta Coordinator
    email: gillian.neff@clarivate.com
  version: 1.0.0
servers:
- url: https://api.clarivate.com/api/endnote/v1
security:
- Log In, accessCode: []
tags:
- name: References
paths:
  /references/{guid}/file:
    parameters:
    - name: guid
      in: path
      required: true
      schema:
        type: string
    - $ref: '#/components/parameters/routingHeader'
    - $ref: '#/components/parameters/acceptHeader'
    - $ref: '#/components/parameters/contentTypeHeader'
    post:
      summary: Create a file attached to this reference
      description: 'File Content must send in the request body. Client Application must provide the guid of the attaching reference in request header x-enws-reference-guid as well as name in request header x-enws-name and checksum (CRC32) in request header x-enws-checksumA file name is mandatory when creating an attachment. Client Application can send it in the request header: x-enws-name. The server will respond with 400 if any mandatory header is missing. If succeed, the server will respond with 201 created, and place in responde header Location the specific URI to this attachment.'
      operationId: create/references/{guid}/file
      responses:
        '201':
          description: 'Create a new file attachment. '
      requestBody:
        content:
          application/octet-stream:
            schema:
              format: binary
              type: string
        description: File content as stream of bytes.
      tags:
      - References
  /references/{guid}:
    parameters:
    - name: guid
      in: path
      required: true
      schema:
        type: string
    - $ref: '#/components/parameters/routingHeader'
    - $ref: '#/components/parameters/acceptHeader'
    - $ref: '#/components/parameters/contentTypeHeader'
    get:
      summary: Retreive the set of fields of a specific reference
      description: Accept request header will contain the format of the set of data in the response body. By default, we accept application/json. If client application request a reference content in a format that server is not able to process, the server will respond with 406.After a successful process of this operation, the server respond with 200. Field result contains the name of the field that will contain the reference content. By default, it is data.If a client application has previously deleted this reference, there will be no field containing this reference content, but the server still responds with 200.
      operationId: read/references/{guid}
      responses:
        '200':
          description: 'Retrieve the content of this resource. '
          content:
            application/json:
              schema:
                description: A resource is any object addressed by a URI. it is actually a wrapper of the object, and it can wrap either a single object or a collection of objects (Collection resource).It is basically the URI object with resource content. Properties id and display are not included because either are included in the resource content or are irrelevant.Property result value has the name of the property a GET operation will include resource data. Property on contains the timestamp when this request was processed by the server. Server has included this date in any property of type DATE processed by it (system or readOnly).  If the resource is collection, this object will have additional properties and uris, implementing Collection Iterator pattern.Property pageSize value is the amount of objets from the server.Property page value is the page number of the iteration.Property orderBy is a collection of ORDER object that specifies the collection sorting.If the size of the collection is smaller than pageSize value, property total will be included with the size of the collection, and server will include no other collection property but pageSize.first, previous, next, last are uri properties that replacing the current uri property will set the collection to first, previous, next or last page. Total uri will complete this object by including properties total and lastPage.
                properties:
                  attachmentLimit:
                    format: int64
                    description: Total amount of files that can be attached to this reference. A positive Number
                    default: 0
                    type: integer
                  results:
                    description: Name of the property whose value will be the data of this resource.
                    type: string
                  data:
                    $ref: '#/components/schemas/roareference'
                  'on':
                    format: int64
                    description: 'TimeStamp of the processing of the current request. Its value is actually a date: milliseconds since 01/01/1970 in GMT'
                    type: integer
                  figureLimit:
                    format: int64
                    description: Total amount of figures that can be attached to this reference. A positive Number
                    default: 0
                    type: integer
                type: object
        '201':
          description: 'Create a new resource in the server or a new URI to address it. '
      tags:
      - References
    put:
      summary: Change a set of this reference bibliographic content fields
      description: Field biblioContent is a required field in the request. It must contains at least the set of field values the user would like to change, but it can include unchanged fields too. If the user has made some changes in this reference with another application, the server will respond with 409 Conflict, and it will send the current state of this reference in the server in the field conflicts. Client applications may ask the user to resolve this conflict. Replace this url with the url included in the field uri, otherwise server will keep responding with 409. Server will respond with 201 and will place a new URI to access to this reference in LOCATION header. This new URI includes the current updateSequenceNumber, soit must replece the original one in order to send the next update without conflicts.
      operationId: update/references/{guid}
      responses:
        '200':
          description: 'Retrieve the content of this resource. '
          content:
            application/json:
              schema:
                description: A resource is any object addressed by a URI. it is actually a wrapper of the object, and it can wrap either a single object or a collection of objects (Collection resource).It is basically the URI object with resource content. Properties id and display are not included because either are included in the resource content or are irrelevant.Property result value has the name of the property a GET operation will include resource data. Property on contains the timestamp when this request was processed by the server. Server has included this date in any property of type DATE processed by it (system or readOnly).  If the resource is collection, this object will have additional properties and uris, implementing Collection Iterator pattern.Property pageSize value is the amount of objets from the server.Property page value is the page number of the iteration.Property orderBy is a collection of ORDER object that specifies the collection sorting.If the size of the collection is smaller than pageSize value, property total will be included with the size of the collection, and server will include no other collection property but pageSize.first, previous, next, last are uri properties that replacing the current uri property will set the collection to first, previous, next or last page. Total uri will complete this object by including properties total and lastPage.
                properties:
                  attachmentLimit:
                    format: int64
                    description: Total amount of files that can be attached to this reference. A positive Number
                    default: 0
                    type: integer
                  results:
                    description: Name of the property whose value will be the data of this resource.
                    type: string
                  data:
                    $ref: '#/components/schemas/roareference'
                  'on':
                    format: int64
                    description: 'TimeStamp of the processing of the current request. Its value is actually a date: milliseconds since 01/01/1970 in GMT'
                    type: integer
                  figureLimit:
                    format: int64
                    description: Total amount of figures that can be attached to this reference. A positive Number
                    default: 0
                    type: integer
                type: object
        '201':
          description: 'Create a new resource in the server or a new URI to address it. '
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/roareference'
      tags:
      - References
components:
  schemas:
    roareference:
      description: 'Metadata of a bibliographic content. This object wraps a bibliographic content adding a set of fields for ENWS Services processing. While bibliographic content is an agnostic set of fields for any environment, Reference object contains a set of fields for ENWS Services. '
      properties:
        guid:
          description: 'Unique identifier of this reference. in ENWS Services. '
          readOnly: true
          type: string
        updated:
          format: int64
          description: 'Date of the lastest change of this reference. Its value is actually a date: milliseconds since 01/01/1970 in GMT'
          readOnly: true
          type: integer
        created:
          format: int64
          description: 'Date when this reference was added to the user''s library. Its value is actually a date: milliseconds since 01/01/1970 in GMT'
          readOnly: true
          type: integer
        biblioContent:
          description: 'Object that contains all bibliografic fields of this reference. When created this field is mandatory and at least one of its field must have a value. '
          properties:
            custom1:
              description: 'If client application needs bibliocontent fields not included in this object, it can use this field to store its values. '
              type: string
            edition:
              description: Edition of the book referred by this reference
              type: string
            custom2:
              description: 'If client application needs bibliocontent fields not included in this object, it can use this field to store its values. '
              type: string
            custom3:
              description: 'If client application needs bibliocontent fields not included in this object, it can use this field to store its values. '
              type: string
            secondaryTitle:
              description: Secondary title of this reference
              type: string
            custom4:
              description: 'If client application needs bibliocontent fields not included in this object, it can use this field to store its values. '
              type: string
            custom5:
              description: 'If client application needs bibliocontent fields not included in this object, it can use this field to store its values. '
              type: string
            custom6:
              description: 'If client application needs bibliocontent fields not included in this object, it can use this field to store its values. '
              type: string
            custom7:
              description: 'If client application needs bibliocontent fields not included in this object, it can use this field to store its values. '
              type: string
            databaseProvider:
              description: Provider of the database of this reference
              type: string
            custom8:
              description: Last Date modified
              type: string
            researchNotes:
              description: Research notes
              type: string
            authors:
              description: Collection of authors
              type: string
            callNumber:
              description: Call number
              type: string
            year:
              description: Year of the publication
              type: string
            electronicResourceNumber:
              description: Electronic Resource Number
              type: string
            nameOfDatabase:
              description: Name of the database where to find this reference
              type: string
            keywords:
              description: Collection of keywords of the paper
              type: string
            tertiaryTitle:
              description: Tertiary title of this reference
              type: string
            label:
              description: Label
              type: string
            number:
              description: Number
              type: string
            accessDate:
              description: Date of access
              type: string
            url:
              description: URL
              type: string
            subsidiaryAuthors:
              description: Subsidiary authors
              type: string
            accessionNumber:
              description: Accession number
              type: string
            language:
              description: Language
              type: string
            secondaryAuthors:
              description: Collection of secondary authors
              type: string
            alternateTitle:
              description: Alternative title of publication
              type: string
            placePublished:
              description: Place of publication
              type: string
            originalPublication:
              description: Original Publication
              type: string
            date:
              description: Date
              type: string
            publisher:
              description: Publisher
              type: string
            title:
              description: Title of this reference
              type: string
            referenceType:
              format: int64
              description: Type of Reference. Client Application may use GET in /reference/types URI in order to get the list of types. When creating a new reference the value of this field must be one of the field value of that list of types. This field is not madatory. By default, it will be 17, Journal Article. A positive Number
              default: 0
              type: integer
            isbn:
              description: ISBN
              type: string
            abstract:
              description: Abstract of the paper
              type: string
            reviewedItem:
              description: Reviewed Item
              type: string
            translatedTitle:
              description: Translated title
              type: string
            translatedAuthors:
              description: Collection of translated authors
              type: string
            tertiaryAuthors:
              description: Tertiary authors
              type: string
            pages:
              description: Total pages of publication
              type: string
            reprintEdition:
              description: Reprinted Edition
              type: string
            caption:
              description: Caption
              type: string
            section:
              description: Section where to find this reference
              type: string
            numberOfVolumes:
              description: Total of volumes
              type: string
            shortTitle:
              description: Short title of the publication
              type: string
            volume:
              description: Volumen of the book
              type: string
            typeOfWork:
              description: Type of publication
              type: string
            notes:
              description: Notes
              type: string
            authorAddress:
              description: Author address
              type: string
          type: object
        updateSequenceNum:
          format: int64
          description: This number represent the current state of this reference. Changes in any field of this reference will make this number increase.,When user wants to perform a change in this reference, client application must submit this field with the changes of the user If the submitting value of this field from client application matches with the value of this field stored in the server, the server will perform requested changes, and update this field. If both values are not matchings, the server will response with HTTP response code 409, and it will include in the response payload, the current state of this reference.,Server will response with a conflict (409) when this reference were change by other application after getting this reference state. As client application has missed this later changes, server cannot decide if accept this changes or reject them, so respond sending the current state of the object. Client may ignore this conflict and override the state of the reference by including the value of this field. Client may track the first reference state, the changes made of the user, and the current state of the reference. If there is no conflict, submit the changes by including the last updateSequenceNum. Otherwise. it may show the conflicts to the user in order to make a decission. A positive Number
          readOnly: true
          default: 0
          type: integer
        uri:
          $ref: '#/components/schemas/uri'
        fileCount:
          format: int64
          description: Number of files currently attached to this reference. A positive Number
          default: 0
          type: integer
        fileFactoryUri:
          $ref: '#/components/schemas/uri'
      type: object
    uri:
      properties:
        system:
          description: As true, POST method is not allowed
          readOnly: true
          default: false
          type: boolean
        readOnly:
          description: As true, PUT method is not allowed
          readOnly: true
          default: false
          type: boolean
        idValue:
          description: Unique Identifier of a pointed resource
          readOnly: true
          type: string
        hidden:
          description: As true, GET method is not allowed
          readOnly: true
          default: false
          type: boolean
        mandatory:
          description: As true, DELETE method is not allowed
          readOnly: true
          default: false
          type: boolean
        display:
          description: Name of the resource to show users
          readOnly: true
          type: string
        uri:
          description: URL pointing to a resource
          readOnly: true
          type: string
      type: object
  parameters:
    routingHeader:
      description: 'Routing header. This header is generated in a response when not included in the request (first request), and it must be included in the next request. Request that include this header will be be faster. '
      name: x-enws-authorization
      in: header
      required: true
      schema:
        type: string
    contentTypeHeader:
      description: 'Contains the format of the data sent in the request body. This header has no effect when GET or OPTIONS methods. '
      name: Content-Type
      in: header
      schema:
        type: string
    acceptHeader:
      description: 'Contains the format of the data of the response or any error sent by the server placed in the response body. '
      name: Accept
      in: header
      required: true
      schema:
        type: string
  securitySchemes:
    Log_In__accessCode:
      type: oauth2
      flows:
        authorizationCode:
          scopes: {}
          authorizationUrl: https://api.clarivate.com/auth/steam/api/endnote/authorize
          tokenUrl: https://api.clarivate.com/auth/steam/api/endnote/token