eusage-reports-1.0.yaml

openapi: 3.0.0
info:
  title: EUsage Reports
  version: v1
paths:
  /eusage-reports/report-titles:
    parameters:
      - $ref: headers/okapi-tenant.yaml
      - $ref: headers/okapi-token.yaml
      - $ref: headers/okapi-url.yaml
      - $ref: parameters/facets.yaml
      - $ref: parameters/limit.yaml
      - $ref: parameters/query.yaml
      - $ref: parameters/offset.yaml
      - in: query
        name: counterReportId
        required: false
        description: limit titles associated with counter report (UUID)
        schema:
          type: string
      - in: query
        name: providerId
        required: false
        description: limit titles associated with usage provider (UUID)
        schema:
          type: string
    get:
      description: Get titles with links to KB. The response contains facets response with facet type "status"
        and counts for values "matched", "ignored", "unmatched. The resulting set can be limited by parameter
        query (CQL) as well as counterReportId and providerId (these are NOT part of CQL). The CQL query itself
        supports fields "cql.allRecords", "id", "counterReportTitle", "ISBN", "printISSN", "onlineISSN",
        "kbTitleId" and "kbManualMatch".
      operationId: getReportTitles
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: schemas/reportTitles.json
        "400":
          $ref: "#/components/responses/trait_400"
        "500":
          $ref: "#/components/responses/trait_500"
    post:
      description: POST titles with links to KB
      operationId: postReportTitles
      requestBody:
        content:
          application/json:
            schema:
              $ref: schemas/reportTitles.json
      responses:
        "204":
          description: OK
        "400":
          $ref: "#/components/responses/trait_400"
        "500":
          $ref: "#/components/responses/trait_500"
  /eusage-reports/report-packages:
    parameters:
      - $ref: headers/okapi-tenant.yaml
      - $ref: headers/okapi-token.yaml
      - $ref: headers/okapi-url.yaml
      - $ref: parameters/offset.yaml
      - $ref: parameters/limit.yaml
      - $ref: parameters/query.yaml
    get:
      description: Get KB title - package relationship.
      operationId: getReportPackages
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: schemas/reportPackages.json
        "400":
          $ref: "#/components/responses/trait_400"
        "500":
          $ref: "#/components/responses/trait_500"
  /eusage-reports/report-titles/from-counter:
    parameters:
      - $ref: headers/okapi-tenant.yaml
      - $ref: headers/okapi-token.yaml
      - $ref: headers/okapi-url.yaml
    post:
      description: Parse counter reports
      operationId: postFromCounter
      requestBody:
        content:
          application/json:
            schema:
              $ref: schemas/fromCounterRequest.json
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: schemas/fromCounterResponse.json
        "400":
          $ref: "#/components/responses/trait_400"
        "404":
          $ref: "#/components/responses/trait_404"
        "500":
          $ref: "#/components/responses/trait_500"
  /eusage-reports/title-data:
    parameters:
      - $ref: headers/okapi-tenant.yaml
      - $ref: headers/okapi-token.yaml
      - $ref: headers/okapi-url.yaml
      - $ref: parameters/offset.yaml
      - $ref: parameters/limit.yaml
      - $ref: parameters/query.yaml
    get:
      description: Get counter report title data.
      operationId: getTitleData
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: schemas/titleDataEntries.json
        "400":
          $ref: "#/components/responses/trait_400"
        "500":
          $ref: "#/components/responses/trait_500"
  /eusage-reports/report-data:
    parameters:
      - $ref: headers/okapi-tenant.yaml
      - $ref: headers/okapi-token.yaml
      - $ref: headers/okapi-url.yaml
      - $ref: parameters/offset.yaml
      - $ref: parameters/limit.yaml
      - $ref: parameters/query.yaml
    get:
      description: This returns data for parsed agreements.
      operationId: getReportData
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: schemas/reportDataEntries.json
        "400":
          $ref: "#/components/responses/trait_400"
        "500":
          $ref: "#/components/responses/trait_500"
  /eusage-reports/report-data/from-agreement:
    parameters:
      - $ref: headers/okapi-tenant.yaml
      - $ref: headers/okapi-token.yaml
      - $ref: headers/okapi-url.yaml
    post:
      description: Parse agreements and populate report data
      operationId: postFromAgreement
      requestBody:
        content:
          application/json:
            schema:
              $ref: schemas/fromAgreementRequest.json
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: schemas/fromAgreementResponse.json
        "400":
          $ref: "#/components/responses/trait_400"
        "404":
          $ref: "#/components/responses/trait_404"
        "500":
          $ref: "#/components/responses/trait_500"
  /eusage-reports/stored-reports/use-over-time:
    parameters:
      - $ref: headers/okapi-tenant.yaml
      - $ref: headers/okapi-token.yaml
      - $ref: headers/okapi-url.yaml
      - $ref: parameters/access-count-period.yaml
      - $ref: parameters/agreement-id.yaml
      - $ref: parameters/csv.yaml
      - $ref: parameters/start-date.yaml
      - $ref: parameters/end-date.yaml
      - $ref: parameters/format.yaml
      - $ref: parameters/include-oa.yaml
      - $ref: parameters/full.yaml
    get:
      description: Return usage data over time, where usageDateRange falls within startDate, endDate
      operationId: getUseOverTime
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: schemas/report.json
              example:
                $ref: examples/report.json
        "400":
          $ref: "#/components/responses/trait_400"
        "404":
          $ref: "#/components/responses/trait_404"
        "500":
          $ref: "#/components/responses/trait_500"
  /eusage-reports/stored-reports/reqs-by-date-of-use:
    parameters:
      - $ref: headers/okapi-tenant.yaml
      - $ref: headers/okapi-token.yaml
      - $ref: headers/okapi-url.yaml
      - $ref: parameters/access-count-period.yaml
      - $ref: parameters/agreement-id.yaml
      - $ref: parameters/csv.yaml
      - $ref: parameters/start-date.yaml
      - $ref: parameters/end-date.yaml
      - $ref: parameters/format.yaml
      - $ref: parameters/include-oa.yaml
      - $ref: parameters/yop-interval.yaml
      - $ref: parameters/full.yaml
    get:
      description: Return requests by date of use; this is like use over time but additionally groups by publication year.
      operationId: getReqsByDateOfUse
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: schemas/report.json
        "400":
          $ref: "#/components/responses/trait_400"
        "404":
          $ref: "#/components/responses/trait_404"
        "500":
          $ref: "#/components/responses/trait_500"
  /eusage-reports/stored-reports/reqs-by-pub-year:
    parameters:
      - $ref: headers/okapi-tenant.yaml
      - $ref: headers/okapi-token.yaml
      - $ref: headers/okapi-url.yaml
      - $ref: parameters/access-count-period.yaml
      - $ref: parameters/agreement-id.yaml
      - $ref: parameters/csv.yaml
      - $ref: parameters/start-date.yaml
      - $ref: parameters/end-date.yaml
      - $ref: parameters/format.yaml
      - $ref: parameters/include-oa.yaml
      - $ref: parameters/period-of-use.yaml
      - $ref: parameters/full.yaml
    get:
      description: Return requests by publication year where usageDateRange falls within startDate, endDate.
        Grouping controlled by periodOfUse.
        "accessCountPeriods" array lists the publication years to be used as column labels for numbers in the
        "totalItemRequestsByPeriod", "uniqueItemRequestsByPeriod" and "accessCountsByPeriod" arrays.
      operationId: getReqsByPubYear
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: schemas/report.json
        "400":
          $ref: "#/components/responses/trait_400"
        "404":
          $ref: "#/components/responses/trait_404"
        "500":
          $ref: "#/components/responses/trait_500"
  /eusage-reports/stored-reports/cost-per-use:
    parameters:
      - $ref: headers/okapi-tenant.yaml
      - $ref: headers/okapi-token.yaml
      - $ref: headers/okapi-url.yaml
      - $ref: parameters/access-count-period.yaml
      - $ref: parameters/agreement-id.yaml
      - $ref: parameters/csv.yaml
      - $ref: parameters/start-date.yaml
      - $ref: parameters/end-date.yaml
      - $ref: parameters/format.yaml
      - $ref: parameters/include-oa.yaml
      - $ref: parameters/full.yaml
    get:
      description: Return cost per where usageDateRange falls within startDate, endDate.
        The report is structured in periods, typically months, and the cost-per-use in a period is
        invoiced amount divided by download count (unique or total) and further divided in number of
        periods where any title has downloads. This way the cost for download is divided into periods
        (with non-zero use) and then evenly divided across titles within those periods.
        Consider agreement that has two titles, titleA and titleB where titleA has
        downloads in May and June. titleB has downloads in June only. In May, the title count is 1.
        In June, the title count is 2. The total periods where any title occurs is p = 2+1 = 3.
        Cost per download for titleA in May is (paidAmount/p) / downloads(TitleA,May) and in
        June (paidAmount/p) / downloads(TitleA,June).
        Cost per download for titleB in June is paidAmount/p / downloads(TitleB,June).
      operationId: getCostPerUse
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: schemas/reportCost.json
        "400":
          $ref: "#/components/responses/trait_400"
        "404":
          $ref: "#/components/responses/trait_404"
        "500":
          $ref: "#/components/responses/trait_500"
  /eusage-reports/report-data/status/{id}:
    parameters:
      - $ref: headers/okapi-tenant.yaml
      - $ref: headers/okapi-token.yaml
      - $ref: headers/okapi-url.yaml
      - in: path
        name: id
        required: true
        description: agreement identifier
        schema:
          type: string
          format: uuid
    get:
      description: Return status of operation associated with identifier.
      operationId: getReportStatus
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: schemas/reportStatus.json
        "400":
          $ref: "#/components/responses/trait_400"
        "404":
          $ref: "#/components/responses/trait_404"
        "500":
          $ref: "#/components/responses/trait_500"
components:
  responses:
    trait_400:
      description: Bad request
      content:
        text/plain:
          schema:
            type: string
            example: Invalid JSON in request
        application/json:
          schema:
            type: object
            example: {"error":"Invalid JSON in request"}
    trait_404:
      description: Not Found
      content:
        text/plain:
          schema:
            type: string
            example: Identifier 596d9f60-cda3-44d2-a4a1-2f48b7d4d23c not found
        application/json:
          schema:
            type: object
            example: {"error":"Identifier 596d9f60-cda3-44d2-a4a1-2f48b7d4d23c not found"}
    trait_500:
      description: Internal error
      content:
        text/plain:
          schema:
            type: string
            example: Internal server error, contact administrator
  schemas:
    errors:
      $ref: schemas/errors.json