openapi.yaml

swagger: '2.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"
schemes:
  - https
securityDefinitions:
  Bearer:
    type: apiKey
    description: >-
      Unique code assigned by Content Provider to grant you access to this API. This apikey needs to be in the header.
    name: Authorization
    in: header
security:
  - Bearer: []
paths:
  /status:
    get:
      tags:
        - status
      description: >-
        This resource returns the current status of the reporting service supported by this API.
      produces:
        - application/json
      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.
          type: string
      responses:
        '200':
          description: Status of the reporting service(s) supported by this API.
          schema:
            type: array
            items:
              $ref: '#/definitions/Status'
        default:
          description: unexpected error
          schema:
            $ref: '#/definitions/Error_Model'
  /heartbeat:
    get:
      tags:
        - heartbeat
      description: >-
        This resource returns the current status of the reporting service supported by this API.
      produces:
        - text/plain
      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.
          type: string
      responses:
        '200':
          description: Status of the services provided by this API.
          schema:
            type: array
            items:
              $ref: '#/definitions/Status'
        default:
          description: unexpected error
          schema:
            $ref: '#/definitions/Error_Model'
  /report_types:
    get:
      tags:
        - report_types
      description: >-
        This resource returns a list of reports supported by the API for a given application.
      produces:
        - application/json
      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.
          type: string
      responses:
        '200':
          description: List of reports supported by this service for this application.
          schema:
            type: array
            items:
              $ref: '#/definitions/Report_Types'
        default:
          description: unexpected error
          schema:
            $ref: '#/definitions/Error_Model'
  /reports:
    get:
      tags:
        - reports
      description: 'This resource returns a collection of Dataset reports.'
      consumes:
      - application/json
      produces:
      - application/json
      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.
          type: string
        - name: report_name
          in: query
          type: string
          description: The long name of the report.
        - name: report_id
          type: string
          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.
        - name: release
          type: string
          in: query
          description: The release or version of the report.
        - name: created
          type: string
          in: query
          format: dateTime
          description: Time the report was prepared. Format as defined by date-time - RFC3339
        - name: created_by
          type: string
          in: query
          description: Name of the organization producing the report.
      responses:
        '200':
          description: 'Dataset Master Report (DSR).'
          schema:
            $ref: '#/definitions/Report'
        default:
          description: unexpected error
          schema:
            $ref: '#/definitions/Error_Model'
    post:
      tags:
        - reports
      description: 'This resource returns a collection of Dataset reports.'
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: report
          in: body
          description: >-
            Report of metrics proccesed in SUSHI format.
          schema:
            $ref: "#/definitions/Report"
      responses:
        '200':
          description: 'Collection of Dataset Reports'
          schema:
            $ref: '#/definitions/Report'
        default:
          description: unexpected error
          schema:
            $ref: '#/definitions/Error_Model'
  /reports/{id}:
    get:
      tags:
        - reports
      description: 'This resource returns a specific Dataset report.'
      consumes:
        - application/json
      produces:
        - application/json
      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
          type: string
      responses:
        '200':
          description: 'Usage Report Instance'
          schema:
            $ref: '#/definitions/Report'
        default:
          description: unexpected error
          schema:
            $ref: '#/definitions/Error_Model'
    delete:
      tags:
        - reports
      description: 'This resource deletes a specific Dataset report.'
      consumes:
        - application/json
      produces:
        - application/json
      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
          type: string
      responses:
        '204':
          description: The resource was deleted successfully.
        default:
          description: unexpected error
          schema:
            $ref: '#/definitions/Error_Model'
    put:
      tags:
        - reports
      description: 'This resource returns an updated Dataset report.'
      consumes:
        - application/json
      produces:
        - application/json
      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
          type: string
      responses:
        '200':
          description: 'Report Updated.'
          schema:
            $ref: '#/definitions/Report'
        default:
          description: unexpected error
          schema:
            $ref: '#/definitions/Error_Model'
  /publishers:
    get:
      tags:
        - publishers
      description: 'This resource returns a collection of reports publishers.'
      consumes:
      - application/json
      produces:
      - application/json
      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.
          type: string
        - name: report_id
          type: string
          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.
      responses:
        '200':
          description: 'Collections of Usage Reports.'
          schema:
            $ref: '#/definitions/Publisher'
        default:
          description: unexpected error
          schema:
            $ref: '#/definitions/Error_Model'
    post:
      tags:
        - publishers
      description: 'This resource creates a new of report publisher.'
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: publisher_id
          in: body
          description: >-
            The ID of  the organisation Content providers implementing the Code of Practice for Research Data.
          schema:
            $ref: '#/definitions/Publisher'
      responses:
        '200':
          description: 'Publisher entity'
          schema:
            $ref: '#/definitions/Publisher'
        default:
          description: unexpected error
          schema:
            $ref: '#/definitions/Error_Model'
  /publishers/{id}:
    get:
      tags:
        - publishers
      description: 'This resource returns a specific report publisher.'
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: id
          in: path
          description: >-
            Publisher Unique ID. Identifier of a specific report publisher.
          required: true
          type: string
      responses:
        '200':
          description: 'Publisher Instance'
          schema:
            $ref: '#/definitions/Publisher'
        default:
          description: unexpected error
          schema:
            $ref: '#/definitions/Error_Model'
    delete:
      tags:
        - publishers
      description: 'This resource deletes a Publisher.'
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: id
          in: path
          description: >-
            Publisher Unique ID. Identifier of a specific report publisher.
          required: true
          type: string
      responses:
        '204':
          description: The resource was deleted successfully.
        default:
          description: unexpected error
          schema:
            $ref: '#/definitions/Error_Model'
    put:
      tags:
        - publishers
      description: 'This resource returns an updated Publisher Record.'
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: id
          in: path
          description: >-
            Publisher Unique ID. Identifier of a specific report publisher.
          required: true
          type: string
      responses:
        '200':
          description: 'Report Updated.'
          schema:
            $ref: '#/definitions/Publisher'
        default:
          description: unexpected error
          schema:
            $ref: '#/definitions/Error_Model'
definitions:
  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
host: metrics.stage.datacite.org