openapi: 3.0.0
info:
  title: REST activities reports API
  description: The REST API is used for all API interactions with DataCite services.
  contact:
    name: DataCite Support
    url: https://support.datacite.org
    email: support@datacite.org
  license:
    name: MIT
    url: https://raw.githubusercontent.com/datacite/lupo/master/LICENSE
  version: 2.3.0
servers:
- url: https://api.test.datacite.org
  description: Staging server
- url: https://api.datacite.org
  description: Production server
security:
- {}
- BasicAuth: []
- bearerAuth: []
tags:
- name: reports
  description: Reports
paths:
  /reports:
    get:
      tags:
      - reports
      summary: A JSON array of reports.
      security: []
      parameters:
      - in: query
        name: platform
        description: Name of the Platform the usage is being requested for. This can be omitted if the service provides usage for only one platform.
        schema:
          type: string
      - in: query
        name: report-name
        description: The long name of the report.
        schema:
          type: string
      - in: query
        name: report-id
        description: The report ID or code or shortname. Typically this will be the same code provided in the Report parameter of the request.
        schema:
          type: string
      - in: query
        name: release
        description: The release or version of the report.
        schema:
          type: string
      - in: query
        name: created
        description: Time the report was prepared. Format as defined by date-time - RFC3339
        schema:
          type: string
          format: date-time
      - in: query
        name: created-by
        description: Name of the organization producing the report.
        schema:
          type: string
      - in: query
        $ref: '#/components/parameters/pageNumberParam'
      - in: query
        $ref: '#/components/parameters/pageSizeParam'
      responses:
        '200':
          description: A JSON array of reports.
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Report'
                  meta:
                    type: object
                    properties:
                      total:
                        description: Total results count.
                        type: number
                      total-pages:
                        description: Total pages count.
                        type: number
                      page:
                        description: Current page of the results.
                        type: number
    post:
      tags:
      - reports
      summary: Add a new report.
      security:
      - BasicAuth: []
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Report'
      responses:
        '201':
          description: Created
  /reports/{id}:
    get:
      parameters:
      - name: id
        in: path
        description: Report
        required: true
        schema:
          type: string
      tags:
      - reports
      summary: Return a report.
      responses:
        '200':
          description: A JSON object.
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    $ref: '#/components/schemas/Report'
    put:
      parameters:
      - name: id
        in: path
        description: Report
        required: true
        schema:
          type: string
      tags:
      - reports
      summary: Update a report.
      security:
      - BasicAuth: []
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Report'
      responses:
        '200':
          description: OK
    delete:
      summary: This resource deletes a specific Dataset report.
      tags:
      - reports
      parameters:
      - name: id
        in: path
        description: Report Unique ID. Identifier of a specific usage report is being deleted.  If omitted, there should be a error.
        required: true
        schema:
          type: string
      responses:
        '204':
          description: The resource was deleted successfully.
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/definitions/Error_Model'
components:
  parameters:
    pageSizeParam:
      name: page[size]
      in: query
      schema:
        type: integer
        minimum: 0
        maximum: 1000
      description: Page size between 0 and 1,000 for [pagination](https://support.datacite.org/docs/pagination).
    pageNumberParam:
      name: page[number]
      in: query
      schema:
        type: integer
      description: Page number for [pagination](https://support.datacite.org/docs/pagination).
  schemas:
    Report:
      type: object
      description: Describes the formatting needs for the COUNTER Dataset Report. Response may include the Report_Header (optional), Report_Datasets (usage stats).
      properties:
        id:
          type: string
          example: 003fadc1-daab-4d1e-97d1-96004c1ff529
        report-header:
          type: object
          required:
          - report-id
          - report-name
          - release
          - created-by
          - reporting-period
          properties:
            report-name:
              type: string
              description: The long name of the report.
              example: Dataset Report
            report-id:
              type: string
              description: The report ID or code or shortname. Typically this will be the same code provided in the Report parameter of the request.
              example: DSR
            release:
              type: string
              description: The release or version of the report.
              example: RD1
            created-by:
              type: string
              description: Name of the organization producing the report.
              example: DataONE
            created:
              type: string
              format: dateTime
              description: Time the report was prepared. Format as defined by date-time - RFC3339
              example: '2019-09-08T22:47:31Z'
            reporting-period:
              description: Time the report was prepared.
              type: object
              properties:
                end-date:
                  type: string
                  example: 2018-04-30
                begin-date:
                  type: string
                  example: 2018-04-01
            report-filters:
              description: Zero or more report filters used for this report. Typically reflect filters provided on the Request. Filters limit the data to be reported on.
              type: array
              items:
                type: string
            report-attributes:
              description: Zero or more additional attributes applied to the report. Attributes inform the level of detail in the report.
              type: array
              items:
                type: string
            exceptions:
              readOnly: true
              type: array
              items:
                type: object
                properties:
                  code:
                    type: number
                  data:
                    type: string
                  message:
                    type: string
                  help-url:
                    type: string
                  severity:
                    type: string
        report-datasets:
          description: Defines the output for the Report_Datasets being returned in a Dataset Report. Collection of datasets from the report.
          type: array
          items:
            type: object
            properties:
              uri:
                type: string
                example: https://cn.dataone.org/cn/v2/resolve/doi%3A10.5063%2FAA%2Fnceas.985.1
              yop:
                type: string
                description: Year of publication in the format of 'yyyy'. Use '0001' for unknown and '9999' for articles in press.
                example: '2010'
              platform:
                type: string
                description: Name of the platform.
                example: DataONE
              data-type:
                type: string
                description: Nature of the dataset being reported.
                example: dataset
              publisher:
                type: string
                description: Name of publisher of the dataset.
                example: DataONE
              dataset-id:
                type: array
                description: The identifier for the report dataset.
                items:
                  type: object
                  properties:
                    type:
                      type: string
                      example: doi
                    value:
                      type: string
                      example: 10.15146/R3J66V
              performance:
                type: array
                items:
                  type: object
                  properties:
                    period:
                      type: object
                      properties:
                        end-date:
                          type: string
                          example: 2018-04-30
                        begin-date:
                          type: string
                          example: 2018-04-01
                    instance:
                      type: array
                      items:
                        type: object
                        properties:
                          count:
                            type: number
                            example: 20
                          metric-type:
                            type: string
                            description: Type of activity being counted.
                            example: unique-dataset-requests
                            enum:
                            - total-dataset-requests
                            - unique-dataset-requests
                            - total-dataset-investigations
                            - unique-dataset-investigations
                          access-method:
                            type: string
                            description: Identifies if the usage activity was 'Regular' usage - a user doing research on a content site, or if the usage activity was 'Machine' - for the purpose of retrieving content for Text and Data Mining (TDM).
                            example: regular
                            enum:
                            - regular
                            - machine
              publisher-id:
                type: array
                items:
                  type: object
                  properties:
                    type:
                      type: string
                      example: ror
                    value:
                      type: string
                      example: https://ror.org/04wxnsj81
              dataset-dates:
                type: array
                items:
                  type: object
                  properties:
                    type:
                      type: string
                      example: pub-date
                      enum:
                      - pub-date
                      - first-accessed-online
                      - proprietary
                    value:
                      type: string
                      example: 2017-12-31
              dataset-title:
                type: string
                description: Name of the dataset being reported.
                example: Lake Erie Fish Community Data
              dataset-contributors:
                type: array
                description: The identifier for contributor (i.e. creator) of the dataset.
                items:
                  type: object
                  properties:
                    type:
                      type: string
                      example: name
                      enum:
                      - name
                      - orcid
                      - isni
                    value:
                      type: string
                      description: Value of the contributor identifier.
                      example: Cassandra Lopez
        report-subsets:
          type: array
          items:
            type: object
            properties:
              gzip:
                type: string
              checksum:
                type: string
      required:
      - report-datasets
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT