La Trobe University collections API

openapi: 3.0.3
info:
  title: La Trobe University OPAL (Figshare) Public articles collections API
  description: Public, machine-readable retrieval surface for La Trobe University's open-access repository, OPAL (Open @ La Trobe), which is hosted on the Figshare platform and served by the Figshare REST API v2. La Trobe records are institution-scoped (institution id 234). This document is a faithful subset of the upstream Figshare API 2.0 OpenAPI description (https://docs.figshare.com/swagger.json), limited to the public, unauthenticated article and collection retrieval/search/files/versions endpoints used to harvest OPAL content. No private/account or write operations are included.
  version: '2.0'
  contact:
    name: Figshare Support
    url: https://support.figshare.com/support/home
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://api.figshare.com/v2
  description: Figshare API v2 (serves La Trobe OPAL records, institution=234)
tags:
- name: collections
paths:
  /collections:
    get:
      tags:
      - collections
      summary: Public Collections
      description: Returns a list of public collections
      operationId: collections_list
      parameters:
      - name: X-Cursor
        in: header
        description: Unique hash used for bypassing the item retrieval limit of 9,000 entities. When using this parameter, please note that the offset parameter will not be available, but the limit parameter will still work as expected.
        schema:
          type: string
      - name: page
        in: query
        description: Page number. Used for pagination with page_size
        schema:
          maximum: 5000
          minimum: 1
          type: integer
      - name: page_size
        in: query
        description: The number of results included on a page. Used for pagination with page
        schema:
          maximum: 1000
          minimum: 1
          type: integer
          default: 10
      - name: limit
        in: query
        description: Number of results included on a page. Used for pagination with query
        schema:
          maximum: 1000
          minimum: 1
          type: integer
      - name: offset
        in: query
        description: Where to start the listing (the offset of the first result). Used for pagination with limit
        schema:
          maximum: 5000
          minimum: 0
          type: integer
      - name: order
        in: query
        description: The field by which to order. Default varies by endpoint/resource.
        schema:
          type: string
          default: published_date
          enum:
          - published_date
          - created_date
          - modified_date
          - views
          - shares
          - cites
      - name: order_direction
        in: query
        schema:
          type: string
          default: desc
          enum:
          - asc
          - desc
      - name: institution
        in: query
        description: only return collections from this institution
        schema:
          type: integer
      - name: published_since
        in: query
        description: Filter by collection publishing date. Will only return collections published after the date. date(ISO 8601) YYYY-MM-DD
        schema:
          type: string
      - name: modified_since
        in: query
        description: Filter by collection modified date. Will only return collections modified after the date. date(ISO 8601) YYYY-MM-DD
        schema:
          type: string
      - name: group
        in: query
        description: only return collections from this group
        schema:
          type: integer
      - name: resource_doi
        in: query
        description: only return collections with this resource_doi
        schema:
          type: string
      - name: doi
        in: query
        description: only return collections with this doi
        schema:
          type: string
      - name: handle
        in: query
        description: only return collections with this handle
        schema:
          type: string
      responses:
        '200':
          description: OK. An array of collections
          headers:
            X-Cursor:
              description: Unique hash used for bypassing the item retrieval limit of 9,000 entities.
              schema:
                type: string
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Collection'
        '400':
          description: Bad Request
          content: {}
        '422':
          description: Bad Request
          content: {}
        '500':
          description: Internal Server Error
          content: {}
      security: []
  /collections/search:
    post:
      tags:
      - collections
      summary: Public Collections Search
      description: Returns a list of public collections
      operationId: collections_search
      parameters:
      - name: X-Cursor
        in: header
        description: Unique hash used for bypassing the item retrieval limit of 9,000 entities. When using this parameter, please note that the offset parameter will not be available, but the limit parameter will still work as expected.
        schema:
          type: string
      requestBody:
        description: Search Parameters
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CollectionSearch'
        required: false
      responses:
        '200':
          description: OK. An array of collections
          headers:
            X-Cursor:
              description: Unique hash used for bypassing the item retrieval limit of 9,000 entities.
              schema:
                type: string
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Collection'
        '400':
          description: Bad Request
          content: {}
        '422':
          description: Bad Request
          content: {}
        '500':
          description: Internal Server Error
          content: {}
      security: []
      x-codegen-request-body-name: search
  /collections/{collection_id}:
    get:
      tags:
      - collections
      summary: Collection details
      description: View a collection
      operationId: collection_details
      parameters:
      - name: collection_id
        in: path
        description: Collection Unique identifier
        required: true
        schema:
          minimum: 1
          type: integer
      responses:
        '200':
          description: OK. Collection representation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionComplete'
        '400':
          description: Bad Request
          content: {}
        '404':
          description: Not Found
          content: {}
        '500':
          description: Internal Server Error
          content: {}
      security: []
      x-subcategory: Public Collection
  /collections/{collection_id}/articles:
    get:
      tags:
      - collections
      summary: Public Collection Articles
      description: Returns a list of public collection articles
      operationId: collection_articles
      parameters:
      - name: collection_id
        in: path
        description: Collection Unique identifier
        required: true
        schema:
          minimum: 1
          type: integer
      - name: page
        in: query
        description: Page number. Used for pagination with page_size
        schema:
          maximum: 5000
          minimum: 1
          type: integer
      - name: page_size
        in: query
        description: The number of results included on a page. Used for pagination with page
        schema:
          maximum: 1000
          minimum: 1
          type: integer
          default: 10
      - name: limit
        in: query
        description: Number of results included on a page. Used for pagination with query
        schema:
          maximum: 1000
          minimum: 1
          type: integer
      - name: offset
        in: query
        description: Where to start the listing (the offset of the first result). Used for pagination with limit
        schema:
          maximum: 5000
          minimum: 0
          type: integer
      responses:
        '200':
          description: OK. An array of articles belonging to the collection
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Article'
        '400':
          description: Bad Request
          content: {}
        '404':
          description: Not Found
          content: {}
        '422':
          description: Bad Request
          content: {}
        '500':
          description: Internal Server Error
          content: {}
      security: []
components:
  schemas:
    CommonSearch:
      type: object
      properties:
        search_for:
          type: string
          description: Search term
          example: figshare
        page:
          maximum: 5000
          minimum: 1
          type: integer
          description: Page number. Used for pagination with page_size
          example: 1
        page_size:
          maximum: 1000
          minimum: 1
          type: integer
          description: The number of results included on a page. Used for pagination with page
          example: 10
          default: 10
        limit:
          maximum: 1000
          minimum: 1
          type: integer
          description: Number of results included on a page. Used for pagination with query
          example: 10
        offset:
          maximum: 5000
          minimum: 0
          type: integer
          description: Where to start the listing (the offset of the first result). Used for pagination with limit
          example: 0
        order_direction:
          type: string
          description: Direction of ordering
          example: desc
          default: desc
          enum:
          - asc
          - desc
        institution:
          type: integer
          description: only return collections from this institution
          example: 2000013
        published_since:
          type: string
          description: Filter by article publishing date. Will only return articles published after the date. date(ISO 8601) YYYY-MM-DD or date-time(ISO 8601) YYYY-MM-DDTHH:mm:ssZ
          example: '2017-12-22'
        modified_since:
          type: string
          description: Filter by article modified date. Will only return articles modified after the date. date(ISO 8601) YYYY-MM-DD or date-time(ISO 8601) YYYY-MM-DDTHH:mm:ssZ
          example: '2017-12-22'
        group:
          type: integer
          description: only return collections from this group
          example: 2000013
      x-tag: common
    CollectionComplete:
      required:
      - articles_count
      - authors
      - categories
      - citation
      - created_date
      - custom_fields
      - description
      - funding
      - group_id
      - institution_id
      - keywords
      - modified_date
      - public
      - references
      - related_materials
      - resource_doi
      - resource_id
      - resource_link
      - resource_title
      - resource_version
      - tags
      - timeline
      - version
      properties:
        funding:
          type: array
          description: Full Collection funding information
          items:
            $ref: '#/components/schemas/FundingInformation'
        resource_id:
          type: string
          description: Collection resource id
          example: ''
        resource_doi:
          type: string
          description: Collection resource doi
          example: 10.6084/m9.figshare.123
        resource_title:
          type: string
          description: Collection resource title
          example: test
        resource_link:
          type: string
          description: Collection resource link
          example: http://figshare.com
        resource_version:
          type: integer
          description: Collection resource version
          example: 0
        version:
          type: integer
          description: Collection version
          example: 1
        description:
          type: string
          description: Collection description
          example: description
        categories:
          type: array
          description: List of collection categories
          items:
            $ref: '#/components/schemas/Category'
        references:
          type: array
          description: List of collection references
          items:
            type: string
            format: url
        related_materials:
          type: array
          description: List of related materials; supersedes references and resource DOI/title.
          example:
          - id: 10432
            identifier: 10.6084/m9.figshare.1407024
            identifier_type: DOI
            relation: IsSupplementTo
            title: Figshare for institutions brochure
            is_linkout: false
          items:
            $ref: '#/components/schemas/RelatedMaterial'
        tags:
          type: array
          description: List of collection tags. Keywords can be used instead
          example:
          - t1
          - t2
          items:
            type: string
        keywords:
          type: array
          description: List of collection keywords. Tags can be used instead
          example:
          - t1
          - t2
          items:
            type: string
        authors:
          type: array
          description: List of collection authors
          items:
            $ref: '#/components/schemas/Author'
        institution_id:
          type: integer
          description: Collection institution
          example: 1
        group_id:
          type: integer
          description: Collection group
          example: 1
        articles_count:
          type: integer
          description: Number of articles in collection
          example: 1
        public:
          type: boolean
          description: True if collection is published
          example: true
        citation:
          type: string
          description: Collection citation
          example: citation
        custom_fields:
          type: array
          description: Collection custom fields
          items:
            $ref: '#/components/schemas/CustomArticleField'
        modified_date:
          type: string
          description: Date when collection was last modified
          example: '2017-05-15T15:12:26Z'
        created_date:
          type: string
          description: Date when collection was created
          example: '2017-05-15T15:12:26Z'
        timeline:
          $ref: '#/components/schemas/Timeline'
      allOf:
      - $ref: '#/components/schemas/Collection'
      x-tag: collections
    FundingInformation:
      required:
      - funder_name
      - grant_code
      - id
      - is_user_defined
      - title
      - url
      type: object
      properties:
        id:
          type: integer
          description: Funding id
          example: 1
        title:
          type: string
          description: The funding name
          example: Scholarly funding
        grant_code:
          type: string
          description: The grant code
        funder_name:
          type: string
          description: Funder's name
        is_user_defined:
          type: integer
          description: Return 1 whether the grant has been introduced manually, 0 otherwise
        url:
          type: string
          description: The grant url
          format: url
          example: https://app.dimensions.ai/details/grant/1
      x-tag: funding
    CollectionSearch:
      properties:
        resource_doi:
          type: string
          description: Only return collections with this resource_doi
          example: 10.6084/m9.figshare.1407024
        doi:
          type: string
          description: Only return collections with this doi
          example: 10.6084/m9.figshare.1407024
        handle:
          type: string
          description: Only return collections with this handle
          example: 10084/figshare.1407024
        order:
          type: string
          description: The field by which to order.
          example: published_date
          default: created_date
          enum:
          - created_date
          - published_date
          - modified_date
          - views
          - shares
          - cites
      allOf:
      - $ref: '#/components/schemas/CommonSearch'
      x-tag: collections
    Timeline:
      allOf:
      - $ref: '#/components/schemas/TimelineUpdate'
      x-tag: timeline
    CustomArticleField:
      required:
      - field_type
      - is_mandatory
      - name
      - order
      - settings
      - value
      type: object
      properties:
        name:
          type: string
          description: Custom  metadata name
          example: key
        value:
          type: object
          description: Custom metadata value (can be either a string or an array of strings)
          example: value
        field_type:
          type: string
          description: Custom field type
          example: textarea
          enum:
          - text
          - textarea
          - dropdown
          - url
          - email
          - date
          - dropdown_large_list
        settings:
          type: object
          properties: {}
          description: Settings for the custom field
          example:
            validations:
              min_length: 1
              max_length: 1000
            placeholder: Enter your custom field here
        order:
          type: integer
          description: Order of the custom field
          example: 1
        is_mandatory:
          type: boolean
          description: Whether the field is mandatory or not
          example: false
      x-tag: articles
    Collection:
      required:
      - doi
      - handle
      - id
      - timeline
      - title
      - url
      type: object
      properties:
        id:
          type: integer
          description: Collection id
          example: 123
        title:
          type: string
          description: Collection title
          example: Sample collection
        doi:
          type: string
          description: Collection DOI
          example: 10.6084/m9.figshare.123
        handle:
          type: string
          description: Collection Handle
          example: 111184/figshare.1234
        url:
          type: string
          description: Api endpoint
          example: https://api.figshare.com/v2/collections/123
        timeline:
          $ref: '#/components/schemas/Timeline'
      x-tag: collections
    Category:
      required:
      - id
      - parent_id
      - path
      - source_id
      - taxonomy_id
      - title
      type: object
      properties:
        parent_id:
          type: integer
          description: Parent category
          example: 1
        id:
          type: integer
          description: Category id
          example: 11
        title:
          type: string
          description: Category title
          example: Anatomy
        path:
          type: string
          description: Path to all ancestor ids
          example: /450/1024/6532
        source_id:
          type: string
          description: ID in original standard taxonomy
          example: '300204'
        taxonomy_id:
          type: integer
          description: Internal id of taxonomy the category is part of
          example: 4
      x-tag: common
    RelatedMaterial:
      type: object
      properties:
        id:
          type: integer
          description: The ID of the related material; can be used to add existing materials of the same account to items.
          example: 10432
        identifier:
          type: string
          description: The related material identifier (e.g., DOI, Handle, ISBN). Mandatory if creating a new material.
          example: 10.6084/m9.figshare.1407024
        title:
          type: string
          description: The related material title
          example: 'Rooter: A Methodology for the Typical Unification of Access Points and Redundancy'
        relation:
          type: string
          description: The relation between the item and the related material; defaults to 'References'. Mandatory if creating a new material.
          example: IsSupplementTo
          default: References
          enum:
          - IsCitedBy
          - Cites
          - IsSupplementTo
          - IsSupplementedBy
          - IsContinuedBy
          - Continues
          - Describes
          - IsDescribedBy
          - HasMetadata
          - IsMetadataFor
          - HasVersion
          - IsVersionOf
          - IsNewVersionOf
          - IsPreviousVersionOf
          - IsPartOf
          - HasPart
          - IsPublishedIn
          - IsReferencedBy
          - References
          - IsDocumentedBy
          - Documents
          - IsCompiledBy
          - Compiles
          - IsVariantFormOf
          - IsOriginalFormOf
          - IsIdenticalTo
          - IsReviewedBy
          - Reviews
          - IsDerivedFrom
          - IsSourceOf
          - IsRequiredBy
          - Requires
          - IsObsoletedBy
          - Obsoletes
        identifier_type:
          type: string
          description: The type of the identifier of the related material; defaults to 'URL'. Mandatory if creating a new material.
          example: DOI
          default: URL
          enum:
          - ARK
          - arXiv
          - bibcode
          - DOI
          - EAN13
          - EISSN
          - Handle
          - IGSN
          - ISBN
          - ISSN
          - ISTC
          - LISSN
          - LSID
          - PMID
          - PURL
          - UPC
          - URL
          - URN
          - w3id
        is_linkout:
          type: boolean
          description: Flag for highlighting this related material in the call-out box
          example: true
        link:
          type: string
          description: The full hyperlink for the identifier. Automatically generated by Figshare.
          readOnly: true
          example: https://doi.org/10.6084/m9.figshare.1407024
    Author:
      required:
      - first_name
      - full_name
      - id
      - is_active
      - last_name
      - orcid_id
      - url_name
      type: object
      properties:
        id:
          type: integer
          description: Author id
          example: 97657
        full_name:
          type: string
          description: Author full name
          example: John Doe
        first_name:
          type: string
          description: Author first name
          example: John
        last_name:
          type: string
          description: Author last name
          example: Doe
        is_active:
          type: boolean
          description: True if author has published items
          example: false
        url_name:
          type: string
          description: Author url name
          example: John_Doe
        orcid_id:
          type: string
          description: Author Orcid
          example: 1234-5678-9123-1234
      x-tag: authors
    Article:
      required:
      - created_date
      - defined_type
      - defined_type_name
      - doi
      - handle
      - id
      - resource_doi
      - resource_title
      - thumb
      - timeline
      - title
      - url
      - url_private_api
      - url_private_html
      - url_public_api
      - url_public_html
      type: object
      properties:
        id:
          type: integer
          description: Unique identifier for article
          example: 1434614
        title:
          type: string
          description: Title of article
          example: Test article title
        doi:
          type: string
          description: DOI
          example: 10.6084/m9.figshare.1434614
        handle:
          type: string
          description: Handle
          example: 111184/figshare.1234
        url:
          type: string
          description: Api endpoint for article
          format: url
          example: http://api.figshare.com/articles/1434614
        url_public_html:
          type: string
          description: Public site endpoint for article
          format: url
          example: https://figshare.com/articles/media/Test_article_title/1434614
        url_public_api:
          type: string
          description: Public Api endpoint for article
          format: url
          example: https://api.figshare.com/articles/1434614
        url_private_html:
          type: string
          description: Private site endpoint for article
          format: url
          example: https://figshare.com/account/articles/1434614
        url_private_api:
          type: string
          description: Private Api endpoint for article
          format: url
          example: https://api.figshare.com/account/articles/1434614
        timeline:
          $ref: '#/components/schemas/Timeline'
        thumb:
          type: string
          description: Thumbnail image
          format: url
          example: https://ndownloader.figshare.com/files/123456789/preview/12345678/thumb.png
        defined_type:
          type: integer
          description: Type of article identifier
          example: 3
        defined_type_name:
          type: string
          description: Name of the article type identifier
          example: media
        resource_doi:
          type: string
          description: Deprecated by related materials. Not applicable to regular users. In a publisher case, this is the publisher article DOI.
          default: ''
        resource_title:
          type: string
          description: Deprecated by related materials. Not applicable to regular users. In a publisher case, this is the publisher article title.
          default: ''
        created_date:
          type: string
          description: Date when article was created
          example: '2017-05-18T11:49:03Z'
      x-tag: articles
    TimelineUpdate:
      type: object
      properties:
        firstOnline:
          type: string
          description: Online posted date
          example: '2015-12-31'
        publisherPublication:
          type: string
          description: Publish date
          example: '2015-12-31'
        publisherAcceptance:
          type: string
          description: Date when the item was accepted for publication
          example: '2015-12-31'
      x-tag: timeline_update