OpenAPI Specification
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