openapi: 3.0.0
info:
  title: Data Usage API
  description: The SASHIMI API represents a RESTful implementation of SUSHI automation
    intended to returns COUNTER Research Data Release 1 reports
  termsOfService: ''
  contact:
    name: DataCite Data Usage API
    url: https://metrics.stage.datacite.org
    email: support@datacite.org
  license:
    name: MIT
    url: https://raw.githubusercontent.com/datacite/sashimi/master/LICENSE
  version: 1.0.0
servers:
- url: https://api.datacite.org
  description: Production server
- url: https://metrics.stage.datacite.org
  description: Staging server
security:
- Bearer: []
components:
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer
      description: Token-based authentication for members
  schemas:
    Error_Model:
      type: object
      description: Generalized format for presenting errors and exceptions.
      required:
      - code
      - severity
      - message
      properties:
        code:
          type: integer
          format: int32
          description: Error number. See table of error.
          example: 3040
        severity:
          type: string
          description: Severity of the error.
          example: Warning
          enum:
          - Warning
          - Fatal
          - Debug
          - Info
        message:
          type: string
          description: Text describing the error.
          example: Partial Data Returned.
        help_url:
          type: string
          description: URL describing error details.
        cata:
          type: string
          description: Additional data provided by the server to clarify the error.
          example: Usage data has not been processed for all requested months.
    Publisher:
      type: object
      required:
      - publisher_id
      - publisher_name
      properties:
        publisher_name:
          type: string
          description: The long name of the publisher
          example: CDL
        publisher_id:
          type: string
          description: The PID of the publisher.
          example: CDLS3232323
        Path:
          type: string
          description: The path to use when requesting this report on this service.
          example: /publishers
    Status:
      type: object
      required:
      - serviceactive
      properties:
        description:
          type: string
          description: Description of the service.
          example: COUNTER Research Data Usage Reports for the UK Data Service - ReShare.
        serviceActive:
          type: boolean
          description: Indicator if the service is currently able to deliver reports.
          example: true
        registryURL:
          type: string
          description: If available, the URL separate registry with additional information
            about the service.
          example: https://www.projectcounter.org/counter-user/ebsco-database/
        note:
          type: string
          description: A general note about the service.
          example: A given customer can request a maximum of 5 requests per day for
            a given report
        alerts:
          type: array
          description: Any alerts related to service interuptions and status.
          items:
            type: object
            properties:
              date_time:
                type: string
                format: dateTime
                description: Date-time of the alert.
                example: '2016-08-02: 12:54'
              alert:
                type: string
                description: Text of the alert.
                example: Service will be unavailable Sunday midnight...
    Report:
      type: object
      description: Describes the formatting needs for the COUNTER Dataset Report.
        Response may include the Report_Header (optional), Report_Datasets (usage
        stats).
      required:
      - report_datasets
      - report_id
      - report_name
      - release
      - created_by
      - reporting_period
      properties:
        id:
          type: string
          example: 0000-0000-0000-0000
        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:
          type: string
          format: dateTime
          description: Time the report was prepared. Format as defined by date-time
            - RFC3339
          example: '2016-09-08T22:47:31Z'
        created_by:
          type: string
          description: Name of the organization producing the report.
          example: DataONE
        report_filters:
          type: string
          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.
        report_attributes:
          type: string
          description: Zero or more additional attributes applied to the report. Attributes
            inform the level of detail in the report.
        reporting_period:
          type: string
          description: Time the report was prepared.
        report_datasets:
          type: string
          description: Defines the output for the Report_Datasets being returned in
            a Dataset Report. Collection of datasets from the report.
        exceptions:
          type: array
          description: Series of exceptions encounted when preparing the report.
          items:
            $ref: '#/definitions/Error_Model'
    Report_Types:
      type: object
      required:
      - report_id
      - report_name
      properties:
        report_id:
          type: string
          description: The code, ID or short name of the report that is be used in
            the request to identify the report.
          example: DSR
        release:
          type: string
          description: The release or version number of the report.
          example: RD1
        report_description:
          type: string
          description: A short sentence describing the report.
          example: Usage by Month and Dataset
        Path:
          type: string
          description: The path to use when requesting this report on this service.
          example: /report_types/dsr
paths:
  /status:
    get:
      summary: This resource returns the current status of the reporting service supported
        by this API.
      tags:
      - status
      parameters:
      - name: platform
        in: query
        description: Name of the Platform the report data is being requested for.  This
          can be omitted if the service provides report data for only one platform.
        schema:
          type: string
      responses:
        '200':
          description: Status of the reporting service(s) supported by this API.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/definitions/Status'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/definitions/Error_Model'
  /heartbeat:
    get:
      summary: This resource returns the current status of the reporting service supported
        by this API.
      tags:
      - heartbeat
      parameters:
      - name: status
        in: query
        description: Name of the Platform the report data is being requested for.  This
          can be omitted if the service provides report data for only one platform.
        schema:
          type: string
      responses:
        '200':
          description: Status of the services provided by this API.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/definitions/Status'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/definitions/Error_Model'
  /report_types:
    get:
      summary: This resource returns a list of reports supported by the API for a
        given application.
      tags:
      - report_types
      parameters:
      - name: platform
        in: query
        description: The name of the Platform the report data is being requested for.  This
          can be omitted if the service provides report data for only one platform.
        schema:
          type: string
      responses:
        '200':
          description: List of reports supported by this service for this application.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/definitions/Report_Types'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/definitions/Error_Model'
  /reports:
    get:
      summary: This resource returns a collection of Dataset reports.
      tags:
      - reports
      parameters:
      - name: platform
        in: query
        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
      - name: report_name
        in: query
        description: The long name of the report.
        schema:
          type: string
      - name: report_id
        in: query
        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
      - name: release
        in: query
        description: The release or version of the report.
        schema:
          type: string
      - name: created
        in: query
        description: Time the report was prepared. Format as defined by date-time
          - RFC3339
        schema:
          type: string
          format: dateTime
      - name: created_by
        in: query
        description: Name of the organization producing the report.
        schema:
          type: string
      responses:
        '200':
          description: Dataset Master Report (DSR).
          content:
            application/json:
              schema:
                $ref: '#/definitions/Report'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/definitions/Error_Model'
    post:
      summary: This resource returns a collection of Dataset reports.
      tags:
      - reports
      parameters: []
      responses:
        '200':
          description: Collection of Dataset Reports
          content:
            application/json:
              schema:
                $ref: '#/definitions/Report'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/definitions/Error_Model'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/definitions/Report'
  /reports/{id}:
    get:
      summary: This resource returns a specific Dataset report.
      tags:
      - reports
      parameters:
      - name: id
        in: path
        description: Report Unique ID. Identifier of a specific usage report is being
          requested for.  If omitted, all reports on the platform with usage will
          be returned.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Usage Report Instance
          content:
            application/json:
              schema:
                $ref: '#/definitions/Report'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/definitions/Error_Model'
    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'
    put:
      summary: This resource returns an updated Dataset report.
      tags:
      - reports
      parameters:
      - name: id
        in: path
        description: Report Unique ID. Identifier of a specific usage report is being
          modified.  If omitted, there should be a error.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Report Updated.
          content:
            application/json:
              schema:
                $ref: '#/definitions/Report'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/definitions/Error_Model'
  /publishers:
    get:
      summary: This resource returns a collection of reports publishers.
      tags:
      - publishers
      parameters:
      - name: platform
        in: query
        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
      - name: report_id
        in: query
        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
      responses:
        '200':
          description: Collections of Usage Reports.
          content:
            application/json:
              schema:
                $ref: '#/definitions/Publisher'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/definitions/Error_Model'
    post:
      summary: This resource creates a new of report publisher.
      tags:
      - publishers
      parameters: []
      responses:
        '200':
          description: Publisher entity
          content:
            application/json:
              schema:
                $ref: '#/definitions/Publisher'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/definitions/Error_Model'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/definitions/Publisher'
  /publishers/{id}:
    get:
      summary: This resource returns a specific report publisher.
      tags:
      - publishers
      parameters:
      - name: id
        in: path
        description: Publisher Unique ID. Identifier of a specific report publisher.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Publisher Instance
          content:
            application/json:
              schema:
                $ref: '#/definitions/Publisher'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/definitions/Error_Model'
    delete:
      summary: This resource deletes a Publisher.
      tags:
      - publishers
      parameters:
      - name: id
        in: path
        description: Publisher Unique ID. Identifier of a specific report publisher.
        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'
    put:
      summary: This resource returns an updated Publisher Record.
      tags:
      - publishers
      parameters:
      - name: id
        in: path
        description: Publisher Unique ID. Identifier of a specific report publisher.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Report Updated.
          content:
            application/json:
              schema:
                $ref: '#/definitions/Publisher'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/definitions/Error_Model'