aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorBryan Newbold <bnewbold@robocracy.org>2019-09-12 15:56:44 -0700
committerBryan Newbold <bnewbold@robocracy.org>2019-09-12 15:56:44 -0700
commit0a813aa838c5116ce3406e5862d2eaf2104398c6 (patch)
tree6a81a108b67aaa6c2c911e25a46e03458c22fd6e
parenta922a382bb681dc4d2fe7d2b359a0c48c2e98cbc (diff)
downloadfatcat-0a813aa838c5116ce3406e5862d2eaf2104398c6.tar.gz
fatcat-0a813aa838c5116ce3406e5862d2eaf2104398c6.zip
massively expand docs in openapi spec
-rw-r--r--fatcat-openapi2.yml1015
1 files changed, 937 insertions, 78 deletions
diff --git a/fatcat-openapi2.yml b/fatcat-openapi2.yml
index 95ef4c6b..ab4f0536 100644
--- a/fatcat-openapi2.yml
+++ b/fatcat-openapi2.yml
@@ -2,9 +2,85 @@
swagger: "2.0"
info:
title: fatcat
- description: A scalable, versioned, API-oriented catalog of bibliographic entities
- and file metadata
+
+ description: |
+
+ ## Introduction
+
+ Fatcat is a scalable, versioned, API-oriented catalog of bibliographic
+ entities and file metadata.
+
+ These API reference documents, along with client software libraries, are
+ generated automatically from an OpenAPI 2.0 ("Swagger") definition file.
+
+ A higher-level introduction to the API, as well as a description of the
+ fatcat data model, are available in ["The Fatcat Guide"](https://guide.fatcat.wiki/).
+ The guide also includes a [Cookbook](https://guide.fatcat.wiki/cookbook.html)
+ section demonstrating end-to-end tasks like creating entities as part of
+ editgroups, or safely merging duplicate entities.
+
+ ### Expectations and Best Practices
+
+ A test/staging QA API instance of fatcat is available at
+ <https://api.qa.fatcat.wiki/v0>. The database backing this instance is
+ separate from the production interface, and is periodically rebuilt from
+ snapshots of the full production database, meaning that edits on the QA
+ server will *NOT* persist, and that semantics like the changelog index
+ monotonically increasing *MAY* be broken. Developers are expexcted to test
+ their scripts and tools against the QA instance before running against
+ production.
+
+ Fatcat is made available as a gratis (no cost) and libre (freedom
+ preserving) service to the public, with limited funding and resources. We
+ welcome new and unforseen uses and contributions, but may need to impose
+ restrictions (like rate-limits) to keep the service functional for other
+ users, and in extreme cases reserve the option to block accounts and IP
+ ranges if necessary to keep the service operational.
+
+ The Internet Archive owns and operates it's own server equipment and data
+ centers, and operations are optimized for low-cost, not high-availability.
+ Users and partners should expect some downtime on the fatcat API, on the
+ order of hours a month.
+
+ Periodic metadata exports are available for batch processing, and database
+ snapshots can be used to create locally-hosted mirrors of the service for
+ more intensive and reliable querying.
+
+ ### Other Nitty Gritties
+
+ Cross-origin requests are allowed for the API service, to enable third
+ parties to bulid in-browser applications.
+
+ A metadata search service is available at <https://search.fatcat.wiki> (and
+ <https://search.qa.fatcat.wiki>). The API is currently the raw
+ elasticsearch API, with only GET (read) requests allowed. This public
+ service is experimental and may be removed or limited in the future.
+
+ ## Authentication
+
+ The API allows basic read-only "GET" HTTP requests with no authentication.
+ Proposing changes to the metadata, or other mutating requests ("PUT",
+ "POST", "DELETE") all require authentication, and some operations require
+ additional account permissions.
+
+ End-user account creation and login happens through the web interface. From
+ a logged-in editor profile page, you can generate a API token. Tokens are
+ "macaroons", similar to JWT tokens, and are used for all API
+ authentication. The web interface includes macaroons in browser cookies and
+ passes them through to the API to authenticate editor actions.
+
+ <!-- ReDoc-Inject: <security-definitions> -->
+
version: 0.3.0
+ termsOfService: "https://guide.fatcat.wiki/policies.html"
+ contact:
+ name: "Internet Archive Web Group"
+ email: "webgroup@archive.org"
+ url: "https://fatcat.wiki"
+ x-logo:
+ url: "https://fatcat.wiki/static/paper_man_confused.gif"
+ altText: "Confused Papers Man (Logo)"
+ backgroundColor: "#FFFFFF"
schemes: [https]
basePath: /v0
host: api.fatcat.wiki
@@ -13,29 +89,168 @@ consumes:
produces:
- application/json
+x-servers:
+- url: https://api.fatcat.wiki/v0
+ description: "Production Server"
+- url: https://api.qa.fatcat.wiki/v0
+ description: "QA Server"
+
securityDefinitions:
Bearer:
type: apiKey
name: Authorization
in: header
+ description: |
+ The only current API authentication mechanism is HTTP bearer
+ authentication using the `Authorization` HTTP header. The header should
+ be formatted as the string "Bearer", then a space, then API token (in the
+ usual base64 string encoding).
+
+ An example HTTP request would look on the wire like:
+
+ GET /v0/auth/check HTTP/1.1
+ Accept: */*
+ Accept-Encoding: gzip, deflate
+ Authorization: Bearer AgEPZGV2LmZhdGNhdC53aWtpAhYyMDE5MDEwMS1kZXYtZHVtbXkta2V5AAImZWRpdG9yX2lkID0gYWFhYWFhYWFhYWFhYmt2a2FhYWFhYWFhYWkAAht0aW1lID4gMjAxOS0wMS0wOVQwMDo1Nzo1MloAAAYgnroNha1hSftChtxHGTnLEmM/pY8MeQS/jBSV0UNvXug=
+ Connection: keep-alive
+ Host: api.qa.fatcat.wiki
+ User-Agent: HTTPie/0.9.8
+
+ Headers can be passed on the command line using `http` (HTTPie) like:
+
+ http get https://api.qa.fatcat.wiki/v0/auth/check Authorization:"Bearer AgEPZGV2LmZhdGNhdC53aWtpAhYyMDE5MDEwMS1kZXYtZHVtbXkta2V5AAImZWRpdG9yX2lkID0gYWFhYWFhYWFhYWFhYmt2a2FhYWFhYWFhYWkAAht0aW1lID4gMjAxOS0wMS0wOVQwMDo1Nzo1MloAAAYgnroNha1hSftChtxHGTnLEmM/pY8MeQS/jBSV0UNvXug="
+
+ Or with `curl`:
+
+ curl -H "Authorization: Bearer AgEPZGV2LmZhdGNhdC53aWtpAhYyMDE5MDEwMS1kZXYtZHVtbXkta2V5AAImZWRpdG9yX2lkID0gYWFhYWFhYWFhYWFhYmt2a2FhYWFhYWFhYWkAAht0aW1lID4gMjAxOS0wMS0wOVQwMDo1Nzo1MloAAAYgnroNha1hSftChtxHGTnLEmM/pY8MeQS/jBSV0UNvXug=" https://qa.fatcat.wiki/v0/auth/check
tags: # TAGLINE
- name: containers # TAGLINE
- descriptions: "Container entities: such as journals, conferences, book series" # TAGLINE
+ x-displayName: "Containers" # TAGLINE
+ description: |
+ **Container** entities represent publication venues like journals,
+ conference proceedings, book series, or blogs. They group publications
+ ("releases").
+
+ See the "Catalog Style Guide" section of the guide for details and
+ semantics of what should be included in specific entity fields.
+ Specifically, the
+ [Container Entity Reference](https://guide.fatcat.wiki/entity_container.html).
- name: creators # TAGLINE
- descriptions: "Creator entities: such as authors" # TAGLINE
+ x-displayName: "Creators" # TAGLINE
+ description: |
+ **Creator** entities represent individuals (or organizations, or other
+ agents) who contribute to the creation of specific releases
+ (publications).
+
+ See the "Catalog Style Guide" section of the guide for details and
+ semantics of what should be included in specific entity fields.
+ Specifically, the
+ [Creator Entity Reference](https://guide.fatcat.wiki/entity_creator.html).
- name: files # TAGLINE
- descriptions: "File entities" # TAGLINE
+ x-displayName: "Files" # TAGLINE
+ description: |
+ **File** entities represent unique digital files which are full
+ manifestations of specific releases (publications), such as fulltext PDF
+ files, JATS XML documents, or video files. File entities also include a
+ set of locations where they can be found on the public web.
+
+ See the "Catalog Style Guide" section of the guide for details and
+ semantics of what should be included in specific entity fields.
+ Specifically, the
+ [File Entity Reference](https://guide.fatcat.wiki/entity_file.html).
- name: filesets # TAGLINE
- descriptions: "Fileset entities" # TAGLINE
+ x-displayName: "Filesets" # TAGLINE
+ description: |
+ **Fileset** entities represent sets of digital files, as well as locations
+ where they can be found on the public web. Filesets most commonly
+ represent datasets consisting of serveral data and metadata files.
+
+ See the "Catalog Style Guide" section of the guide for details and
+ semantics of what should be included in specific entity fields.
+ Specifically, the
+ [Fileset Entity Reference](https://guide.fatcat.wiki/entity_fileset.html).
- name: webcaptures # TAGLINE
- descriptions: "Webcapture entities" # TAGLINE
+ x-displayName: "Webcaptures" # TAGLINE
+ description: |
+ **Web Capture** entities represent archival snapshots of web pages (or
+ other web resources), which are usually complete manifestations of a
+ specific release entity. Web Captures also include a set of locations
+ (wayback replay instances or WARC files) where the capture can be found.
+
+ See the "Catalog Style Guide" section of the guide for details and
+ semantics of what should be included in specific entity fields.
+ Specifically, the
+ [Web Capture Entity Reference](https://guide.fatcat.wiki/entity_webcapture.html).
- name: releases # TAGLINE
- descriptions: "Release entities: individual articles, pre-prints, books" # TAGLINE
+ x-displayName: "Releases" # TAGLINE
+ description: |
+ **Release** entities represent specific published versions of a research
+ work, such as a pre-print, a journal article, a book (or chapter), or a
+ scholarly blog post. Releases are always grouped together under Works;
+ they may be published in a specific Container; they may have known
+ Creators; and there may exist known File/Fileset/WebCapture digital copies
+ of the release.
+
+ See the "Catalog Style Guide" section of the guide for details and
+ semantics of what should be included in specific entity fields.
+ Specifically, the
+ [Release Entity Reference](https://guide.fatcat.wiki/entity_release.html).
- name: works # TAGLINE
- descriptions: "Work entities: grouping releases which are variants of the same work" # TAGLINE
- - name: edit-lifecycle # TAGLINE
- descriptions: "Endpoints relating to global edit submission and history" # TAGLINE
+ x-displayName: "Works" # TAGLINE
+ description: |
+ **Work** entities group several Release entities which are different
+ versions of the same abstract piece of research. For example, three
+ release entities representing the pre-print, published article, and
+ retraction stages of the same journal paper would be grouped under a
+ single work.
+
+ See the "Catalog Style Guide" section of the guide for details and
+ semantics of what should be included in specific entity fields.
+ Specifically, the
+ [Work Entity Reference](https://guide.fatcat.wiki/entity_work.html).
+ - name: editgroups # TAGLINE
+ x-displayName: "Editgroups" # TAGLINE
+ description: |
+ **Editgroups** are sets of changes, each to individual entities in the
+ catalog. Every edit must be part of an editgroup which is reviewed and
+ accepted (merged) as a whole.
+ - name: editors # TAGLINE
+ x-displayName: "Editors" # TAGLINE
+ description: |
+ **Editors** are human user accounts and bots that make changes to the
+ Fatcat catalog.
+
+ The API allows fetching (and updating) metadata about individual editors,
+ as well as fetching editor's annotation and edit history.
+ - name: changelog # TAGLINE
+ x-displayName: "Changelog" # TAGLINE
+ description: |
+ The **Changelog** is the ordered feed of editgroups which have been
+ accepted into the catalog.
+ - name: auth # TAGLINE
+ x-displayName: "Auth Methods" # TAGLINE
+ description: |
+ Helper methods and internal APIs for editor authentication.
+
+x-tagGroups:
+ - name: Entities
+ tags:
+ - containers
+ - creators
+ - files
+ - filesets
+ - webcaptures
+ - releases
+ - works
+ - name: Editing
+ tags:
+ - editors
+ - editgroups
+ - changelog
+ - name: Other
+ tags:
+ - auth
# don't want these to be rust types (at least for now)
x-fatcat-ident: &FATCATIDENT
@@ -64,30 +279,35 @@ x-orcid: &FATCATORCID
pattern: "\\d{4}-\\d{4}-\\d{4}-\\d{3}[\\dX]"
minLength: 19
maxLength: 19
+ description: "ORCiD (https://orcid.org) identifier"
x-md5: &FATCATMD5
type: string
example: "1b39813549077b2347c0f370c3864b40"
pattern: "[a-f0-9]{32}"
minLength: 32
maxLength: 32
+ description: "MD5 hash of data, in hex encoding"
x-sha1: &FATCATSHA1
type: string
example: "e9dd75237c94b209dc3ccd52722de6931a310ba3"
pattern: "[a-f0-9]{40}"
minLength: 40
maxLength: 40
+ description: "SHA-1 hash of data, in hex encoding"
x-sha256: &FATCATSHA256
type: string
example: "cb1c378f464d5935ddaa8de28446d82638396c61f042295d7fb85e3cccc9e452"
pattern: "[a-f0-9]{64}"
minLength: 64
maxLength: 64
+ description: "SHA-256 hash of data, in hex encoding"
# Common properties across entities
x-entity-props: &ENTITYPROPS
state:
type: string
enum: ["wip", "active", "redirect", "deleted"]
+ example: "active"
ident:
<<: *FATCATIDENT
revision:
@@ -96,9 +316,15 @@ x-entity-props: &ENTITYPROPS
<<: *FATCATIDENT
extra:
type: object
+ description: |
+ Free-form JSON metadata that will be stored with the other entity
+ metadata. See guide for (unenforced) schema conventions.
additionalProperties: {}
edit_extra:
type: object
+ description: |
+ Free-form JSON metadata that will be stored with specific entity edits
+ (eg, creation/update/delete).
additionalProperties: {}
definitions:
@@ -111,8 +337,10 @@ definitions:
properties:
success:
type: boolean
+ example: false
error:
type: string
+ example: "unexpected-thing"
message:
type: string
example: "A really confusing, totally unexpected thing happened"
@@ -124,6 +352,7 @@ definitions:
properties:
success:
type: boolean
+ example: true
message:
type: string
example: "The computers did the thing successfully!"
@@ -134,18 +363,24 @@ definitions:
<<: *ENTITYPROPS
name:
type: string
+ description: "Name of the container (eg, Journal title). Required for entity creation."
example: "Journal of Important Results"
- description: "Required for valid entities"
container_type:
type: string
- description: "Eg, 'journal'"
+ description: "Type of container, eg 'journal' or 'proceedings'. See Guide for list of valid types."
+ example: "journal"
publisher:
type: string
+ description: |
+ Name of the organization or entity responsible for publication. Not
+ the complete imprint/brand.
example: "Society of Curious Students"
issnl:
+ description: "Linking ISSN number (ISSN-L). Should be valid and registered with issn.org"
<<: *FATCATISSN
wikidata_qid:
type: string
+ example: "Q42812"
creator_entity:
type: object
# required for creation: display_name
@@ -154,15 +389,25 @@ definitions:
display_name:
type: string
example: "Grace Hopper"
- description: "Required for valid entities"
+ description: |
+ Name as should be displayed in web interface or in author lists (not
+ index/sorted). Required for valid entities.
given_name:
type: string
+ description: |
+ In English commonly the first name, but ordering is context and
+ culture specific.
surname:
type: string
+ description: |
+ In English commonly the last, or family name, but ordering is context
+ and culture specific.
orcid:
<<: *FATCATORCID
wikidata_qid:
type: string
+ example: "Q42812"
+ description: "Wikidata entity QID"
file_entity:
type: object
properties:
@@ -171,6 +416,7 @@ definitions:
type: integer
example: 1048576
format: int64
+ description: "Size of file in bytes. Non-zero."
md5:
<<: *FATCATMD5
sha1:
@@ -188,8 +434,15 @@ definitions:
type: array
items:
<<: *FATCATIDENT
+ description: |
+ Set of identifier of release entities this file represents a full
+ manifestation of. Usually a single release, but some files contain
+ content of multiple full releases (eg, an issue of a journal).
releases:
- description: "Optional; GET-only"
+ description: |
+ Full release entities, included in GET responses when `releases`
+ included in `expand` parameter. Ignored if included in PUT or POST
+ requests.
type: array
items:
$ref: "#/definitions/release_entity"
@@ -203,9 +456,15 @@ definitions:
type: string
format: url
example: "https://example.edu/~frau/prcding.pdf"
+ description: |
+ URL/URI pointing directly to a machine retrievable copy of this exact
+ file.
rel:
type: string
- example: "webarchive"
+ example: "web"
+ description: |
+ Indicates type of host this URL points to. Eg, "publisher",
+ "repository", "webarchive". See guide for list of acceptable values.
fileset_entity:
type: object
properties:
@@ -223,11 +482,17 @@ definitions:
type: array
items:
<<: *FATCATIDENT
+ description: |
+ Set of identifier of release entities this fileset represents a full
+ manifestation of. Usually a single release.
releases:
- description: "Optional; GET-only"
type: array
items:
$ref: "#/definitions/release_entity"
+ description: |
+ Full release entities, included in GET responses when `releases`
+ included in `expand` parameter. Ignored if included in PUT or POST
+ requests.
fileset_url:
type: object
required:
@@ -241,6 +506,9 @@ definitions:
rel:
type: string
example: "webarchive"
+ description: |
+ Indicates type of host this URL points to. See guide for list of
+ acceptable values.
fileset_file:
type: object
required:
@@ -250,10 +518,13 @@ definitions:
path:
type: string
example: "img/cat.png"
+ description: |
+ Path name of file within this fileset (eg, directory)
size:
type: integer
example: 1048576
format: int64
+ description: "File size in bytes"
md5:
<<: *FATCATMD5
sha1:
@@ -263,6 +534,10 @@ definitions:
extra:
type: object
additionalProperties: {}
+ description: |
+ Free-form additional metadata about this specific file in the set.
+ Eg, `mimetype`. See guide for nomative (but unenforced) schema
+ fields.
webcapture_entity:
type: object
properties:
@@ -280,19 +555,29 @@ definitions:
type: string
format: url
example: "http://asheesh.org"
+ description: "Base URL of the primary resource this is a capture of"
timestamp:
type: string
format: date-time
- description: "same format as CDX line timestamp (UTC, etc). Corresponds to the overall capture timestamp. Can be the earliest or average of CDX timestamps if that makes sense."
+ description: |
+ Same format as CDX line timestamp (UTC, etc). Corresponds to the
+ overall capture timestamp. Should generally be the timestamp of
+ capture of the primary resource URL.
release_ids:
type: array
items:
<<: *FATCATIDENT
+ description: |
+ Set of identifier of release entities this fileset represents a full
+ manifestation of. Usually a single release.
releases:
- description: "Optional; GET-only"
type: array
items:
$ref: "#/definitions/release_entity"
+ description: |
+ Full release entities, included in GET responses when `releases`
+ included in `expand` parameter. Ignored if included in PUT or POST
+ requests.
webcapture_cdx_line:
type: object
required:
@@ -304,26 +589,40 @@ definitions:
surt:
type: string
example: "org,asheesh)/apus/ch1/node15.html"
+ description: |
+ "Sortable URL" format. See guide for details.
timestamp:
type: string
format: date-time
example: "2016-09-19T17:20:24Z"
- description: "UTC, 'Z'-terminated, second (or better) precision"
+ description: |
+ Date and time of capture, in ISO format. UTC, 'Z'-terminated, second
+ (or better) precision.
url:
type: string
# NOTE: not format:url to allow alternatives
example: "http://www.asheesh.org:80/APUS/ch1/node15.html"
+ description: |
+ Full URL/URI of resource captured.
mimetype:
type: string
example: "text/html"
+ description: |
+ Mimetype of the resource at this URL. May be the Content-Type header,
+ or the actually sniffed file type.
status_code:
type: integer
example: 200
format: int64
+ description: |
+ HTTP status code. Should generally be 200, especially for the primary
+ resource, but may be 3xx (redirect) or even error codes if embedded
+ resources can not be fetched successfully.
size:
type: integer
example: 1048576
format: int64
+ description: "Resource (file) size in bytes"
sha1:
<<: *FATCATSHA1
sha256:
@@ -338,9 +637,15 @@ definitions:
type: string
format: url
example: "https://web.archive.org/web/"
+ description: |
+ URL/URI pointing to archive of this web resource.
rel:
type: string
example: "wayback"
+ description: |
+ Type of archive endpoint. Usually `wayback` (WBM replay of primary
+ resource), or `warc` (direct URL to a WARC file containing all
+ resources of the capture). See guide for full list.
release_entity:
type: object
# required for creation: title
@@ -350,80 +655,167 @@ definitions:
<<: *ENTITYPROPS
title:
type: string
- description: "Required for valid entities. The title used in citations and for display; usually English"
+ description: |
+ Required for valid entities. The title used in citations and for
+ display. Sometimes the English translation of title e even if release
+ content is not English.
subtitle:
type: string
- description: "Avoid this field if possible, and merge with title; usually English"
+ description: |
+ Subtitle of release. In many cases, better to merge with title than
+ include as separate field (unless combined title would be very long).
+ See guide for details.
original_title:
type: string
- description: "Title in original language (or, the language of the full text of this release)"
+ description: |
+ Title in original language if `title` field has been translated. See
+ guide for details.
work_id:
type: string
example: "q3nouwy3nnbsvo3h5klxsx4a7y"
+ description: |
+ Identifier of work this release is part of. In creation (POST)
+ requests, a work entity will be created automatically if this field
+ is not set.
container:
$ref: "#/definitions/container_entity"
- description: "Optional; GET-only"
+ description: |
+ Complete container entity identified by `container_id` field. Only
+ included in GET reponses when `container` included in `expand`
+ parameter; ignored in PUT or POST requests.
files:
- description: "Optional; GET-only"
type: array
items:
$ref: "#/definitions/file_entity"
+ description: |
+ Complete file entities identified by `file_ids` field. Only
+ included in GET responses when `files` included in `expand` parameter;
+ ignored in PUT or POST requests.
filesets:
- description: "Optional; GET-only"
type: array
items:
$ref: "#/definitions/fileset_entity"
+ description: |
+ Complete file entities identified by `filesets_ids` field. Only
+ included in GET responses when `filesets` included in `expand`
+ parameter; ignored in PUT or POST requests.
webcaptures:
- description: "Optional; GET-only"
type: array
items:
$ref: "#/definitions/webcapture_entity"
+ description: |
+ Complete webcapture entities identified by `webcapture_ids` field.
+ Only included in GET responses when `webcaptures` included in `expand`
+ parameter; ignored in PUT or POST requests.
container_id:
type: string
example: "q3nouwy3nnbsvo3h5klxsx4a7y"
+ description: |
+ Used to link this release to a container entity that the release was
+ published as part of.
release_type:
type: string
example: "book"
+ description: |
+ "Type" or "medium" that this release is published as. See guide for
+ valid values.
release_stage:
type: string
- example: "preprint, retracted"
+ example: "preprint"
+ description: |
+ The stage of publication of this specific release. See guide for
+ valid values and semantics.
release_date:
type: string
format: date
+ description: |
+ Full date when this release was formally published. ISO format, like
+ `2019-03-05`. See guide for semantics.
release_year:
type: integer
example: 2014
format: int64
+ description: |
+ Year when this release was formally published. Must match
+ `release_date` if that field is set; this field exists because
+ sometimes only the year is known.
withdrawn_status:
type: string
+ example: "retracted"
+ description: |
+ Type of withdrawl or retraction of this release, if applicable. If
+ release has not been withdrawn, should be `null` (aka, not set, not
+ the string "null" or an empty string).
withdrawn_date:
type: string
format: date
+ description: |
+ Full date when this release was formally withdrawn (if applicable).
+ ISO format, like `release_date`.
withdrawn_year:
type: integer
example: 2014
format: int64
+ description: |
+ Year corresponding with `withdrawn_date` like
+ `release_year`/`release_date`.
ext_ids:
$ref: "#/definitions/release_ext_ids"
+ description: |
+ Set of external identifiers for this release.
volume:
type: string
+ example: "3"
+ description: |
+ Volume number of container that this release was published in. Often
+ corresponds to the "Nth" year of publication, but can be any string.
+ See guide.
issue:
type: string
example: "12"
+ description: |
+ Issue number of volume/container that this release was published in.
+ Sometimes coresponds to a month number in the year, but can be any
+ string. See guide.
pages:
type: string
+ example: "340-345"
+ description: |
+ Either a single page number ("first page") or a range of pages
+ separated by a dash ("-"). See guide for details.
number:
type: string
+ example: "RFC1337"
+ description: |
+ For, eg, technical reports, which are published in series or
+ assigned some other institutional or container-specific identifier.
version:
type: string
+ example: "3"
+ description: |
+ For, eg, updated technical reports or software packages, where
+ the version string may be the only field disambiguating between
+ releases.
publisher:
type: string
+ example: "Elsevier"
+ description: |
+ Name, usually English, of the entity or institution responsible for
+ publication of this release. Not necessarily the imprint/brand. See
+ guide.
language:
- description: "Two-letter RFC1766/ISO639-1 language code, with extensions"
type: string
+ example: "en"
+ description: |
+ Primary language of the content of the full release. Two-letter
+ RFC1766/ISO639-1 language code, with some custom
+ extensions/additions. See guide.
license_slug:
type: string
- description: "Short version of license name. Eg, 'CC-BY'"
+ example: "CC-BY"
+ description: |
+ Short string (slug) name of license under which release is openly
+ published (if applicable).
contribs:
type: array
items:
@@ -443,26 +835,44 @@ definitions:
type: string
#format: custom
example: "10.1234/abcde.789"
+ description: |
+ Digital Object Identifier (DOI), mostly for published papers and
+ datasets. Should be registered and resolvable via https://doi.org/
wikidata_qid:
type: string
+ example: "Q42812"
+ description: "Wikidata entity QID"
isbn13:
type: string
#format: custom
+ description: |
+ ISBN-13, for books. Usually not set for chapters. ISBN-10 should be
+ converted to ISBN-13.
pmid:
type: string
+ example: "482132"
+ description: "PubMed Identifier"
pmcid:
+ example: "PMC7391"
type: string
+ description: "PubMed Central Identifier"
core:
+ exmaple: "9234592"
type: string
#format: custom
+ description: "CORE (https://core.ac.uk) identifier"
arxiv:
type: string
+ description: "arXiv (https://arxiv.org) identifier; must include version"
jstor:
type: string
+ description: "JSTOR work identifier"
ark:
type: string
+ description: "ARK identifier"
mag:
type: string
+ description: "Microsoft Academic Graph identifier"
release_abstract:
type: object
properties:
@@ -471,12 +881,20 @@ definitions:
content:
type: string
example: "<jats:p>Some abstract thing goes here</jats:p>"
+ description: |
+ Abstract content. May be encoded, as per `mimetype` field, but only
+ string/text content may be included.
mimetype:
type: string
example: "application/xml+jats"
+ description: |
+ Mimetype of abstract contents. `text/plain` is the default if content
+ isn't encoded.
lang:
type: string
example: "en"
+ description: |
+ ISO language code of the abstract. Same semantics as release `language` field.
work_entity:
type: object
properties:
@@ -503,16 +921,31 @@ definitions:
properties:
edit_id:
<<: *FATCATUUID
+ description: |
+ Unique UUID for this specific edit object.
ident:
<<: *FATCATIDENT
+ description: |
+ Fatcat identifier of the entity this edit is mutating.
revision:
<<: *FATCATUUID
+ description: |
+ Entity revision that this edit will set the entity to. May be
+ `null` in the case of deletions.
prev_revision:
<<: *FATCATUUID
+ description: |
+ Revision of entity just before this edit. May be used in the future
+ to prevent edit race conditions.
redirect_ident:
<<: *FATCATIDENT
+ description: |
+ When an edit is to merge entities (redirect one to another), this
+ is the entity fatcat identifier for the target entity.
editgroup_id:
<<: *FATCATIDENT
+ description: |
+ Editgroup identifier that this edit is part of.
extra:
type: object
additionalProperties: {}
@@ -523,45 +956,91 @@ definitions:
properties:
editor_id:
<<: *FATCATIDENT
+ description: |
+ Fatcat identifier for the editor. Can not be changed.
username:
type: string
example: "zerocool93"
+ description: |
+ Username/handle (short slug-like string) to identify this editor. May
+ be changed at any time by the editor; use the `editor_id` as a
+ persistend identifer.
is_admin:
type: boolean
+ example: false
+ description: |
+ Whether this editor has the `admin` role.
is_bot:
type: boolean
+ example: false
+ description: |
+ Whether this editor is a bot (as opposed to a human making manual
+ edits)
is_active:
type: boolean
+ example: true
+ description: |
+ Whether this editor's account is enabled (if not API tokens and web
+ logins will not work).
editgroup:
type: object
properties:
editgroup_id:
<<: *FATCATIDENT
+ description: |
+ Fatcat identifier for this editgroup. Assigned on creation.
editor_id:
<<: *FATCATIDENT
+ description: |
+ Fatcat identifer of editor that created this editgroup.
editor:
$ref: "#/definitions/editor"
+ description: |
+ Complete editor object identified by `container_id` field. Only
+ included in GET responses.
changelog_index: # not returned in all contexts...
type: integer
example: 1048576
format: int64
+ description: |
+ For accepted/merged editgroups, the changelog index that the accept
+ occured at. WARNING: not populated in all contexts that an editgroup
+ could be included in a response.
created:
type: string
format: date-time
+ description: |
+ Timestamp when this editgroup was first created.
submitted:
type: string
format: date-time
+ description: |
+ Timestamp when this editgroup was most recently submitted for review.
+ If withdrawn, or never submitted, will be `null`.
description:
type: string
+ description: |
+ Comment describing the changes in this editgroup. Can be updated with
+ PUT request.
extra:
type: object
additionalProperties: {}
+ description: |
+ Free-form JSON metadata attached to this editgroup. Eg, metadata
+ provenance, or script user-agent details. See guide for (unenforced)
+ schema norms.
annotations:
type: array
items:
$ref: "#/definitions/editgroup_annotation"
+ description: |
+ Only included in GET responses, and not in all contexts. Do not
+ include this field in PUT or POST requests.
edits:
type: object
+ description: |
+ Only included in GET responses, and not in all contexts. Do not
+ include this field in PUT or POST requests.
properties:
containers:
type: array
@@ -598,18 +1077,31 @@ definitions:
<<: *FATCATUUID
editgroup_id:
<<: *FATCATIDENT
+ description: |
+ Editgroup that this annotation applies to. Set automatically in
+ creations based on URL parameter.
editor_id:
<<: *FATCATIDENT
+ description: |
+ Defaults to editor created the annotation via POST request.
editor:
$ref: "#/definitions/editor"
+ description: |
+ Only included in GET responses; ignored in PUT or POST requests.
created:
type: string
format: date-time
+ description: |
+ Timestamp when annotation was first created.
comment_markdown:
type: string
extra:
type: object
additionalProperties: {}
+ description: |
+ Additional free-form JSON metadata that can be included as part of
+ the annotation (or even as the primary annotation itself). See guide
+ for details.
changelog_entry:
type: object
required:
@@ -620,12 +1112,18 @@ definitions:
index:
type: integer
format: int64
+ description: |
+ Monotonically increasing sequence number of this changelog entry.
editgroup_id:
type: string
example: "q3nouwy3nnbsvo3h5klxsx4a7y"
+ description: |
+ Identifier of editgroup accepted/merged in this changelog entry.
timestamp:
type: string
format: date-time
+ description: |
+ Date and time when the editgroup was accpeted.
editgroup:
$ref: "#/definitions/editgroup"
release_ref:
@@ -634,48 +1132,102 @@ definitions:
index:
type: integer
format: int64
+ description: |
+ Zero-indexed sequence number of this reference in the list of
+ references. Assigned automatically and used internally; don't confuse
+ with `key`.
target_release_id:
<<: *FATCATIDENT
+ description: |
+ Optional, fatcat identifier of release entity that this reference is
+ citing.
extra:
type: object
additionalProperties: {}
+ description: |
+ Additional free-form JSON metadata about this citation. Generally
+ follows Citation Style Language (CSL) JSON schema. See guide for
+ details.
key:
type: string
+ example: "SMITH2016"
+ description: |
+ Short string used to indicate this reference from within the release
+ text; or numbering of references as typeset in the release itself.
+ Optional; don't confuse with `index` field.
year:
type: integer
format: int64
+ example: 1972
+ description: |
+ Year that the cited work was published in.
container_name:
type: string
+ description: |
+ Name of the container (eg, journal) that the citation work was
+ published as part of. May be an acronym or full name.
title:
type: string
+ description:
+ Name of the work being cited.
locator:
type: string
example: "p123"
+ description: |
+ Page number or other indicator of the specific subset of a work being
+ cited. Not to be confused with the first page (or page range) of an
+ entire paper or chapter being cited.
release_contrib:
type: object
properties:
index:
type: integer
format: int64
+ example: 0
+ description: |
+ Internally assigned zero-indexed sequence number of contribution.
+ Authors should come first; this encodes the order of attriubtion.
creator_id:
<<: *FATCATIDENT
+ description: |
+ If known, indicates the creator entity this contribution was made by.
creator:
$ref: "#/definitions/creator_entity"
- description: "Optional; GET-only"
+ description: |
+ Complete creator entity. Only returned in GET responses, and only if
+ `contribs` included in the `expand` query parameter.
raw_name:
type: string
+ example: "Jane K. Doe"
+ description: |
+ Full name of the contributor as typeset in the release.
given_name:
type: string
+ example: "Jane"
+ description: |
+ In English commonly the first name, but ordering is context and
+ culture specific.
surname:
type: string
+ example: "Doe"
+ description: |
+ In English commonly the last, or family name, but ordering is context
+ and culture specific.
role:
type: string
+ example: "author"
+ description: |
+ Short string (slug) indicating type of contribution (eg, "author",
+ "translator"). See guide for list of accpeted values.
raw_affiliation:
type: string
description: "Raw affiliation string as displayed in text"
extra:
type: object
additionalProperties: {}
+ description: |
+ Additional free-form JSON metadata about this
+ contributor/contribution. See guide for normative schema.
container_auto_batch:
type: object
required:
@@ -770,12 +1322,26 @@ definitions:
properties:
provider:
type: string
+ example: "orcid"
+ description: |
+ Fatcat-specific short name (slug) for remote service being used for
+ authentication.
sub:
type: string
+ description: "`SUB` from OIDC protocol. Usually a URL."
+ example: "https://orcid.org"
iss:
type: string
+ description: "`ISS` from OIDC protocol. Usually a stable account username, number, or identifier."
+ example: "0000-0002-8593-9468"
preferred_username:
type: string
+ description: |
+ What it sounds like; returned by OIDC, and used as a hint when
+ creating new editor accounts. Fatcat usernames are usually this
+ string with the `provider` slug as a suffix, though some munging may
+ occur.
+ example: "bnewbold"
auth_oidc_result:
type: object
required:
@@ -786,6 +1352,7 @@ definitions:
$ref: "#/definitions/editor"
token:
type: string
+ example: "AgEPZGV2LmZhdGNhdC53aWtpAhYyMDE5MDEwMS1kZXYtZHVtbXkta2V5AAImZWRpdG9yX2lkID0gYWFhYWFhYWFhYWFhYmt2a2FhYWFhYWFhYWkAAht0aW1lID4gMjAxOS0wMS0wOVQwMDo1Nzo1MloAAAYgnroNha1hSftChtxHGTnLEmM/pY8MeQS/jBSV0UNvXug="
x-auth-responses: &AUTHRESPONSES
401:
@@ -824,6 +1391,11 @@ paths:
operationId: "create_container"
tags: # TAGLINE
- containers # TAGLINE
+ description: |
+ Create a single Container entity as part of an existing editgroup.
+
+ Editgroup must be mutable (aka, not accepted) and editor must have
+ permission (aka, have created the editgrou p or have `admin` role).
parameters:
- name: entity
in: body
@@ -844,6 +1416,15 @@ paths:
operationId: "create_container_auto_batch"
tags: # TAGLINE
- containers # TAGLINE
+ description: |
+ Create a set of Container entities as part of a new editgroup, and
+ accept that editgroup in the same atomic request.
+
+ This method is mostly useful for bulk import of new entities by
+ carefully written bots. This method is more efficient than creating an
+ editgroup, several entities, then accepting the editgroup, both in
+ terms of API requests required and database load. Requires `admin`
+ role.
parameters:
- name: auto_batch
in: body
@@ -869,6 +1450,8 @@ paths:
operationId: "get_container"
tags: # TAGLINE
- containers # TAGLINE
+ description: |
+ Fetches a single container entity from the catalog.
parameters:
- name: expand
in: query
@@ -900,6 +1483,16 @@ paths:
operationId: "update_container"
tags: # TAGLINE
- containers # TAGLINE
+ description: |
+ Updates an existing entity as part of a specific (existing) editgroup.
+ The editgroup must be open for updates (aka, not accepted/merged), and
+ the editor making the requiest must have permissions (aka, must have
+ created the editgroup or have `admin` role).
+
+ This method can also be used to update an existing entity edit as part
+ of an editgroup. For example, if an entity was created in this
+ editgroup, an editor could make changes to the new entity's metadata
+ before merging.
parameters:
- name: entity
in: body
@@ -919,6 +1512,12 @@ paths:
operationId: "delete_container"
tags: # TAGLINE
- containers # TAGLINE
+ description: |
+ Creates a new "deletion" edit for a specific entity as part of an
+ existing editgroup.
+
+ This is not the method to use to remove an edit from an editgroup; for
+ that use `delete_container_edit`.
security:
- Bearer: []
responses:
@@ -938,17 +1537,24 @@ paths:
operationId: "get_container_revision"
tags: # TAGLINE
- containers # TAGLINE
+ description: |
+ Fetches a specific entity revision. Note that the returned revision
+ will not be associated with any particular fatcat identifier (even if
+ one or more identifiers do currently point to this revision). The
+ revision may even be part of an un-merged editgroup.
+
+ Revisions are immutable and can not be deleted or updated.
parameters:
- name: expand
in: query
type: string
required: false
- description: "List of sub-entities to expand in response. For containers, none accepted (yet)."
+ description: "List of sub-entities to expand in response. See `get_container`."
- name: hide
in: query
type: string
required: false
- description: "List of entity fields to elide in response. For containers, none accepted (yet)."
+ description: "List of entity fields to elide in response. See `get_container`."
responses:
200:
description: Found Entity Revision
@@ -966,9 +1572,13 @@ paths:
type: integer
format: int64
required: false
+ description: "Maximum number of changelog entries to return"
get:
tags: # TAGLINE
- containers # TAGLINE
+ description: |
+ Fetches the history of accepted edits (changelog entries) for a
+ specific entity fatcat identifier.
operationId: "get_container_history"
responses:
200:
@@ -985,9 +1595,12 @@ paths:
type: string
required: true
get:
+ operationId: "get_container_redirects"
tags: # TAGLINE
- containers # TAGLINE
- operationId: "get_container_redirects"
+ description: |
+ Returns the set of entity identifiers which currently redirect to this
+ identifier.
responses:
200:
description: Found Entity Redirects
@@ -1001,6 +1614,14 @@ paths:
operationId: "lookup_container"
tags: # TAGLINE
- containers # TAGLINE
+ description: |
+ Looks for an active entity with the given external identifier. If any
+ such entity is found, returns a single complete entity. If multiple
+ entities have the same external identifier, this is considered a soft
+ catalog error, and the behavior of which entity is returned is
+ undefined.
+
+ One (and only one) external identifier should be specified per request.
parameters:
- name: issnl
in: query
@@ -1009,16 +1630,17 @@ paths:
- name: wikidata_qid
in: query
required: false
+ example: "Q42812"
- name: expand
in: query
type: string
required: false
- description: "List of sub-entities to expand in response."
+ description: "List of sub-entities to expand in response. See `get_container`."
- name: hide
in: query
type: string
required: false
- description: "List of entity fields to elide in response. For container, none accepted (yet)."
+ description: "List of entity fields to elide in response. See `get_container`."
responses:
200:
description: Found Entity
@@ -1030,6 +1652,9 @@ paths:
operationId: "get_container_edit"
tags: # TAGLINE
- containers # TAGLINE
+ description: |
+ Returns the entity edit object with the given identifier. This method
+ is expected to be used rarely.
parameters:
- name: edit_id
in: path
@@ -1055,6 +1680,14 @@ paths:
operationId: "delete_container_edit"
tags: # TAGLINE
- containers # TAGLINE
+ description: |
+ Removes a single edit from the specified editgroup. The editgroup must
+ be mutable (aka, not accepted/merged), and the editor making this
+ request must have permission (aka, have created the editgroup or hold
+ the `admin` role).
+
+ Not to be confused with the `delete_container` method, which *creates*
+ a new edit in the given editgroup.
security:
- Bearer: []
responses:
@@ -1064,6 +1697,7 @@ paths:
$ref: "#/definitions/success"
<<: *ENTITYRESPONSES
<<: *AUTHRESPONSES
+
/editgroup/{editgroup_id}/creator:
parameters:
- name: editgroup_id
@@ -1129,7 +1763,7 @@ paths:
in: query
type: string
required: false
- description: "List of entity fields to elide in response. For containers, none accepted (yet)."
+ description: "List of entity fields to elide in response. For creators, none accepted (yet)."
responses:
200:
description: Found Entity
@@ -1193,12 +1827,15 @@ paths:
in: query
type: string
required: false
- description: "List of sub-entities to expand in response. For creators, none accepted (yet)."
+ description: |
+ List of sub-entities to expand in response. See `get_creator`,
+ though note that identifier-based expansions (like `releases`) will
+ always be empty for revisions.
- name: hide
in: query
type: string
required: false
- description: "List of entity fields to elide in response. For creators, none accepted (yet)."
+ description: "List of entity fields to elide in response. See `get_creator`."
responses:
200:
description: Found Entity Revision
@@ -1238,11 +1875,14 @@ paths:
in: query
type: string
required: false
- description: "List of entity fields to elide in response. For creators, none implemented yet."
+ description: "List of entity fields to elide in response. See `get_release`."
get:
operationId: "get_creator_releases"
tags: # TAGLINE
- creators # TAGLINE
+ description: |
+ Returns the set of Release entities having a `contrib` entry pointing
+ to the creator entity.
responses:
200:
description: Found
@@ -1258,9 +1898,9 @@ paths:
type: string
required: true
get:
+ operationId: "get_creator_redirects"
tags: # TAGLINE
- creators # TAGLINE
- operationId: "get_creator_redirects"
responses:
200:
description: Found Entity Redirects
@@ -1282,16 +1922,17 @@ paths:
- name: wikidata_qid
in: query
required: false
+ example: "Q42812"
- name: expand
in: query
type: string
required: false
- description: "List of sub-entities to expand in response."
+ description: "List of sub-entities to expand in response. See `get_creator`."
- name: hide
in: query
type: string
required: false
- description: "List of entity fields to elide in response. For creator, none accepted (yet)."
+ description: "List of entity fields to elide in response. See `get_creator`."
responses:
200:
description: Found Entity
@@ -1337,6 +1978,7 @@ paths:
$ref: "#/definitions/success"
<<: *ENTITYRESPONSES
<<: *AUTHRESPONSES
+
/editgroup/{editgroup_id}/file:
parameters:
- name: editgroup_id
@@ -1466,12 +2108,12 @@ paths:
in: query
type: string
required: false
- description: "List of sub-entities to expand in response. For files, none accepted (yet)."
+ description: "List of sub-entities to expand in response. See `get_file`."
- name: hide
in: query
type: string
required: false
- description: "List of entity fields to elide in response. For files, none accepted (yet)."
+ description: "List of entity fields to elide in response. See `get_file`."
responses:
200:
description: Found Entity Revision
@@ -1508,9 +2150,9 @@ paths:
type: string
required: true
get:
+ operationId: "get_file_redirects"
tags: # TAGLINE
- files # TAGLINE
- operationId: "get_file_redirects"
responses:
200:
description: Found Entity Redirects
@@ -1541,12 +2183,12 @@ paths:
in: query
type: string
required: false
- description: "List of sub-entities to expand in response."
+ description: "List of sub-entities to expand in response. See `get_file`."
- name: hide
in: query
type: string
required: false
- description: "List of entity fields to elide in response. For files, none accepted (yet)."
+ description: "List of entity fields to elide in response. See `get_file`."
responses:
200:
description: Found Entity
@@ -1592,6 +2234,7 @@ paths:
$ref: "#/definitions/success"
<<: *ENTITYRESPONSES
<<: *AUTHRESPONSES
+
/editgroup/{editgroup_id}/fileset:
parameters:
- name: editgroup_id
@@ -1721,12 +2364,12 @@ paths:
in: query
type: string
required: false
- description: "List of sub-entities to expand in response. For filesets, none accepted (yet)."
+ description: "List of sub-entities to expand in response. See `get_fileset`."
- name: hide
in: query
type: string
required: false
- description: "List of entity fields to elide in response. For filesets, 'manifest' is accepted."
+ description: "List of entity fields to elide in response. See `get_fileset`."
responses:
200:
description: Found Entity Revision
@@ -1763,9 +2406,9 @@ paths:
type: string
required: true
get:
+ operationId: "get_fileset_redirects"
tags: # TAGLINE
- filesets # TAGLINE
- operationId: "get_fileset_redirects"
responses:
200:
description: Found Entity Redirects
@@ -1813,6 +2456,7 @@ paths:
$ref: "#/definitions/success"
<<: *ENTITYRESPONSES
<<: *AUTHRESPONSES
+
/editgroup/{editgroup_id}/webcapture:
parameters:
- name: editgroup_id
@@ -1942,12 +2586,12 @@ paths:
in: query
type: string
required: false
- description: "List of sub-entities to expand in response. For webcaptures, none accepted (yet)."
+ description: "List of sub-entities to expand in response. See `get_webcapture`."
- name: hide
in: query
type: string
required: false
- description: "List of entity fields to elide in response. For webcaptures, 'cdx' is accepted."
+ description: "List of entity fields to elide in response. See `get_webcapture`."
responses:
200:
description: Found Entity Revision
@@ -1984,9 +2628,9 @@ paths:
type: string
required: true
get:
+ operationId: "get_webcapture_redirects"
tags: # TAGLINE
- webcaptures # TAGLINE
- operationId: "get_webcapture_redirects"
responses:
200:
description: Found Entity Redirects
@@ -2034,6 +2678,7 @@ paths:
$ref: "#/definitions/success"
<<: *ENTITYRESPONSES
<<: *AUTHRESPONSES
+
/editgroup/{editgroup_id}/release:
parameters:
- name: editgroup_id
@@ -2044,6 +2689,13 @@ paths:
operationId: "create_release"
tags: # TAGLINE
- releases # TAGLINE
+ description: |
+ Create a single Release entity as part of an existing editgroup. If the
+ `work_id` field is not set, a work entity will be created automatically
+ and this field set pointing to the new work.
+
+ Editgroup must be mutable (aka, not accepted) and editor must have
+ permission (aka, have created the editgrou p or have `admin` role).
parameters:
- name: entity
in: body
@@ -2064,6 +2716,15 @@ paths:
operationId: "create_release_auto_batch"
tags: # TAGLINE
- releases # TAGLINE
+ description: |
+ Create a set of Release entities as part of a new editgroup, and
+ accept that editgroup in the same atomic request.
+
+ This method is mostly useful for bulk import of new entities by
+ carefully written bots. This method is more efficient than creating an
+ editgroup, several entities, then accepting the editgroup, both in
+ terms of API requests required and database load. Requires `admin`
+ role.
parameters:
- name: auto_batch
in: body
@@ -2089,17 +2750,23 @@ paths:
operationId: "get_release"
tags: # TAGLINE
- releases # TAGLINE
+ description: |
+ Fetches a single Release entity from the catalog.
parameters:
- name: expand
in: query
type: string
required: false
- description: "List of sub-entities to expand in response. For releases, 'files', 'filesets, 'webcaptures', 'container', and 'creators' are valid."
+ description: |
+ List of sub-entities to expand in response. For releases, 'files',
+ 'filesets, 'webcaptures', 'container', and 'creators' are valid.
- name: hide
in: query
type: string
required: false
- description: "List of entity fields to elide in response. For releases, 'abstracts', 'refs', and 'contribs' are valid."
+ description: |
+ List of entity fields to elide in response (for efficiency). For
+ releases, 'abstracts', 'refs', and 'contribs' are valid.
responses:
200:
description: Found Entity
@@ -2120,6 +2787,16 @@ paths:
operationId: "update_release"
tags: # TAGLINE
- releases # TAGLINE
+ description: |
+ Updates an existing entity as part of a specific (existing) editgroup.
+ The editgroup must be open for updates (aka, not accepted/merged), and
+ the editor making the requiest must have permissions (aka, must have
+ created the editgroup or have `admin` role).
+
+ This method can also be used to update an existing entity edit as part
+ of an editgroup. For example, if an entity was created in this
+ editgroup, an editor could make changes to the new entity's metadata
+ before merging.
parameters:
- name: entity
in: body
@@ -2139,6 +2816,12 @@ paths:
operationId: "delete_release"
tags: # TAGLINE
- releases # TAGLINE
+ description: |
+ Creates a new "deletion" edit for a specific entity as part of an
+ existing editgroup.
+
+ This is not the method to use to remove an edit from an editgroup; for
+ that use `delete_release_edit`.
security:
- Bearer: []
responses:
@@ -2158,17 +2841,27 @@ paths:
operationId: "get_release_revision"
tags: # TAGLINE
- releases # TAGLINE
+ description: |
+ Fetches a specific entity revision. Note that the returned revision
+ will not be associated with any particular fatcat identifier (even if
+ one or more identifiers do currently point to this revision). The
+ revision may even be part of an un-merged editgroup.
+
+ Revisions are immutable and can not be deleted or updated.
parameters:
- name: expand
in: query
type: string
required: false
- description: "List of sub-entities to expand in response. For releases, none accepted (yet)."
+ description:
+ List of sub-entities to expand in response. See `get_release`,
+ though note that identifier-based exapansions like `file` will
+ always be empty for revisions.
- name: hide
in: query
type: string
required: false
- description: "List of entity fields to elide in response. For releases, none accepted (yet)."
+ description: "List of entity fields to elide in response. See `get_release`."
responses:
200:
description: Found Entity Revision
@@ -2190,6 +2883,9 @@ paths:
operationId: "get_release_history"
tags: # TAGLINE
- releases # TAGLINE
+ description: |
+ Fetches the history of accepted edits (changelog entries) for a
+ specific entity fatcat identifier.
responses:
200:
description: Found Entity History
@@ -2208,11 +2904,14 @@ paths:
in: query
type: string
required: false
- description: "List of entity fields to elide in response. For files, none accepted (yet)."
+ description: "List of entity fields to elide in response. See `get_file`."
get:
operationId: "get_release_files"
tags: # TAGLINE
- releases # TAGLINE
+ description: |
+ Returns the set of File entities that have a `release_id` pointing to
+ this release entity.
responses:
200:
description: Found
@@ -2231,11 +2930,14 @@ paths:
in: query
type: string
required: false
- description: "List of entity fields to elide in response. For filesets, 'manifest' is valid."
+ description: "List of entity fields to elide in response. See `get_fileset`."
get:
operationId: "get_release_filesets"
tags: # TAGLINE
- releases # TAGLINE
+ description: |
+ Returns the set of Fileset entities that have a `release_id` pointing to
+ this release entity.
responses:
200:
description: Found
@@ -2254,11 +2956,14 @@ paths:
in: query
type: string
required: false
- description: "List of entity fields to elide in response. For webcaptures, 'cdx' is valid."
+ description: "List of entity fields to elide in response. See `get_webcapture`."
get:
operationId: "get_release_webcaptures"
tags: # TAGLINE
- releases # TAGLINE
+ description: |
+ Returns the set of Web Capture entities that have a `release_id`
+ pointing to this release entity.
responses:
200:
description: Found
@@ -2274,9 +2979,12 @@ paths:
type: string
required: true
get:
+ operationId: "get_release_redirects"
tags: # TAGLINE
- releases # TAGLINE
- operationId: "get_release_redirects"
+ description: |
+ Returns the set of entity identifiers which currently redirect to this
+ identifier.
responses:
200:
description: Found Entity Redirects
@@ -2290,7 +2998,16 @@ paths:
operationId: "lookup_release"
tags: # TAGLINE
- releases # TAGLINE
+ description: |
+ Looks for an active entity with the given external identifier. If any
+ such entity is found, returns a single complete entity. If multiple
+ entities have the same external identifier, this is considered a soft
+ catalog error, and the behavior of which entity is returned is
+ undefined.
+
+ One (and only one) external identifier should be specified per request.
parameters:
+ # TODO: use identifier types here
- name: doi
in: query
type: string
@@ -2335,12 +3052,12 @@ paths:
in: query
type: string
required: false
- description: "List of sub-entities to expand in response."
+ description: "List of sub-entities to expand in response. See `get_release`."
- name: hide
in: query
type: string
required: false
- description: "List of sub-entities to expand in response. For releases, 'files', 'filesets, 'webcaptures', 'container', and 'creators' are valid."
+ description: "List of sub-entities to elide in response. See `get_release`."
responses:
200:
description: Found Entity
@@ -2352,6 +3069,9 @@ paths:
operationId: "get_release_edit"
tags: # TAGLINE
- releases # TAGLINE
+ description: |
+ Returns the entity edit object with the given identifier. This method
+ is expected to be used rarely.
parameters:
- name: edit_id
in: path
@@ -2377,6 +3097,14 @@ paths:
operationId: "delete_release_edit"
tags: # TAGLINE
- releases # TAGLINE
+ description: |
+ Removes a single edit from the specified editgroup. The editgroup must
+ be mutable (aka, not accepted/merged), and the editor making this
+ request must have permission (aka, have created the editgroup or hold
+ the `admin` role).
+
+ Not to be confused with the `delete_container` method, which *creates*
+ a new edit in the given editgroup.
security:
- Bearer: []
responses:
@@ -2386,6 +3114,7 @@ paths:
$ref: "#/definitions/success"
<<: *ENTITYRESPONSES
<<: *AUTHRESPONSES
+
/editgroup/{editgroup_id}/work:
parameters:
- name: editgroup_id
@@ -2395,7 +3124,7 @@ paths:
post:
operationId: "create_work"
tags: # TAGLINE
- - releases # TAGLINE
+ - works # TAGLINE
parameters:
- name: entity
in: body
@@ -2515,12 +3244,15 @@ paths:
in: query
type: string
required: false
- description: "List of sub-entities to expand in response. For works, none accepted (yet)."
+ description:
+ List of sub-entities to expand in response. See `get_work`, though
+ note that identifier-based expansions like `releases` will always
+ be empty for revisions.
- name: hide
in: query
type: string
required: false
- description: "List of entity fields to elide in response. For works, none accepted (yet)."
+ description: "List of entity fields to elide in response. See `get_work`."
responses:
200:
description: Found Entity Revision
@@ -2557,9 +3289,9 @@ paths:
type: string
required: true
get:
+ operationId: "get_work_redirects"
tags: # TAGLINE
- works # TAGLINE
- operationId: "get_work_redirects"
responses:
200:
description: Found Entity Redirects
@@ -2578,11 +3310,14 @@ paths:
in: query
type: string
required: false
- description: "List of entity fields to elide in response. For works, none implemented yet."
+ description: "List of entity fields to elide in response. See `get_release`."
get:
operationId: "get_work_releases"
tags: # TAGLINE
- works # TAGLINE
+ description: |
+ Returns the set of release entities that are part of this work (aka,
+ have `work_id` pointing to this work entity).
responses:
200:
description: Found
@@ -2630,6 +3365,7 @@ paths:
$ref: "#/definitions/success"
<<: *ENTITYRESPONSES
<<: *AUTHRESPONSES
+
/editor/{editor_id}:
parameters:
- name: editor_id
@@ -2638,6 +3374,11 @@ paths:
required: true
get:
operationId: "get_editor"
+ tags: # TAGLINE
+ - editors # TAGLINE
+ description: |
+ Returns an editor object, including metadata such as the username,
+ type, and role of editor.
responses:
200:
description: Found
@@ -2657,6 +3398,14 @@ paths:
$ref: "#/definitions/error_response"
put:
operationId: "update_editor"
+ tags: # TAGLINE
+ - editors # TAGLINE
+ description: |
+ Allows metadata changes to some editor fields, such as the username.
+
+ Changes require authentication and permissions. An editor can change
+ their own username; changes to role flags require the `admin` role by
+ the editor making the request.
parameters:
- name: editor
in: body
@@ -2691,6 +3440,11 @@ paths:
required: true
get:
operationId: "get_editor_editgroups"
+ tags: # TAGLINE
+ - editors # TAGLINE
+ description: |
+ Returns a set of editgroups created by the given editor, regardless of
+ the status (accepted/submitted) of the editgroups.
parameters:
- name: limit
in: query
@@ -2702,11 +3456,19 @@ paths:
type: string
format: date-time
required: false
+ description: |
+ Return only editgroups created *before* the given timestamp (not
+ inclusive). Editgroups will be sorted by creation time in
+ descending order (most recent first). For use in pagination.
- name: since
in: query
type: string
format: date-time
required: false
+ description: |
+ Return only editgroups created *after* the given timestamp (not
+ inclusive). Editgroups will be sorted by creation time in ascending
+ order (most recent last). For use in pagination.
responses:
200:
description: Found
@@ -2735,23 +3497,34 @@ paths:
get:
operationId: "get_editor_annotations"
tags: # TAGLINE
- - edit-lifecycle # TAGLINE
+ - editors # TAGLINE
+ description: |
+ Fetches a list of annotations made by a particular editor.
parameters:
- name: limit
in: query
type: integer
format: int64
required: false
+ description: "Maximum number (count) of annotations to return in response"
- name: before
in: query
type: string
format: date-time
required: false
+ description: |
+ Return only annotations made *before* the given timestamp (not
+ inclusive). Annotations will be sorted by creation time in
+ descending order (most recent first). For use in pagination.
- name: since
in: query
type: string
format: date-time
required: false
+ description: |
+ Return only annotations made *after* the given timestamp (not
+ inclusive). Annotations will be sorted by creation time in
+ ascending order (most recent last). For use in pagination.
responses:
200:
description: Success
@@ -2772,11 +3545,15 @@ paths:
schema:
$ref: "#/definitions/error_response"
<<: *AUTHRESPONSES
+
/editgroup:
post:
operationId: "create_editgroup"
tags: # TAGLINE
- - edit-lifecycle # TAGLINE
+ - editgroups # TAGLINE
+ description: |
+ Creates a new editgroup. By default the editor making this request will
+ be the author of the editgroup.
parameters:
- name: editgroup
in: body
@@ -2812,7 +3589,13 @@ paths:
get:
operationId: "get_editgroup"
tags: # TAGLINE
- - edit-lifecycle # TAGLINE
+ - editgroups # TAGLINE
+ description: |
+ Returns a single editgroup object.
+
+ Unlike some similar methods, this method will return a full/expanded
+ editgroup object, which includes edit lists of each entity type (though
+ will not include the complete entity objects).
responses:
200:
description: Found
@@ -2832,6 +3615,14 @@ paths:
$ref: "#/definitions/error_response"
put:
operationId: "update_editgroup"
+ tags: # TAGLINE
+ - editgroups # TAGLINE
+ description: |
+ Updates metadata for a single editgroup object. Note that only metadata
+ fields such as the `description` or `extra` metadata can be changed
+ with this method; it does not allow adding or removing edits to the
+ editgroup (for that use the individual entity create/update/delete
+ methods).
security:
- Bearer: []
parameters:
@@ -2871,7 +3662,11 @@ paths:
post:
operationId: "accept_editgroup"
tags: # TAGLINE
- - edit-lifecycle # TAGLINE
+ - editgroups # TAGLINE
+ description: |
+ Accept ("merge") the given editgroup into the catalog. The editgroup
+ must be open (not already accepted), and the editor making this request
+ must have the `admin` role.
security:
- Bearer: []
responses:
@@ -2905,13 +3700,15 @@ paths:
get:
operationId: "get_editgroup_annotations"
tags: # TAGLINE
- - edit-lifecycle # TAGLINE
+ - editgroups # TAGLINE
+ description:
+ Returns a list of annotations made to a specific editgroup.
parameters:
- name: expand
in: query
type: string
required: false
- description: "List of sub-entities to expand in response. For editgroups: 'editors'"
+ description: "List of sub-entities to expand in response. For editgroup annotations: 'editors'"
responses:
200:
description: Success
@@ -2941,7 +3738,12 @@ paths:
post:
operationId: "create_editgroup_annotation"
tags: # TAGLINE
- - edit-lifecycle # TAGLINE
+ - editgroups # TAGLINE
+ description: |
+ Submits a new annotation to the specified editgroup.
+
+ The editgroup must be open (not already accepted). The annotation will
+ automatically have authorship of the editor making this request.
security:
- Bearer: []
parameters:
@@ -2971,6 +3773,12 @@ paths:
/editgroup/reviewable:
get:
operationId: "get_editgroups_reviewable"
+ tags: # TAGLINE
+ - editgroups # TAGLINE
+ description: |
+ Returns a set of editgroups which have been submitted but not yet accepted.
+
+ Query parameters can be used to sort and paginate the list returned.
parameters:
- name: expand
in: query
@@ -2982,16 +3790,25 @@ paths:
type: integer
format: int64
required: false
+ description: "Maximum number of reviewable editgroups to return in response"
- name: before
in: query
type: string
format: date-time
required: false
+ description: |
+ Return only reviewable editgroups submitted *before* the given
+ timestamp (not inclusive). Editgroups will be sorted by submission
+ time in descending order (most recent first). For use in pagination.
- name: since
in: query
type: string
format: date-time
required: false
+ description: |
+ Return only reviewable editgroups submitted *after* the given
+ timestamp (not inclusive). Editgroups will be sorted by submission
+ time in ascending order (most recent last). For use in pagination.
responses:
200:
description: Found
@@ -3018,10 +3835,27 @@ paths:
type: integer
format: int64
required: false
+ description: "Maximum count of changelog entries to return in response"
get:
operationId: "get_changelog"
tags: # TAGLINE
- - edit-lifecycle # TAGLINE
+ - changelog # TAGLINE
+ description: |
+ Returns a list of the most recent changelog entries accepted (merged)
+ into the catalog.
+
+ List is sorted by changelog index in descending order. Note that the
+ accepted timestamp roughly corresponds to order, but not strictly;
+ there exist out-of-order timestamps on the order of several seconds.
+
+ As a known database issue, it is technically possible for there to be a
+ gap in changelog index numbers (aka, a missing changelog entry). There
+ are no currently known gaps and this is considered a bug that will be
+ addressed.
+
+ There are millions of entries; to paginate through all of them, use
+ this method to discover the highest existing entry number, then request
+ the entries using `get_changelog_entry` one at a time.
responses:
200:
description: Success
@@ -3044,10 +3878,18 @@ paths:
type: integer
format: int64
required: true
+ description: "Changelog index of entry to return"
get:
operationId: "get_changelog_entry"
tags: # TAGLINE
- - edit-lifecycle # TAGLINE
+ - changelog # TAGLINE
+ description: |
+ Returns a single changelog entry.
+
+ As a known database issue, it is technically possible for there to be a
+ gap in changelog index numbers (aka, a missing changelog entry). There
+ are no currently known gaps and this is considered a bug that will be
+ addressed.
responses:
200:
description: Found Changelog Entry
@@ -3069,6 +3911,18 @@ paths:
post:
operationId: "auth_oidc"
tags: # TAGLINE
+ - auth # TAGLINE
+ description: |
+ Login or create editor account using OIDC metadata (internal method).
+
+ This method is used by privileged front-end tools (like the web
+ interface service) to process editor logins using OpenID Connect (OIDC)
+ and/or OAuth. Most accounts (including tool and bot accounts) do not
+ have sufficient privileges to call this method, which requires the
+ `admin` role.
+
+ The method returns an API token; the HTTP status code indicates whether
+ an existing account was logged in, or a new account was created.
security:
# required admin privs
- Bearer: []
@@ -3104,6 +3958,11 @@ paths:
get:
operationId: "auth_check"
tags: # TAGLINE
+ - auth # TAGLINE
+ description: |
+ Verify that authentication (API token) is working as expected. The
+ optional `role` parameter can be used to verify that the current
+ account (editor) has permissions for the given role.
security:
# required admin privs
- Bearer: []