OpenAPI Specification
openapi: 3.0.0
info:
title: REST activities events 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: events
description: Events
paths:
/events:
get:
summary: Return a list of events.
security: []
parameters:
- in: query
name: query
description: Query for any event information.
schema:
type: string
- in: query
name: subj-id
description: The identifier for the event subject expressed as URL.
schema:
type: string
example: https://doi.org/10.14454/g8e5-6293
- in: query
name: obj-id
description: The identifier for the event object expressed as URL.
schema:
type: string
example: https://doi.org/10.14454/g8e5-6293
- in: query
name: doi
description: The subj-id or obj-id of the event expressed as DOI.
schema:
type: string
example: 10.14454/g8e5-629
- in: query
name: prefix
description: The DOI prefix of the subj-id or obj-id of the event.
schema:
type: string
example: 10.14454
- in: query
name: orcid
description: The subj-id or obj-id of the event expressed as an ORCID iD.
schema:
type: string
example: 0000-0002-4684-9769
- in: query
name: year-month
description: The year and month in which the event occurred in the format YYYY-MM.
schema:
type: string
example: 2018-08
- in: query
name: source-id
description: The [source of the event](https://support.datacite.org/docs/eventdata-guide#source-id). Use commas to include multiple sources.
schema:
type: array
items:
$ref: '#/components/schemas/source-id'
explode: false
style: form
- in: query
name: relation-type-id
description: The relation type of the event. See [Linking events](https://support.datacite.org/docs/eventdata-guide#linking-events) and [Usage events](https://support.datacite.org/docs/eventdata-guide#usage-events) documentation for definitions. Use commas to include multiple relation types.
schema:
type: array
items:
$ref: '#/components/schemas/relation-type-id'
explode: false
style: form
- in: query
name: subtype
schema:
type: string
- in: query
name: citation-type
schema:
type: string
- in: query
name: registrant-id
schema:
type: string
- in: query
name: publication-year
schema:
type: string
- in: query
$ref: '#/components/parameters/pageNumberParam'
- in: query
$ref: '#/components/parameters/pageSizeParam'
- in: query
$ref: '#/components/parameters/pageCursorParam'
- in: query
name: sort
description: Sort order. By default, all events are sorted in ascending chronological order (using the last updated timestamp).
schema:
type: string
enum:
- relevance
- obj-id
- -obj-id
- total
- -total
- created
- -created
- updated
- -updated
responses:
'200':
description: A JSON array of events.
content:
application/vnd.api+json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Event'
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
sources:
$ref: '#/components/schemas/MetaArray'
occurred:
$ref: '#/components/schemas/MetaArray'
prefixes:
$ref: '#/components/schemas/MetaArray'
citation-types:
$ref: '#/components/schemas/MetaArray'
relation-types:
$ref: '#/components/schemas/MetaArray'
registrants:
$ref: '#/components/schemas/MetaArray'
links:
allOf:
- $ref: '#/components/schemas/Links'
tags:
- events
/events/{id}:
get:
parameters:
- name: id
in: path
description: Event
required: true
schema:
type: string
tags:
- events
summary: Return an event.
security: []
responses:
'200':
description: A JSON object.
content:
application/vnd.api+json:
schema:
type: object
properties:
data:
type: object
$ref: '#/components/schemas/Event'
components:
schemas:
MetaObject:
type: object
properties:
id:
type: string
type:
type: string
count:
type: number
Links:
type: object
properties:
self:
type: string
next:
type: string
source-id:
type: string
enum:
- datacite-usage
- datacite-related
- datacite-crossref
- datacite-kisti
- datacite-op
- datacite-medra
- datacite-istic
- datacite-funder
- datacite-orcid-auto-update
- datacite-url
- crossref
MetaArray:
type: array
items:
$ref: '#/components/schemas/MetaObject'
relation-type-id:
type: string
enum:
- is-cited-by
- cites
- is-supplement-to
- is-supplemented-by
- is-continued-by
- continues
- is-described-by
- describes
- has-metadata
- is-metadata-for
- has-version
- is-version-of
- is-new-version-of
- is-previous-version-of
- is-part-of
- has-part
- is-published-in
- is-referenced-by
- references
- is-documented-by
- documents
- is-compiled-by
- compiles
- is-variant-form-of
- is-original-form-of
- is-identical-to
- is-reviewed-by
- reviews
- is-derived-from
- is-source-of
- is-required-by
- requires
- is-obsoleted-by
- obsoletes
- is-collected-by
- collects
- is-translation-of
- has-translation
- other
- is-authored-by
- is-authored-at
- is-funded-by
- total-dataset-investigations-regular
- unique-dataset-investigations-regular
- total-dataset-requests-regular
- unique-dataset-requests-regular
- total-dataset-investigations-machine
- unique-dataset-investigations-machine
- total-dataset-requests-machine
- unique-dataset-requests-machine
DataObject:
type: object
properties:
id:
type: string
type:
type: string
Event:
type: object
properties:
id:
type: string
type:
type: string
enum:
- events
attributes:
type: object
properties:
subj-id:
type: string
obj-id:
type: string
source-id:
$ref: '#/components/schemas/source-id'
relation-type-id:
$ref: '#/components/schemas/relation-type-id'
total:
type: number
message-action:
type: string
enum:
- create
- add
source-token:
type: string
license:
type: string
occured-at:
type: string
timestamp:
type: string
relationships:
type: object
properties:
subj:
type: object
properties:
data:
$ref: '#/components/schemas/DataObject'
obj:
type: object
properties:
data:
$ref: '#/components/schemas/DataObject'
required:
- id
- attributes - subj-id - source-token - source-id
parameters:
pageNumberParam:
name: page[number]
in: query
schema:
type: integer
description: Page number for [pagination](https://support.datacite.org/docs/pagination).
pageCursorParam:
name: page[cursor]
in: query
schema:
type: string
description: Use for [cursor-based pagination](https://support.datacite.org/docs/pagination#method-2-cursor).
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).
securitySchemes:
BasicAuth:
type: http
scheme: basic
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT