summaryrefslogtreecommitdiffstats
path: root/rust/fatcat-openapi/api
diff options
context:
space:
mode:
authorBryan Newbold <bnewbold@robocracy.org>2019-09-13 11:27:09 -0700
committerBryan Newbold <bnewbold@robocracy.org>2019-09-13 11:32:05 -0700
commiteb6993c6cc40e532cb1462e44408ed30db5244c0 (patch)
tree3dce637443f1fdf602f8967b65b140456445f004 /rust/fatcat-openapi/api
parent601f3f6ac91546dd5e047c3e932a61c402305826 (diff)
downloadfatcat-eb6993c6cc40e532cb1462e44408ed30db5244c0.tar.gz
fatcat-eb6993c6cc40e532cb1462e44408ed30db5244c0.zip
rust codegen
This re-ordered a lot of code, because several endpoints had their tags changed, but should be no actual change in behavior/spec.
Diffstat (limited to 'rust/fatcat-openapi/api')
-rw-r--r--rust/fatcat-openapi/api/swagger.yaml1052
1 files changed, 830 insertions, 222 deletions
diff --git a/rust/fatcat-openapi/api/swagger.yaml b/rust/fatcat-openapi/api/swagger.yaml
index b4c5e657..296570af 100644
--- a/rust/fatcat-openapi/api/swagger.yaml
+++ b/rust/fatcat-openapi/api/swagger.yaml
@@ -1,21 +1,146 @@
---
swagger: "2.0"
info:
- description: "A scalable, versioned, API-oriented catalog of bibliographic entities\
- \ and file metadata"
+ description: "Fatcat is a scalable, versioned, API-oriented catalog of bibliographic\n\
+ entities and file metadata.\n\n<!-- STARTLONGDESCRIPTION -->\nThese API reference\
+ \ documents, along with client software libraries, are\ngenerated automatically\
+ \ from an OpenAPI 2.0 (\"Swagger\") definition file.\n\n## Introduction\n\n\n\
+ A higher-level introduction to the API, as well as a description of the\nfatcat\
+ \ data model, are available in [\"The Fatcat Guide\"](https://guide.fatcat.wiki/).\n\
+ The guide also includes a [Cookbook](https://guide.fatcat.wiki/cookbook.html)\n\
+ section demonstrating end-to-end tasks like creating entities as part of\neditgroups,\
+ \ or safely merging duplicate entities.\n\n### Expectations and Best Practices\n\
+ \nA test/staging QA API instance of fatcat is available at\n<https://api.qa.fatcat.wiki/v0>.\
+ \ The database backing this instance is\nseparate from the production interface,\
+ \ and is periodically rebuilt from\nsnapshots of the full production database,\
+ \ meaning that edits on the QA\nserver will *NOT* persist, and that semantics\
+ \ like the changelog index\nmonotonically increasing *MAY* be broken. Developers\
+ \ are expexcted to test\ntheir scripts and tools against the QA instance before\
+ \ running against\nproduction.\n\nFatcat is made available as a gratis (no cost)\
+ \ and libre (freedom\npreserving) service to the public, with limited funding\
+ \ and resources. We\nwelcome new and unforseen uses and contributions, but may\
+ \ need to impose\nrestrictions (like rate-limits) to keep the service functional\
+ \ for other\nusers, and in extreme cases reserve the option to block accounts\
+ \ and IP\nranges if necessary to keep the service operational.\n\nThe Internet\
+ \ Archive owns and operates it's own server equipment and data\ncenters, and operations\
+ \ are optimized for low-cost, not high-availability.\nUsers and partners should\
+ \ expect some downtime on the fatcat API, on the\norder of hours a month.\n\n\
+ Periodic metadata exports are available for batch processing, and database\nsnapshots\
+ \ can be used to create locally-hosted mirrors of the service for\nmore intensive\
+ \ and reliable querying.\n\n### Other Nitty Gritties\n\nCross-origin requests\
+ \ are allowed for the API service, to enable third\nparties to bulid in-browser\
+ \ applications.\n\nA metadata search service is available at <https://search.fatcat.wiki>\
+ \ (and\n<https://search.qa.fatcat.wiki>). The API is currently the raw\nelasticsearch\
+ \ API, with only GET (read) requests allowed. This public\nservice is experimental\
+ \ and may be removed or limited in the future.\n\n## Authentication\n\nThe API\
+ \ allows basic read-only \"GET\" HTTP requests with no authentication.\nProposing\
+ \ changes to the metadata, or other mutating requests (\"PUT\",\n\"POST\", \"\
+ DELETE\") all require authentication, and some operations require\nadditional\
+ \ account permissions.\n\nEnd-user account creation and login happens through\
+ \ the web interface. From\na logged-in editor profile page, you can generate a\
+ \ API token. Tokens are\n\"macaroons\", similar to JWT tokens, and are used for\
+ \ all API\nauthentication. The web interface includes macaroons in browser cookies\
+ \ and\npasses them through to the API to authenticate editor actions.\n\n<!--\
+ \ ReDoc-Inject: <security-definitions> -->\n<!-- ENDLONGDESCRIPTION -->\n"
version: "0.3.0"
title: "fatcat"
+ termsOfService: "https://guide.fatcat.wiki/policies.html"
+ contact:
+ name: "Internet Archive Web Group"
+ url: "https://fatcat.wiki"
+ email: "webservices@archive.org"
+ x-logo:
+ url: "https://fatcat.wiki/static/paper_man_confused.gif"
+ altText: "Confused Papers Man (Logo)"
+ backgroundColor: "#FFFFFF"
host: "api.fatcat.wiki"
basePath: "/v0"
tags:
- name: "containers"
+ description: "**Container** entities represent publication venues like journals,\
+ \ # TAGLINE\nconference proceedings, book series, or blogs. They group publications\
+ \ # TAGLINE\n(\"releases\"). # TAGLINE\n\nSee the \"Catalog Style Guide\" section\
+ \ of the guide for details and # TAGLINE\nsemantics of what should be included\
+ \ in specific entity fields. # TAGLINE\nSpecifically, the # TAGLINE\n[Container\
+ \ Entity Reference](https://guide.fatcat.wiki/entity_container.html). # TAGLINE\n"
+ x-displayName: "Containers"
- name: "creators"
+ description: "**Creator** entities represent individuals (or organizations, or other\
+ \ # TAGLINE\nagents) who contribute to the creation of specific releases # TAGLINE\n\
+ (publications). # TAGLINE\n\nSee the \"Catalog Style Guide\" section of the guide\
+ \ for details and # TAGLINE\nsemantics of what should be included in specific\
+ \ entity fields. # TAGLINE\nSpecifically, the # TAGLINE\n[Creator Entity Reference](https://guide.fatcat.wiki/entity_creator.html).\
+ \ # TAGLINE\n"
+ x-displayName: "Creators"
- name: "files"
+ description: "**File** entities represent unique digital files which are full #\
+ \ TAGLINE\nmanifestations of specific releases (publications), such as fulltext\
+ \ PDF # TAGLINE\nfiles, JATS XML documents, or video files. File entities also\
+ \ include a # TAGLINE\nset of locations where they can be found on the public\
+ \ web. # TAGLINE\n\nSee the \"Catalog Style Guide\" section of the guide for\
+ \ details and # TAGLINE\nsemantics of what should be included in specific entity\
+ \ fields. # TAGLINE\nSpecifically, the # TAGLINE\n[File Entity Reference](https://guide.fatcat.wiki/entity_file.html).\
+ \ # TAGLINE\n"
+ x-displayName: "Files"
- name: "filesets"
+ description: "**Fileset** entities represent sets of digital files, as well as locations\
+ \ # TAGLINE\nwhere they can be found on the public web. Filesets most commonly\
+ \ # TAGLINE\nrepresent datasets consisting of serveral data and metadata files.\
+ \ # TAGLINE\n\nSee the \"Catalog Style Guide\" section of the guide for details\
+ \ and # TAGLINE\nsemantics of what should be included in specific entity fields.\
+ \ # TAGLINE\nSpecifically, the # TAGLINE\n[Fileset Entity Reference](https://guide.fatcat.wiki/entity_fileset.html).\
+ \ # TAGLINE\n"
+ x-displayName: "Filesets"
- name: "webcaptures"
+ description: "**Web Capture** entities represent archival snapshots of web pages\
+ \ (or # TAGLINE\nother web resources), which are usually complete manifestations\
+ \ of a # TAGLINE\nspecific release entity. Web Captures also include a set of\
+ \ locations # TAGLINE\n(wayback replay instances or WARC files) where the capture\
+ \ can be found. # TAGLINE\n\nSee the \"Catalog Style Guide\" section of the guide\
+ \ for details and # TAGLINE\nsemantics of what should be included in specific\
+ \ entity fields. # TAGLINE\nSpecifically, the # TAGLINE\n[Web Capture Entity\
+ \ Reference](https://guide.fatcat.wiki/entity_webcapture.html). # TAGLINE\n"
+ x-displayName: "Webcaptures"
- name: "releases"
+ description: "**Release** entities represent specific published versions of a research\
+ \ # TAGLINE\nwork, such as a pre-print, a journal article, a book (or chapter),\
+ \ or a # TAGLINE\nscholarly blog post. Releases are always grouped together under\
+ \ Works; # TAGLINE\nthey may be published in a specific Container; they may have\
+ \ known # TAGLINE\nCreators; and there may exist known File/Fileset/WebCapture\
+ \ digital copies # TAGLINE\nof the release. # TAGLINE\n\nSee the \"Catalog Style\
+ \ Guide\" section of the guide for details and # TAGLINE\nsemantics of what should\
+ \ be included in specific entity fields. # TAGLINE\nSpecifically, the # TAGLINE\n\
+ [Release Entity Reference](https://guide.fatcat.wiki/entity_release.html). #\
+ \ TAGLINE\n"
+ x-displayName: "Releases"
- name: "works"
-- name: "edit-lifecycle"
+ description: "**Work** entities group several Release entities which are different\
+ \ # TAGLINE\nversions of the same abstract piece of research. For example, three\
+ \ # TAGLINE\nrelease entities representing the pre-print, published article,\
+ \ and # TAGLINE\nretraction stages of the same journal paper would be grouped\
+ \ under a # TAGLINE\nsingle work. # TAGLINE\n\nSee the \"Catalog Style Guide\"\
+ \ section of the guide for details and # TAGLINE\nsemantics of what should be\
+ \ included in specific entity fields. # TAGLINE\nSpecifically, the # TAGLINE\n\
+ [Work Entity Reference](https://guide.fatcat.wiki/entity_work.html). # TAGLINE\n"
+ x-displayName: "Works"
+- name: "editgroups"
+ description: "**Editgroups** are sets of changes, each to individual entities in\
+ \ the # TAGLINE\ncatalog. Every edit must be part of an editgroup which is reviewed\
+ \ and # TAGLINE\naccepted (merged) as a whole. # TAGLINE\n"
+ x-displayName: "Editgroups"
+- name: "editors"
+ description: "**Editors** are human user accounts and bots that make changes to\
+ \ the # TAGLINE\nFatcat catalog. # TAGLINE\n\nThe API allows fetching (and updating)\
+ \ metadata about individual editors, # TAGLINE\nas well as fetching editor's\
+ \ annotation and edit history. # TAGLINE\n"
+ x-displayName: "Editors"
+- name: "changelog"
+ description: "The **Changelog** is the ordered feed of editgroups which have been\
+ \ # TAGLINE\naccepted into the catalog. # TAGLINE\n"
+ x-displayName: "Changelog"
+- name: "auth"
+ description: "Helper methods and internal APIs for editor authentication. # TAGLINE\n"
+ x-displayName: "Auth Methods"
schemes:
- "https"
consumes:
@@ -27,6 +152,9 @@ paths:
post:
tags:
- "containers"
+ description: "Create a single Container entity as part of an existing editgroup.\n\
+ \nEditgroup must be mutable (aka, not accepted) and editor must have\npermission\
+ \ (aka, have created the editgrou p or have `admin` role).\n"
operationId: "create_container"
parameters:
- name: "editgroup_id"
@@ -117,6 +245,12 @@ paths:
post:
tags:
- "containers"
+ description: "Create a set of Container entities as part of a new editgroup,\
+ \ and\naccept that editgroup in the same atomic request.\n\nThis method is\
+ \ mostly useful for bulk import of new entities by\ncarefully written bots.\
+ \ This method is more efficient than creating an\neditgroup, several entities,\
+ \ then accepting the editgroup, both in\nterms of API requests required and\
+ \ database load. Requires `admin`\nrole.\n"
operationId: "create_container_auto_batch"
parameters:
- in: "body"
@@ -201,6 +335,7 @@ paths:
get:
tags:
- "containers"
+ description: "Fetches a single container entity from the catalog.\n"
operationId: "get_container"
parameters:
- name: "ident"
@@ -271,6 +406,13 @@ paths:
put:
tags:
- "containers"
+ description: "Updates an existing entity as part of a specific (existing) editgroup.\n\
+ The editgroup must be open for updates (aka, not accepted/merged), and\nthe\
+ \ editor making the requiest must have permissions (aka, must have\ncreated\
+ \ the editgroup or have `admin` role).\n\nThis method can also be used to\
+ \ update an existing entity edit as part\nof an editgroup. For example, if\
+ \ an entity was created in this\neditgroup, an editor could make changes to\
+ \ the new entity's metadata\nbefore merging.\n"
operationId: "update_container"
parameters:
- name: "editgroup_id"
@@ -366,6 +508,9 @@ paths:
delete:
tags:
- "containers"
+ description: "Creates a new \"deletion\" edit for a specific entity as part\
+ \ of an\nexisting editgroup.\n\nThis is not the method to use to remove an\
+ \ edit from an editgroup; for\nthat use `delete_container_edit`.\n"
operationId: "delete_container"
parameters:
- name: "editgroup_id"
@@ -449,6 +594,11 @@ paths:
get:
tags:
- "containers"
+ description: "Fetches a specific entity revision. Note that the returned revision\n\
+ will not be associated with any particular fatcat identifier (even if\none\
+ \ or more identifiers do currently point to this revision). The\nrevision\
+ \ may even be part of an un-merged editgroup.\n\nRevisions are immutable and\
+ \ can not be deleted or updated.\n"
operationId: "get_container_revision"
parameters:
- name: "rev_id"
@@ -463,16 +613,14 @@ paths:
example: "\"rev_id_example\".to_string()"
- name: "expand"
in: "query"
- 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`."
required: false
type: "string"
formatString: "{:?}"
example: "Some(\"expand_example\".to_string())"
- name: "hide"
in: "query"
- 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`."
required: false
type: "string"
formatString: "{:?}"
@@ -523,6 +671,8 @@ paths:
get:
tags:
- "containers"
+ description: "Fetches the history of accepted edits (changelog entries) for\
+ \ a\nspecific entity fatcat identifier.\n"
operationId: "get_container_history"
parameters:
- name: "ident"
@@ -533,6 +683,7 @@ paths:
example: "\"ident_example\".to_string()"
- name: "limit"
in: "query"
+ description: "Maximum number of changelog entries to return"
required: false
type: "integer"
format: "int64"
@@ -586,6 +737,8 @@ paths:
get:
tags:
- "containers"
+ description: "Returns the set of entity identifiers which currently redirect\
+ \ to this\nidentifier.\n"
operationId: "get_container_redirects"
parameters:
- name: "ident"
@@ -601,7 +754,6 @@ paths:
type: "array"
items:
type: "string"
- example: "q3nouwy3nnbsvo3h5klxsx4a7y"
description: "base32-encoded unique identifier"
minLength: 26
maxLength: 26
@@ -647,6 +799,11 @@ paths:
get:
tags:
- "containers"
+ description: "Looks for an active entity with the given external identifier.\
+ \ If any\nsuch entity is found, returns a single complete entity. If multiple\n\
+ entities have the same external identifier, this is considered a soft\ncatalog\
+ \ error, and the behavior of which entity is returned is\nundefined.\n\nOne\
+ \ (and only one) external identifier should be specified per request.\n"
operationId: "lookup_container"
parameters:
- name: "issnl"
@@ -661,19 +818,19 @@ paths:
- name: "wikidata_qid"
in: "query"
required: false
+ type: "string"
formatString: "{:?}"
example: "Some(\"wikidata_qid_example\".to_string())"
- name: "expand"
in: "query"
- description: "List of sub-entities to expand in response."
+ description: "List of sub-entities to expand in response. See `get_container`."
required: false
type: "string"
formatString: "{:?}"
example: "Some(\"expand_example\".to_string())"
- name: "hide"
in: "query"
- 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`."
required: false
type: "string"
formatString: "{:?}"
@@ -724,6 +881,8 @@ paths:
get:
tags:
- "containers"
+ description: "Returns the entity edit object with the given identifier. This\
+ \ method\nis expected to be used rarely.\n"
operationId: "get_container_edit"
parameters:
- name: "edit_id"
@@ -782,6 +941,11 @@ paths:
delete:
tags:
- "containers"
+ description: "Removes a single edit from the specified editgroup. The editgroup\
+ \ must\nbe mutable (aka, not accepted/merged), and the editor making this\n\
+ request must have permission (aka, have created the editgroup or hold\nthe\
+ \ `admin` role).\n\nNot to be confused with the `delete_container` method,\
+ \ which *creates*\na new edit in the given editgroup.\n"
operationId: "delete_container_edit"
parameters:
- name: "editgroup_id"
@@ -1061,8 +1225,8 @@ paths:
example: "Some(\"expand_example\".to_string())"
- name: "hide"
in: "query"
- 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)."
required: false
type: "string"
formatString: "{:?}"
@@ -1305,16 +1469,16 @@ paths:
example: "\"rev_id_example\".to_string()"
- name: "expand"
in: "query"
- 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`,\n\
+ though note that identifier-based expansions (like `releases`) will\nalways\
+ \ be empty for revisions.\n"
required: false
type: "string"
formatString: "{:?}"
example: "Some(\"expand_example\".to_string())"
- name: "hide"
in: "query"
- 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`."
required: false
type: "string"
formatString: "{:?}"
@@ -1428,6 +1592,8 @@ paths:
get:
tags:
- "creators"
+ description: "Returns the set of Release entities having a `contrib` entry pointing\n\
+ to the creator entity.\n"
operationId: "get_creator_releases"
parameters:
- name: "ident"
@@ -1438,8 +1604,7 @@ paths:
example: "\"ident_example\".to_string()"
- name: "hide"
in: "query"
- 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`."
required: false
type: "string"
formatString: "{:?}"
@@ -1507,7 +1672,6 @@ paths:
type: "array"
items:
type: "string"
- example: "q3nouwy3nnbsvo3h5klxsx4a7y"
description: "base32-encoded unique identifier"
minLength: 26
maxLength: 26
@@ -1557,6 +1721,7 @@ paths:
parameters:
- name: "orcid"
in: "query"
+ description: "ORCiD (https://orcid.org) identifier"
required: false
type: "string"
maxLength: 19
@@ -1567,19 +1732,19 @@ paths:
- name: "wikidata_qid"
in: "query"
required: false
+ type: "string"
formatString: "{:?}"
example: "Some(\"wikidata_qid_example\".to_string())"
- name: "expand"
in: "query"
- description: "List of sub-entities to expand in response."
+ description: "List of sub-entities to expand in response. See `get_creator`."
required: false
type: "string"
formatString: "{:?}"
example: "Some(\"expand_example\".to_string())"
- name: "hide"
in: "query"
- 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`."
required: false
type: "string"
formatString: "{:?}"
@@ -2211,16 +2376,14 @@ paths:
example: "\"rev_id_example\".to_string()"
- name: "expand"
in: "query"
- 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`."
required: false
type: "string"
formatString: "{:?}"
example: "Some(\"expand_example\".to_string())"
- name: "hide"
in: "query"
- 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`."
required: false
type: "string"
formatString: "{:?}"
@@ -2349,7 +2512,6 @@ paths:
type: "array"
items:
type: "string"
- example: "q3nouwy3nnbsvo3h5klxsx4a7y"
description: "base32-encoded unique identifier"
minLength: 26
maxLength: 26
@@ -2399,6 +2561,7 @@ paths:
parameters:
- name: "md5"
in: "query"
+ description: "MD5 hash of data, in hex encoding"
required: false
type: "string"
maxLength: 32
@@ -2408,6 +2571,7 @@ paths:
example: "Some(\"md5_example\".to_string())"
- name: "sha1"
in: "query"
+ description: "SHA-1 hash of data, in hex encoding"
required: false
type: "string"
maxLength: 40
@@ -2417,6 +2581,7 @@ paths:
example: "Some(\"sha1_example\".to_string())"
- name: "sha256"
in: "query"
+ description: "SHA-256 hash of data, in hex encoding"
required: false
type: "string"
maxLength: 64
@@ -2426,15 +2591,14 @@ paths:
example: "Some(\"sha256_example\".to_string())"
- name: "expand"
in: "query"
- description: "List of sub-entities to expand in response."
+ description: "List of sub-entities to expand in response. See `get_file`."
required: false
type: "string"
formatString: "{:?}"
example: "Some(\"expand_example\".to_string())"
- name: "hide"
in: "query"
- 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`."
required: false
type: "string"
formatString: "{:?}"
@@ -3066,16 +3230,14 @@ paths:
example: "\"rev_id_example\".to_string()"
- name: "expand"
in: "query"
- 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`."
required: false
type: "string"
formatString: "{:?}"
example: "Some(\"expand_example\".to_string())"
- name: "hide"
in: "query"
- 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`."
required: false
type: "string"
formatString: "{:?}"
@@ -3204,7 +3366,6 @@ paths:
type: "array"
items:
type: "string"
- example: "q3nouwy3nnbsvo3h5klxsx4a7y"
description: "base32-encoded unique identifier"
minLength: 26
maxLength: 26
@@ -3831,16 +3992,14 @@ paths:
example: "\"rev_id_example\".to_string()"
- name: "expand"
in: "query"
- 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`."
required: false
type: "string"
formatString: "{:?}"
example: "Some(\"expand_example\".to_string())"
- name: "hide"
in: "query"
- 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`."
required: false
type: "string"
formatString: "{:?}"
@@ -3969,7 +4128,6 @@ paths:
type: "array"
items:
type: "string"
- example: "q3nouwy3nnbsvo3h5klxsx4a7y"
description: "base32-encoded unique identifier"
minLength: 26
maxLength: 26
@@ -4160,6 +4318,11 @@ paths:
post:
tags:
- "releases"
+ description: "Create a single Release entity as part of an existing editgroup.\
+ \ If the\n`work_id` field is not set, a work entity will be created automatically\n\
+ and this field set pointing to the new work.\n\nEditgroup must be mutable\
+ \ (aka, not accepted) and editor must have\npermission (aka, have created\
+ \ the editgrou p or have `admin` role).\n"
operationId: "create_release"
parameters:
- name: "editgroup_id"
@@ -4250,6 +4413,12 @@ paths:
post:
tags:
- "releases"
+ description: "Create a set of Release entities as part of a new editgroup, and\n\
+ accept that editgroup in the same atomic request.\n\nThis method is mostly\
+ \ useful for bulk import of new entities by\ncarefully written bots. This\
+ \ method is more efficient than creating an\neditgroup, several entities,\
+ \ then accepting the editgroup, both in\nterms of API requests required and\
+ \ database load. Requires `admin`\nrole.\n"
operationId: "create_release_auto_batch"
parameters:
- in: "body"
@@ -4334,6 +4503,7 @@ paths:
get:
tags:
- "releases"
+ description: "Fetches a single Release entity from the catalog.\n"
operationId: "get_release"
parameters:
- name: "ident"
@@ -4344,16 +4514,16 @@ paths:
example: "\"ident_example\".to_string()"
- name: "expand"
in: "query"
- 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',\n\
+ 'filesets, 'webcaptures', 'container', and 'creators' are valid.\n"
required: false
type: "string"
formatString: "{:?}"
example: "Some(\"expand_example\".to_string())"
- name: "hide"
in: "query"
- 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\nreleases, 'abstracts', 'refs', and 'contribs' are valid.\n"
required: false
type: "string"
formatString: "{:?}"
@@ -4404,6 +4574,13 @@ paths:
put:
tags:
- "releases"
+ description: "Updates an existing entity as part of a specific (existing) editgroup.\n\
+ The editgroup must be open for updates (aka, not accepted/merged), and\nthe\
+ \ editor making the requiest must have permissions (aka, must have\ncreated\
+ \ the editgroup or have `admin` role).\n\nThis method can also be used to\
+ \ update an existing entity edit as part\nof an editgroup. For example, if\
+ \ an entity was created in this\neditgroup, an editor could make changes to\
+ \ the new entity's metadata\nbefore merging.\n"
operationId: "update_release"
parameters:
- name: "editgroup_id"
@@ -4499,6 +4676,9 @@ paths:
delete:
tags:
- "releases"
+ description: "Creates a new \"deletion\" edit for a specific entity as part\
+ \ of an\nexisting editgroup.\n\nThis is not the method to use to remove an\
+ \ edit from an editgroup; for\nthat use `delete_release_edit`.\n"
operationId: "delete_release"
parameters:
- name: "editgroup_id"
@@ -4582,6 +4762,11 @@ paths:
get:
tags:
- "releases"
+ description: "Fetches a specific entity revision. Note that the returned revision\n\
+ will not be associated with any particular fatcat identifier (even if\none\
+ \ or more identifiers do currently point to this revision). The\nrevision\
+ \ may even be part of an un-merged editgroup.\n\nRevisions are immutable and\
+ \ can not be deleted or updated.\n"
operationId: "get_release_revision"
parameters:
- name: "rev_id"
@@ -4596,16 +4781,16 @@ paths:
example: "\"rev_id_example\".to_string()"
- name: "expand"
in: "query"
- 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."
required: false
type: "string"
formatString: "{:?}"
example: "Some(\"expand_example\".to_string())"
- name: "hide"
in: "query"
- 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`."
required: false
type: "string"
formatString: "{:?}"
@@ -4656,6 +4841,8 @@ paths:
get:
tags:
- "releases"
+ description: "Fetches the history of accepted edits (changelog entries) for\
+ \ a\nspecific entity fatcat identifier.\n"
operationId: "get_release_history"
parameters:
- name: "ident"
@@ -4719,6 +4906,8 @@ paths:
get:
tags:
- "releases"
+ description: "Returns the set of File entities that have a `release_id` pointing\
+ \ to\nthis release entity.\n"
operationId: "get_release_files"
parameters:
- name: "ident"
@@ -4729,8 +4918,7 @@ paths:
example: "\"ident_example\".to_string()"
- name: "hide"
in: "query"
- 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`."
required: false
type: "string"
formatString: "{:?}"
@@ -4783,6 +4971,8 @@ paths:
get:
tags:
- "releases"
+ description: "Returns the set of Fileset entities that have a `release_id` pointing\
+ \ to\nthis release entity.\n"
operationId: "get_release_filesets"
parameters:
- name: "ident"
@@ -4793,8 +4983,7 @@ paths:
example: "\"ident_example\".to_string()"
- name: "hide"
in: "query"
- 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`."
required: false
type: "string"
formatString: "{:?}"
@@ -4847,6 +5036,8 @@ paths:
get:
tags:
- "releases"
+ description: "Returns the set of Web Capture entities that have a `release_id`\n\
+ pointing to this release entity.\n"
operationId: "get_release_webcaptures"
parameters:
- name: "ident"
@@ -4857,8 +5048,7 @@ paths:
example: "\"ident_example\".to_string()"
- name: "hide"
in: "query"
- 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`."
required: false
type: "string"
formatString: "{:?}"
@@ -4911,6 +5101,8 @@ paths:
get:
tags:
- "releases"
+ description: "Returns the set of entity identifiers which currently redirect\
+ \ to this\nidentifier.\n"
operationId: "get_release_redirects"
parameters:
- name: "ident"
@@ -4926,7 +5118,6 @@ paths:
type: "array"
items:
type: "string"
- example: "q3nouwy3nnbsvo3h5klxsx4a7y"
description: "base32-encoded unique identifier"
minLength: 26
maxLength: 26
@@ -4972,6 +5163,11 @@ paths:
get:
tags:
- "releases"
+ description: "Looks for an active entity with the given external identifier.\
+ \ If any\nsuch entity is found, returns a single complete entity. If multiple\n\
+ entities have the same external identifier, this is considered a soft\ncatalog\
+ \ error, and the behavior of which entity is returned is\nundefined.\n\nOne\
+ \ (and only one) external identifier should be specified per request.\n"
operationId: "lookup_release"
parameters:
- name: "doi"
@@ -5036,15 +5232,14 @@ paths:
example: "Some(\"mag_example\".to_string())"
- name: "expand"
in: "query"
- description: "List of sub-entities to expand in response."
+ description: "List of sub-entities to expand in response. See `get_release`."
required: false
type: "string"
formatString: "{:?}"
example: "Some(\"expand_example\".to_string())"
- name: "hide"
in: "query"
- 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`."
required: false
type: "string"
formatString: "{:?}"
@@ -5095,6 +5290,8 @@ paths:
get:
tags:
- "releases"
+ description: "Returns the entity edit object with the given identifier. This\
+ \ method\nis expected to be used rarely.\n"
operationId: "get_release_edit"
parameters:
- name: "edit_id"
@@ -5153,6 +5350,11 @@ paths:
delete:
tags:
- "releases"
+ description: "Removes a single edit from the specified editgroup. The editgroup\
+ \ must\nbe mutable (aka, not accepted/merged), and the editor making this\n\
+ request must have permission (aka, have created the editgroup or hold\nthe\
+ \ `admin` role).\n\nNot to be confused with the `delete_container` method,\
+ \ which *creates*\na new edit in the given editgroup.\n"
operationId: "delete_release_edit"
parameters:
- name: "editgroup_id"
@@ -5239,7 +5441,7 @@ paths:
/editgroup/{editgroup_id}/work:
post:
tags:
- - "releases"
+ - "works"
operationId: "create_work"
parameters:
- name: "editgroup_id"
@@ -5676,16 +5878,16 @@ paths:
example: "\"rev_id_example\".to_string()"
- name: "expand"
in: "query"
- 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."
required: false
type: "string"
formatString: "{:?}"
example: "Some(\"expand_example\".to_string())"
- name: "hide"
in: "query"
- 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`."
required: false
type: "string"
formatString: "{:?}"
@@ -5814,7 +6016,6 @@ paths:
type: "array"
items:
type: "string"
- example: "q3nouwy3nnbsvo3h5klxsx4a7y"
description: "base32-encoded unique identifier"
minLength: 26
maxLength: 26
@@ -5860,6 +6061,8 @@ paths:
get:
tags:
- "works"
+ description: "Returns the set of release entities that are part of this work\
+ \ (aka,\nhave `work_id` pointing to this work entity).\n"
operationId: "get_work_releases"
parameters:
- name: "ident"
@@ -5870,8 +6073,7 @@ paths:
example: "\"ident_example\".to_string()"
- name: "hide"
in: "query"
- 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`."
required: false
type: "string"
formatString: "{:?}"
@@ -6067,6 +6269,10 @@ paths:
httpmethod: "delete"
/editor/{editor_id}:
get:
+ tags:
+ - "editors"
+ description: "Returns an editor object, including metadata such as the username,\n\
+ type, and role of editor.\n"
operationId: "get_editor"
parameters:
- name: "editor_id"
@@ -6118,6 +6324,12 @@ paths:
HttpMethod: "Get"
httpmethod: "get"
put:
+ tags:
+ - "editors"
+ description: "Allows metadata changes to some editor fields, such as the username.\n\
+ \nChanges require authentication and permissions. An editor can change\ntheir\
+ \ own username; changes to role flags require the `admin` role by\nthe editor\
+ \ making the request.\n"
operationId: "update_editor"
parameters:
- name: "editor_id"
@@ -6206,6 +6418,10 @@ paths:
noClientExample: true
/editor/{editor_id}/editgroups:
get:
+ tags:
+ - "editors"
+ description: "Returns a set of editgroups created by the given editor, regardless\
+ \ of\nthe status (accepted/submitted) of the editgroups.\n"
operationId: "get_editor_editgroups"
parameters:
- name: "editor_id"
@@ -6223,6 +6439,9 @@ paths:
example: "Some(789)"
- name: "before"
in: "query"
+ description: "Return only editgroups created *before* the given timestamp\
+ \ (not\ninclusive). Editgroups will be sorted by creation time in\ndescending\
+ \ order (most recent first). For use in pagination.\n"
required: false
type: "string"
format: "date-time"
@@ -6230,6 +6449,9 @@ paths:
example: "None"
- name: "since"
in: "query"
+ description: "Return only editgroups created *after* the given timestamp (not\n\
+ inclusive). Editgroups will be sorted by creation time in ascending\norder\
+ \ (most recent last). For use in pagination.\n"
required: false
type: "string"
format: "date-time"
@@ -6282,7 +6504,8 @@ paths:
/editor/{editor_id}/annotations:
get:
tags:
- - "edit-lifecycle"
+ - "editors"
+ description: "Fetches a list of annotations made by a particular editor.\n"
operationId: "get_editor_annotations"
parameters:
- name: "editor_id"
@@ -6297,6 +6520,7 @@ paths:
example: "\"editor_id_example\".to_string()"
- name: "limit"
in: "query"
+ description: "Maximum number (count) of annotations to return in response"
required: false
type: "integer"
format: "int64"
@@ -6304,6 +6528,9 @@ paths:
example: "Some(789)"
- name: "before"
in: "query"
+ description: "Return only annotations made *before* the given timestamp (not\n\
+ inclusive). Annotations will be sorted by creation time in\ndescending order\
+ \ (most recent first). For use in pagination.\n"
required: false
type: "string"
format: "date-time"
@@ -6311,6 +6538,9 @@ paths:
example: "None"
- name: "since"
in: "query"
+ description: "Return only annotations made *after* the given timestamp (not\n\
+ inclusive). Annotations will be sorted by creation time in\nascending order\
+ \ (most recent last). For use in pagination.\n"
required: false
type: "string"
format: "date-time"
@@ -6384,7 +6614,9 @@ paths:
/editgroup:
post:
tags:
- - "edit-lifecycle"
+ - "editgroups"
+ description: "Creates a new editgroup. By default the editor making this request\
+ \ will\nbe the author of the editgroup.\n"
operationId: "create_editgroup"
parameters:
- in: "body"
@@ -6468,7 +6700,11 @@ paths:
/editgroup/{editgroup_id}:
get:
tags:
- - "edit-lifecycle"
+ - "editgroups"
+ description: "Returns a single editgroup object.\n\nUnlike some similar methods,\
+ \ this method will return a full/expanded\neditgroup object, which includes\
+ \ edit lists of each entity type (though\nwill not include the complete entity\
+ \ objects).\n"
operationId: "get_editgroup"
parameters:
- name: "editgroup_id"
@@ -6524,6 +6760,12 @@ paths:
HttpMethod: "Get"
httpmethod: "get"
put:
+ tags:
+ - "editgroups"
+ description: "Updates metadata for a single editgroup object. Note that only\
+ \ metadata\nfields such as the `description` or `extra` metadata can be changed\n\
+ with this method; it does not allow adding or removing edits to the\neditgroup\
+ \ (for that use the individual entity create/update/delete\nmethods).\n"
operationId: "update_editgroup"
parameters:
- name: "editgroup_id"
@@ -6623,7 +6865,10 @@ paths:
/editgroup/{editgroup_id}/accept:
post:
tags:
- - "edit-lifecycle"
+ - "editgroups"
+ description: "Accept (\"merge\") the given editgroup into the catalog. The editgroup\n\
+ must be open (not already accepted), and the editor making this request\n\
+ must have the `admin` role.\n"
operationId: "accept_editgroup"
parameters:
- name: "editgroup_id"
@@ -6713,7 +6958,8 @@ paths:
/editgroup/{editgroup_id}/annotations:
get:
tags:
- - "edit-lifecycle"
+ - "editgroups"
+ description: "Returns a list of annotations made to a specific editgroup."
operationId: "get_editgroup_annotations"
parameters:
- name: "editgroup_id"
@@ -6728,7 +6974,7 @@ paths:
example: "\"editgroup_id_example\".to_string()"
- name: "expand"
in: "query"
- description: "List of sub-entities to expand in response. For editgroups:\
+ description: "List of sub-entities to expand in response. For editgroup annotations:\
\ 'editors'"
required: false
type: "string"
@@ -6802,7 +7048,10 @@ paths:
/editgroup/{editgroup_id}/annotation:
post:
tags:
- - "edit-lifecycle"
+ - "editgroups"
+ description: "Submits a new annotation to the specified editgroup.\n\nThe editgroup\
+ \ must be open (not already accepted). The annotation will\nautomatically\
+ \ have authorship of the editor making this request.\n"
operationId: "create_editgroup_annotation"
parameters:
- name: "editgroup_id"
@@ -6895,6 +7144,11 @@ paths:
noClientExample: true
/editgroup/reviewable:
get:
+ tags:
+ - "editgroups"
+ description: "Returns a set of editgroups which have been submitted but not\
+ \ yet accepted.\n\nQuery parameters can be used to sort and paginate the list\
+ \ returned.\n"
operationId: "get_editgroups_reviewable"
parameters:
- name: "expand"
@@ -6907,6 +7161,7 @@ paths:
example: "Some(\"expand_example\".to_string())"
- name: "limit"
in: "query"
+ description: "Maximum number of reviewable editgroups to return in response"
required: false
type: "integer"
format: "int64"
@@ -6914,6 +7169,9 @@ paths:
example: "Some(789)"
- name: "before"
in: "query"
+ description: "Return only reviewable editgroups submitted *before* the given\n\
+ timestamp (not inclusive). Editgroups will be sorted by submission\ntime\
+ \ in descending order (most recent first). For use in pagination.\n"
required: false
type: "string"
format: "date-time"
@@ -6921,6 +7179,9 @@ paths:
example: "None"
- name: "since"
in: "query"
+ description: "Return only reviewable editgroups submitted *after* the given\n\
+ timestamp (not inclusive). Editgroups will be sorted by submission\ntime\
+ \ in ascending order (most recent last). For use in pagination.\n"
required: false
type: "string"
format: "date-time"
@@ -6973,11 +7234,22 @@ paths:
/changelog:
get:
tags:
- - "edit-lifecycle"
+ - "changelog"
+ description: "Returns a list of the most recent changelog entries accepted (merged)\n\
+ into the catalog.\n\nList is sorted by changelog index in descending order.\
+ \ Note that the\naccepted timestamp roughly corresponds to order, but not\
+ \ strictly;\nthere exist out-of-order timestamps on the order of several seconds.\n\
+ \nAs a known database issue, it is technically possible for there to be a\n\
+ gap in changelog index numbers (aka, a missing changelog entry). There\nare\
+ \ no currently known gaps and this is considered a bug that will be\naddressed.\n\
+ \nThere are millions of entries; to paginate through all of them, use\nthis\
+ \ method to discover the highest existing entry number, then request\nthe\
+ \ entries using `get_changelog_entry` one at a time.\n"
operationId: "get_changelog"
parameters:
- name: "limit"
in: "query"
+ description: "Maximum count of changelog entries to return in response"
required: false
type: "integer"
format: "int64"
@@ -7021,11 +7293,16 @@ paths:
/changelog/{index}:
get:
tags:
- - "edit-lifecycle"
+ - "changelog"
+ description: "Returns a single changelog entry.\n\nAs a known database issue,\
+ \ it is technically possible for there to be a\ngap in changelog index numbers\
+ \ (aka, a missing changelog entry). There\nare no currently known gaps and\
+ \ this is considered a bug that will be\naddressed.\n"
operationId: "get_changelog_entry"
parameters:
- name: "index"
in: "path"
+ description: "Changelog index of entry to return"
required: true
type: "integer"
format: "int64"
@@ -7075,6 +7352,15 @@ paths:
httpmethod: "get"
/auth/oidc:
post:
+ tags:
+ - "auth"
+ description: "Login or create editor account using OIDC metadata (internal method).\n\
+ \nThis method is used by privileged front-end tools (like the web\ninterface\
+ \ service) to process editor logins using OpenID Connect (OIDC)\nand/or OAuth.\
+ \ Most accounts (including tool and bot accounts) do not\nhave sufficient\
+ \ privileges to call this method, which requires the\n`admin` role.\n\nThe\
+ \ method returns an API token; the HTTP status code indicates whether\nan\
+ \ existing account was logged in, or a new account was created.\n"
operationId: "auth_oidc"
parameters:
- in: "body"
@@ -7166,6 +7452,11 @@ paths:
noClientExample: true
/auth/check:
get:
+ tags:
+ - "auth"
+ description: "Verify that authentication (API token) is working as expected.\
+ \ The\noptional `role` parameter can be used to verify that the current\n\
+ account (editor) has permissions for the given role.\n"
operationId: "auth_check"
parameters:
- name: "role"
@@ -7232,6 +7523,18 @@ paths:
httpmethod: "get"
securityDefinitions:
Bearer:
+ description: "The only current API authentication mechanism is HTTP bearer\nauthentication\
+ \ using the `Authorization` HTTP header. The header should\nbe formatted as\
+ \ the string \"Bearer\", then a space, then API token (in the\nusual base64\
+ \ string encoding).\n\nAn example HTTP request would look on the wire like:\n\
+ \n GET /v0/auth/check HTTP/1.1\n Accept: */*\n Accept-Encoding: gzip,\
+ \ deflate\n Authorization: Bearer AgEPZGV2LmZhdGNhdC53aWtpAhYyMDE5MDEwMS1kZXYtZHVtbXkta2V5AAImZWRpdG9yX2lkID0gYWFhYWFhYWFhYWFhYmt2a2FhYWFhYWFhYWkAAht0aW1lID4gMjAxOS0wMS0wOVQwMDo1Nzo1MloAAAYgnroNha1hSftChtxHGTnLEmM/pY8MeQS/jBSV0UNvXug=\n\
+ \ Connection: keep-alive\n Host: api.qa.fatcat.wiki\n User-Agent: HTTPie/0.9.8\n\
+ \nHeaders can be passed on the command line using `http` (HTTPie) like:\n\n\
+ \ http get https://api.qa.fatcat.wiki/v0/auth/check Authorization:\"Bearer\
+ \ AgEPZGV2LmZhdGNhdC53aWtpAhYyMDE5MDEwMS1kZXYtZHVtbXkta2V5AAImZWRpdG9yX2lkID0gYWFhYWFhYWFhYWFhYmt2a2FhYWFhYWFhYWkAAht0aW1lID4gMjAxOS0wMS0wOVQwMDo1Nzo1MloAAAYgnroNha1hSftChtxHGTnLEmM/pY8MeQS/jBSV0UNvXug=\"\
+ \n\nOr with `curl`:\n\n curl -H \"Authorization: Bearer AgEPZGV2LmZhdGNhdC53aWtpAhYyMDE5MDEwMS1kZXYtZHVtbXkta2V5AAImZWRpdG9yX2lkID0gYWFhYWFhYWFhYWFhYmt2a2FhYWFhYWFhYWkAAht0aW1lID4gMjAxOS0wMS0wOVQwMDo1Nzo1MloAAAYgnroNha1hSftChtxHGTnLEmM/pY8MeQS/jBSV0UNvXug=\"\
+ \ https://qa.fatcat.wiki/v0/auth/check\n"
type: "apiKey"
name: "Authorization"
in: "header"
@@ -7245,8 +7548,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"
@@ -7259,6 +7564,7 @@ definitions:
properties:
success:
type: "boolean"
+ example: true
message:
type: "string"
example: "The computers did the thing successfully!"
@@ -7271,26 +7577,38 @@ definitions:
properties:
wikidata_qid:
type: "string"
+ example: "Q42812"
issnl:
type: "string"
example: "1234-5678"
+ description: "Linking ISSN number (ISSN-L). Should be valid and registered\
+ \ with issn.org"
minLength: 9
maxLength: 9
pattern: "\\d{4}-\\d{3}[0-9X]"
publisher:
type: "string"
example: "Society of Curious Students"
+ description: "Name of the organization or entity responsible for publication.\
+ \ Not\nthe complete imprint/brand.\n"
container_type:
type: "string"
- description: "Eg, 'journal'"
+ example: "journal"
+ description: "Type of container, eg 'journal' or 'proceedings'. See Guide\
+ \ for list of valid types."
name:
type: "string"
example: "Journal of Important Results"
- description: "Required for valid entities"
+ description: "Name of the container (eg, Journal title). Required for entity\
+ \ creation."
edit_extra:
type: "object"
+ description: "Free-form JSON metadata that will be stored with specific entity\
+ \ edits\n(eg, creation/update/delete).\n"
extra:
type: "object"
+ description: "Free-form JSON metadata that will be stored with the other entity\n\
+ metadata. See guide for (unenforced) schema conventions.\n"
redirect:
type: "string"
example: "q3nouwy3nnbsvo3h5klxsx4a7y"
@@ -7314,6 +7632,7 @@ definitions:
pattern: "[a-zA-Z2-7]{26}"
state:
type: "string"
+ example: "active"
enum:
- "wip"
- "active"
@@ -7323,12 +7642,12 @@ definitions:
redirect: "q3nouwy3nnbsvo3h5klxsx4a7y"
ident: "q3nouwy3nnbsvo3h5klxsx4a7y"
extra: "{}"
- container_type: "container_type"
+ container_type: "journal"
name: "Journal of Important Results"
publisher: "Society of Curious Students"
issnl: "1234-5678"
- wikidata_qid: "wikidata_qid"
- state: "wip"
+ wikidata_qid: "Q42812"
+ state: "active"
edit_extra: "{}"
revision: "86daea5b-1b6b-432a-bb67-ea97795f80fe"
upperCaseName: "CONTAINER_ENTITY"
@@ -7337,22 +7656,31 @@ definitions:
properties:
wikidata_qid:
type: "string"
+ example: "Q42812"
+ description: "Wikidata entity QID"
orcid:
type: "string"
example: "0000-0002-1825-0097"
+ description: "ORCiD (https://orcid.org) identifier"
minLength: 19
maxLength: 19
pattern: "\\d{4}-\\d{4}-\\d{4}-\\d{3}[\\dX]"
surname:
type: "string"
+ description: "In English commonly the last, or family name, but ordering is\
+ \ context\nand culture specific.\n"
given_name:
type: "string"
+ description: "In English commonly the first name, but ordering is context\
+ \ and\nculture specific.\n"
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\nindex/sorted). Required for valid entities.\n"
state:
type: "string"
+ example: "active"
enum:
- "wip"
- "active"
@@ -7381,16 +7709,20 @@ definitions:
pattern: "[a-zA-Z2-7]{26}"
extra:
type: "object"
+ description: "Free-form JSON metadata that will be stored with the other entity\n\
+ metadata. See guide for (unenforced) schema conventions.\n"
edit_extra:
type: "object"
+ description: "Free-form JSON metadata that will be stored with specific entity\
+ \ edits\n(eg, creation/update/delete).\n"
example:
redirect: "q3nouwy3nnbsvo3h5klxsx4a7y"
surname: "surname"
ident: "q3nouwy3nnbsvo3h5klxsx4a7y"
extra: "{}"
orcid: "0000-0002-1825-0097"
- wikidata_qid: "wikidata_qid"
- state: "wip"
+ wikidata_qid: "Q42812"
+ state: "active"
given_name: "given_name"
display_name: "Grace Hopper"
edit_extra: "{}"
@@ -7401,11 +7733,15 @@ definitions:
properties:
releases:
type: "array"
- description: "Optional; GET-only"
+ description: "Full release entities, included in GET responses when `releases`\n\
+ included in `expand` parameter. Ignored if included in PUT or POST\nrequests.\n"
items:
$ref: "#/definitions/release_entity"
release_ids:
type: "array"
+ description: "Set of identifier of release entities this file represents a\
+ \ full\nmanifestation of. Usually a single release, but some files contain\n\
+ content of multiple full releases (eg, an issue of a journal).\n"
items:
type: "string"
example: "q3nouwy3nnbsvo3h5klxsx4a7y"
@@ -7423,18 +7759,21 @@ definitions:
sha256:
type: "string"
example: "cb1c378f464d5935ddaa8de28446d82638396c61f042295d7fb85e3cccc9e452"
+ description: "SHA-256 hash of data, in hex encoding"
minLength: 64
maxLength: 64
pattern: "[a-f0-9]{64}"
sha1:
type: "string"
example: "e9dd75237c94b209dc3ccd52722de6931a310ba3"
+ description: "SHA-1 hash of data, in hex encoding"
minLength: 40
maxLength: 40
pattern: "[a-f0-9]{40}"
md5:
type: "string"
example: "1b39813549077b2347c0f370c3864b40"
+ description: "MD5 hash of data, in hex encoding"
minLength: 32
maxLength: 32
pattern: "[a-f0-9]{32}"
@@ -7442,10 +7781,15 @@ definitions:
type: "integer"
format: "int64"
example: 1048576
+ description: "Size of file in bytes. Non-zero."
edit_extra:
type: "object"
+ description: "Free-form JSON metadata that will be stored with specific entity\
+ \ edits\n(eg, creation/update/delete).\n"
extra:
type: "object"
+ description: "Free-form JSON metadata that will be stored with the other entity\n\
+ metadata. See guide for (unenforced) schema conventions.\n"
redirect:
type: "string"
example: "q3nouwy3nnbsvo3h5klxsx4a7y"
@@ -7469,6 +7813,7 @@ definitions:
pattern: "[a-zA-Z2-7]{26}"
state:
type: "string"
+ example: "active"
enum:
- "wip"
- "active"
@@ -7484,14 +7829,14 @@ definitions:
revision: "86daea5b-1b6b-432a-bb67-ea97795f80fe"
sha1: "e9dd75237c94b209dc3ccd52722de6931a310ba3"
urls:
- - rel: "webarchive"
+ - rel: "web"
url: "https://example.edu/~frau/prcding.pdf"
- - rel: "webarchive"
+ - rel: "web"
url: "https://example.edu/~frau/prcding.pdf"
size: 1048576
extra: "{}"
mimetype: "application/pdf"
- state: "wip"
+ state: "active"
release_ids:
- "q3nouwy3nnbsvo3h5klxsx4a7y"
- "q3nouwy3nnbsvo3h5klxsx4a7y"
@@ -7508,11 +7853,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\nfile.\n"
rel:
type: "string"
- example: "webarchive"
+ example: "web"
+ description: "Indicates type of host this URL points to. Eg, \"publisher\"\
+ ,\n\"repository\", \"webarchive\". See guide for list of acceptable values.\n"
example:
- rel: "webarchive"
+ rel: "web"
url: "https://example.edu/~frau/prcding.pdf"
upperCaseName: "FILE_URL"
fileset_entity:
@@ -7520,11 +7869,14 @@ definitions:
properties:
releases:
type: "array"
- description: "Optional; GET-only"
+ description: "Full release entities, included in GET responses when `releases`\n\
+ included in `expand` parameter. Ignored if included in PUT or POST\nrequests.\n"
items:
$ref: "#/definitions/release_entity"
release_ids:
type: "array"
+ description: "Set of identifier of release entities this fileset represents\
+ \ a full\nmanifestation of. Usually a single release.\n"
items:
type: "string"
example: "q3nouwy3nnbsvo3h5klxsx4a7y"
@@ -7542,6 +7894,7 @@ definitions:
$ref: "#/definitions/fileset_file"
state:
type: "string"
+ example: "active"
enum:
- "wip"
- "active"
@@ -7570,8 +7923,12 @@ definitions:
pattern: "[a-zA-Z2-7]{26}"
extra:
type: "object"
+ description: "Free-form JSON metadata that will be stored with the other entity\n\
+ metadata. See guide for (unenforced) schema conventions.\n"
edit_extra:
type: "object"
+ description: "Free-form JSON metadata that will be stored with specific entity\
+ \ edits\n(eg, creation/update/delete).\n"
example:
redirect: "q3nouwy3nnbsvo3h5klxsx4a7y"
urls:
@@ -7594,7 +7951,7 @@ definitions:
md5: "1b39813549077b2347c0f370c3864b40"
ident: "q3nouwy3nnbsvo3h5klxsx4a7y"
extra: "{}"
- state: "wip"
+ state: "active"
release_ids:
- "q3nouwy3nnbsvo3h5klxsx4a7y"
- "q3nouwy3nnbsvo3h5klxsx4a7y"
@@ -7617,6 +7974,8 @@ definitions:
rel:
type: "string"
example: "webarchive"
+ description: "Indicates type of host this URL points to. See guide for list\
+ \ of\nacceptable values.\n"
example:
rel: "webarchive"
url: "https://example.edu/~frau/prcding.pdf"
@@ -7630,30 +7989,38 @@ definitions:
path:
type: "string"
example: "img/cat.png"
+ description: "Path name of file within this fileset (eg, directory)\n"
size:
type: "integer"
format: "int64"
example: 1048576
+ description: "File size in bytes"
md5:
type: "string"
example: "1b39813549077b2347c0f370c3864b40"
+ description: "MD5 hash of data, in hex encoding"
minLength: 32
maxLength: 32
pattern: "[a-f0-9]{32}"
sha1:
type: "string"
example: "e9dd75237c94b209dc3ccd52722de6931a310ba3"
+ description: "SHA-1 hash of data, in hex encoding"
minLength: 40
maxLength: 40
pattern: "[a-f0-9]{40}"
sha256:
type: "string"
example: "cb1c378f464d5935ddaa8de28446d82638396c61f042295d7fb85e3cccc9e452"
+ description: "SHA-256 hash of data, in hex encoding"
minLength: 64
maxLength: 64
pattern: "[a-f0-9]{64}"
extra:
type: "object"
+ description: "Free-form additional metadata about this specific file in the\
+ \ set.\nEg, `mimetype`. See guide for nomative (but unenforced) schema\n\
+ fields.\n"
example:
sha1: "e9dd75237c94b209dc3ccd52722de6931a310ba3"
path: "img/cat.png"
@@ -7667,11 +8034,14 @@ definitions:
properties:
releases:
type: "array"
- description: "Optional; GET-only"
+ description: "Full release entities, included in GET responses when `releases`\n\
+ included in `expand` parameter. Ignored if included in PUT or POST\nrequests.\n"
items:
$ref: "#/definitions/release_entity"
release_ids:
type: "array"
+ description: "Set of identifier of release entities this fileset represents\
+ \ a full\nmanifestation of. Usually a single release.\n"
items:
type: "string"
example: "q3nouwy3nnbsvo3h5klxsx4a7y"
@@ -7682,13 +8052,14 @@ definitions:
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\noverall capture timestamp. Should generally be the timestamp of\n\
+ capture of the primary resource URL.\n"
original_url:
type: "string"
format: "url"
example: "http://asheesh.org"
+ description: "Base URL of the primary resource this is a capture of"
archive_urls:
type: "array"
items:
@@ -7699,8 +8070,12 @@ definitions:
$ref: "#/definitions/webcapture_cdx_line"
edit_extra:
type: "object"
+ description: "Free-form JSON metadata that will be stored with specific entity\
+ \ edits\n(eg, creation/update/delete).\n"
extra:
type: "object"
+ description: "Free-form JSON metadata that will be stored with the other entity\n\
+ metadata. See guide for (unenforced) schema conventions.\n"
redirect:
type: "string"
example: "q3nouwy3nnbsvo3h5klxsx4a7y"
@@ -7724,6 +8099,7 @@ definitions:
pattern: "[a-zA-Z2-7]{26}"
state:
type: "string"
+ example: "active"
enum:
- "wip"
- "active"
@@ -7756,7 +8132,7 @@ definitions:
timestamp: "2016-09-19T17:20:24Z"
ident: "q3nouwy3nnbsvo3h5klxsx4a7y"
extra: "{}"
- state: "wip"
+ state: "active"
release_ids:
- "q3nouwy3nnbsvo3h5klxsx4a7y"
- "q3nouwy3nnbsvo3h5klxsx4a7y"
@@ -7778,34 +8154,45 @@ definitions:
surt:
type: "string"
example: "org,asheesh)/apus/ch1/node15.html"
+ description: "\"Sortable URL\" format. See guide for details.\n"
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\n(or better) precision.\n"
url:
type: "string"
example: "http://www.asheesh.org:80/APUS/ch1/node15.html"
+ description: "Full URL/URI of resource captured.\n"
mimetype:
type: "string"
example: "text/html"
+ description: "Mimetype of the resource at this URL. May be the Content-Type\
+ \ header,\nor the actually sniffed file type.\n"
status_code:
type: "integer"
format: "int64"
example: 200
+ description: "HTTP status code. Should generally be 200, especially for the\
+ \ primary\nresource, but may be 3xx (redirect) or even error codes if embedded\n\
+ resources can not be fetched successfully.\n"
size:
type: "integer"
format: "int64"
example: 1048576
+ description: "Resource (file) size in bytes"
sha1:
type: "string"
example: "e9dd75237c94b209dc3ccd52722de6931a310ba3"
+ description: "SHA-1 hash of data, in hex encoding"
minLength: 40
maxLength: 40
pattern: "[a-f0-9]{40}"
sha256:
type: "string"
example: "cb1c378f464d5935ddaa8de28446d82638396c61f042295d7fb85e3cccc9e452"
+ description: "SHA-256 hash of data, in hex encoding"
minLength: 64
maxLength: 64
pattern: "[a-f0-9]{64}"
@@ -7829,9 +8216,13 @@ definitions:
type: "string"
format: "url"
example: "https://web.archive.org/web/"
+ description: "URL/URI pointing to archive of this web resource.\n"
rel:
type: "string"
example: "wayback"
+ description: "Type of archive endpoint. Usually `wayback` (WBM replay of primary\n\
+ resource), or `warc` (direct URL to a WARC file containing all\nresources\
+ \ of the capture). See guide for full list.\n"
example:
rel: "wayback"
url: "https://web.archive.org/web/"
@@ -7855,85 +8246,143 @@ definitions:
$ref: "#/definitions/release_contrib"
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\n\
+ published (if applicable).\n"
language:
type: "string"
- description: "Two-letter RFC1766/ISO639-1 language code, with extensions"
+ example: "en"
+ description: "Primary language of the content of the full release. Two-letter\n\
+ RFC1766/ISO639-1 language code, with some custom\nextensions/additions.\
+ \ See guide.\n"
publisher:
type: "string"
+ example: "Elsevier"
+ description: "Name, usually English, of the entity or institution responsible\
+ \ for\npublication of this release. Not necessarily the imprint/brand. See\n\
+ guide.\n"
version:
type: "string"
+ example: "3"
+ description: "For, eg, updated technical reports or software packages, where\n\
+ the version string may be the only field disambiguating between\nreleases.\n"
number:
type: "string"
+ example: "RFC1337"
+ description: "For, eg, technical reports, which are published in series or\n\
+ assigned some other institutional or container-specific identifier.\n"
pages:
type: "string"
+ example: "340-345"
+ description: "Either a single page number (\"first page\") or a range of pages\n\
+ separated by a dash (\"-\"). See guide for details.\n"
issue:
type: "string"
example: "12"
+ description: "Issue number of volume/container that this release was published\
+ \ in.\nSometimes coresponds to a month number in the year, but can be any\n\
+ string. See guide.\n"
volume:
type: "string"
+ example: "3"
+ description: "Volume number of container that this release was published in.\
+ \ Often\ncorresponds to the \"Nth\" year of publication, but can be any\
+ \ string.\nSee guide.\n"
ext_ids:
+ description: "Set of external identifiers for this release.\n"
$ref: "#/definitions/release_ext_ids"
withdrawn_year:
type: "integer"
format: "int64"
example: 2014
+ description: "Year corresponding with `withdrawn_date` like\n`release_year`/`release_date`.\n"
withdrawn_date:
type: "string"
format: "date"
+ description: "Full date when this release was formally withdrawn (if applicable).\n\
+ ISO format, like `release_date`.\n"
withdrawn_status:
type: "string"
+ example: "retracted"
+ description: "Type of withdrawl or retraction of this release, if applicable.\
+ \ If\nrelease has not been withdrawn, should be `null` (aka, not set, not\n\
+ the string \"null\" or an empty string).\n"
release_year:
type: "integer"
format: "int64"
example: 2014
+ description: "Year when this release was formally published. Must match\n\
+ `release_date` if that field is set; this field exists because\nsometimes\
+ \ only the year is known.\n"
release_date:
type: "string"
format: "date"
+ description: "Full date when this release was formally published. ISO format,\
+ \ like\n`2019-03-05`. See guide for semantics.\n"
release_stage:
type: "string"
- example: "preprint, retracted"
+ example: "preprint"
+ description: "The stage of publication of this specific release. See guide\
+ \ for\nvalid values and semantics.\n"
release_type:
type: "string"
example: "book"
+ description: "\"Type\" or \"medium\" that this release is published as. See\
+ \ guide for\nvalid values.\n"
container_id:
type: "string"
example: "q3nouwy3nnbsvo3h5klxsx4a7y"
+ description: "Used to link this release to a container entity that the release\
+ \ was\npublished as part of.\n"
webcaptures:
type: "array"
- description: "Optional; GET-only"
+ description: "Complete webcapture entities identified by `webcapture_ids`\
+ \ field.\nOnly included in GET responses when `webcaptures` included in\
+ \ `expand`\nparameter; ignored in PUT or POST requests.\n"
items:
$ref: "#/definitions/webcapture_entity"
filesets:
type: "array"
- description: "Optional; GET-only"
+ description: "Complete file entities identified by `filesets_ids` field. Only\n\
+ included in GET responses when `filesets` included in `expand`\nparameter;\
+ \ ignored in PUT or POST requests.\n"
items:
$ref: "#/definitions/fileset_entity"
files:
type: "array"
- description: "Optional; GET-only"
+ description: "Complete file entities identified by `file_ids` field. Only\n\
+ included in GET responses when `files` included in `expand` parameter;\n\
+ ignored in PUT or POST requests.\n"
items:
$ref: "#/definitions/file_entity"
container:
- description: "Optional; GET-only"
+ description: "Complete container entity identified by `container_id` field.\
+ \ Only\nincluded in GET reponses when `container` included in `expand`\n\
+ parameter; ignored in PUT or POST requests.\n"
$ref: "#/definitions/container_entity"
work_id:
type: "string"
example: "q3nouwy3nnbsvo3h5klxsx4a7y"
+ description: "Identifier of work this release is part of. In creation (POST)\n\
+ requests, a work entity will be created automatically if this field\nis\
+ \ not set.\n"
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\nguide for details.\n"
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\ninclude as separate field (unless combined title would be very long).\n\
+ See guide for details.\n"
title:
type: "string"
description: "Required for valid entities. The title used in citations and\
- \ for display; usually English"
+ \ for\ndisplay. Sometimes the English translation of title e even if release\n\
+ content is not English.\n"
state:
type: "string"
+ example: "active"
enum:
- "wip"
- "active"
@@ -7962,19 +8411,23 @@ definitions:
pattern: "[a-zA-Z2-7]{26}"
extra:
type: "object"
+ description: "Free-form JSON metadata that will be stored with the other entity\n\
+ metadata. See guide for (unenforced) schema conventions.\n"
edit_extra:
type: "object"
+ description: "Free-form JSON metadata that will be stored with specific entity\
+ \ edits\n(eg, creation/update/delete).\n"
example:
container:
redirect: "q3nouwy3nnbsvo3h5klxsx4a7y"
ident: "q3nouwy3nnbsvo3h5klxsx4a7y"
extra: "{}"
- container_type: "container_type"
+ container_type: "journal"
name: "Journal of Important Results"
publisher: "Society of Curious Students"
issnl: "1234-5678"
- wikidata_qid: "wikidata_qid"
- state: "wip"
+ wikidata_qid: "Q42812"
+ state: "active"
edit_extra: "{}"
revision: "86daea5b-1b6b-432a-bb67-ea97795f80fe"
webcaptures:
@@ -8004,7 +8457,7 @@ definitions:
timestamp: "2016-09-19T17:20:24Z"
ident: "q3nouwy3nnbsvo3h5klxsx4a7y"
extra: "{}"
- state: "wip"
+ state: "active"
release_ids:
- "q3nouwy3nnbsvo3h5klxsx4a7y"
- "q3nouwy3nnbsvo3h5klxsx4a7y"
@@ -8040,7 +8493,7 @@ definitions:
timestamp: "2016-09-19T17:20:24Z"
ident: "q3nouwy3nnbsvo3h5klxsx4a7y"
extra: "{}"
- state: "wip"
+ state: "active"
release_ids:
- "q3nouwy3nnbsvo3h5klxsx4a7y"
- "q3nouwy3nnbsvo3h5klxsx4a7y"
@@ -8051,8 +8504,8 @@ definitions:
timestamp: "2000-01-23T04:56:07.000+00:00"
revision: "86daea5b-1b6b-432a-bb67-ea97795f80fe"
ident: "q3nouwy3nnbsvo3h5klxsx4a7y"
- withdrawn_status: "withdrawn_status"
- language: "language"
+ withdrawn_status: "retracted"
+ language: "en"
title: "title"
contribs:
- raw_affiliation: "raw_affiliation"
@@ -8062,19 +8515,19 @@ definitions:
ident: "q3nouwy3nnbsvo3h5klxsx4a7y"
extra: "{}"
orcid: "0000-0002-1825-0097"
- wikidata_qid: "wikidata_qid"
- state: "wip"
+ wikidata_qid: "Q42812"
+ state: "active"
given_name: "given_name"
display_name: "Grace Hopper"
edit_extra: "{}"
revision: "86daea5b-1b6b-432a-bb67-ea97795f80fe"
- raw_name: "raw_name"
- role: "role"
- surname: "surname"
+ raw_name: "Jane K. Doe"
+ role: "author"
+ surname: "Doe"
extra: "{}"
creator_id: "q3nouwy3nnbsvo3h5klxsx4a7y"
- index: 1
- given_name: "given_name"
+ index: 0
+ given_name: "Jane"
- raw_affiliation: "raw_affiliation"
creator:
redirect: "q3nouwy3nnbsvo3h5klxsx4a7y"
@@ -8082,23 +8535,23 @@ definitions:
ident: "q3nouwy3nnbsvo3h5klxsx4a7y"
extra: "{}"
orcid: "0000-0002-1825-0097"
- wikidata_qid: "wikidata_qid"
- state: "wip"
+ wikidata_qid: "Q42812"
+ state: "active"
given_name: "given_name"
display_name: "Grace Hopper"
edit_extra: "{}"
revision: "86daea5b-1b6b-432a-bb67-ea97795f80fe"
- raw_name: "raw_name"
- role: "role"
- surname: "surname"
+ raw_name: "Jane K. Doe"
+ role: "author"
+ surname: "Doe"
extra: "{}"
creator_id: "q3nouwy3nnbsvo3h5klxsx4a7y"
- index: 1
- given_name: "given_name"
- number: "number"
- pages: "pages"
+ index: 0
+ given_name: "Jane"
+ number: "RFC1337"
+ pages: "340-345"
extra: "{}"
- state: "wip"
+ state: "active"
edit_extra: "{}"
withdrawn_year: 2014
redirect: "q3nouwy3nnbsvo3h5klxsx4a7y"
@@ -8116,43 +8569,43 @@ definitions:
content: "<jats:p>Some abstract thing goes here</jats:p>"
release_year: 2014
release_type: "book"
- version: "version"
+ version: "3"
revision: "86daea5b-1b6b-432a-bb67-ea97795f80fe"
- volume: "volume"
+ volume: "3"
ext_ids:
core: "core"
mag: "mag"
jstor: "jstor"
isbn13: "isbn13"
arxiv: "arxiv"
- wikidata_qid: "wikidata_qid"
+ wikidata_qid: "Q42812"
ark: "ark"
- pmid: "pmid"
- pmcid: "pmcid"
+ pmid: "482132"
+ pmcid: "PMC7391"
doi: "10.1234/abcde.789"
- release_stage: "preprint, retracted"
- license_slug: "license_slug"
+ release_stage: "preprint"
+ license_slug: "CC-BY"
withdrawn_date: "2000-01-23"
refs:
- target_release_id: "q3nouwy3nnbsvo3h5klxsx4a7y"
container_name: "container_name"
- year: 6
+ year: 1972
extra: "{}"
index: 0
title: "title"
locator: "p123"
- key: "key"
+ key: "SMITH2016"
- target_release_id: "q3nouwy3nnbsvo3h5klxsx4a7y"
container_name: "container_name"
- year: 6
+ year: 1972
extra: "{}"
index: 0
title: "title"
locator: "p123"
- key: "key"
+ key: "SMITH2016"
release_date: "2000-01-23"
subtitle: "subtitle"
- publisher: "publisher"
+ publisher: "Elsevier"
files:
- redirect: "q3nouwy3nnbsvo3h5klxsx4a7y"
sha256: "cb1c378f464d5935ddaa8de28446d82638396c61f042295d7fb85e3cccc9e452"
@@ -8163,14 +8616,14 @@ definitions:
revision: "86daea5b-1b6b-432a-bb67-ea97795f80fe"
sha1: "e9dd75237c94b209dc3ccd52722de6931a310ba3"
urls:
- - rel: "webarchive"
+ - rel: "web"
url: "https://example.edu/~frau/prcding.pdf"
- - rel: "webarchive"
+ - rel: "web"
url: "https://example.edu/~frau/prcding.pdf"
size: 1048576
extra: "{}"
mimetype: "application/pdf"
- state: "wip"
+ state: "active"
release_ids:
- "q3nouwy3nnbsvo3h5klxsx4a7y"
- "q3nouwy3nnbsvo3h5klxsx4a7y"
@@ -8185,14 +8638,14 @@ definitions:
revision: "86daea5b-1b6b-432a-bb67-ea97795f80fe"
sha1: "e9dd75237c94b209dc3ccd52722de6931a310ba3"
urls:
- - rel: "webarchive"
+ - rel: "web"
url: "https://example.edu/~frau/prcding.pdf"
- - rel: "webarchive"
+ - rel: "web"
url: "https://example.edu/~frau/prcding.pdf"
size: 1048576
extra: "{}"
mimetype: "application/pdf"
- state: "wip"
+ state: "active"
release_ids:
- "q3nouwy3nnbsvo3h5klxsx4a7y"
- "q3nouwy3nnbsvo3h5klxsx4a7y"
@@ -8220,7 +8673,7 @@ definitions:
md5: "1b39813549077b2347c0f370c3864b40"
ident: "q3nouwy3nnbsvo3h5klxsx4a7y"
extra: "{}"
- state: "wip"
+ state: "active"
release_ids:
- "q3nouwy3nnbsvo3h5klxsx4a7y"
- "q3nouwy3nnbsvo3h5klxsx4a7y"
@@ -8250,7 +8703,7 @@ definitions:
md5: "1b39813549077b2347c0f370c3864b40"
ident: "q3nouwy3nnbsvo3h5klxsx4a7y"
extra: "{}"
- state: "wip"
+ state: "active"
release_ids:
- "q3nouwy3nnbsvo3h5klxsx4a7y"
- "q3nouwy3nnbsvo3h5klxsx4a7y"
@@ -8267,34 +8720,49 @@ definitions:
doi:
type: "string"
example: "10.1234/abcde.789"
+ description: "Digital Object Identifier (DOI), mostly for published papers\
+ \ and\ndatasets. Should be registered and resolvable via https://doi.org/\n"
wikidata_qid:
type: "string"
+ example: "Q42812"
+ description: "Wikidata entity QID"
isbn13:
type: "string"
+ description: "ISBN-13, for books. Usually not set for chapters. ISBN-10 should\
+ \ be\nconverted to ISBN-13.\n"
pmid:
type: "string"
+ example: "482132"
+ description: "PubMed Identifier"
pmcid:
type: "string"
+ example: "PMC7391"
+ description: "PubMed Central Identifier"
core:
type: "string"
+ 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"
example:
core: "core"
mag: "mag"
jstor: "jstor"
isbn13: "isbn13"
arxiv: "arxiv"
- wikidata_qid: "wikidata_qid"
+ wikidata_qid: "Q42812"
ark: "ark"
- pmid: "pmid"
- pmcid: "pmcid"
+ pmid: "482132"
+ pmcid: "PMC7391"
doi: "10.1234/abcde.789"
upperCaseName: "RELEASE_EXT_IDS"
release_abstract:
@@ -8303,18 +8771,25 @@ definitions:
sha1:
type: "string"
example: "e9dd75237c94b209dc3ccd52722de6931a310ba3"
+ description: "SHA-1 hash of data, in hex encoding"
minLength: 40
maxLength: 40
pattern: "[a-f0-9]{40}"
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\nstring/text content may be included.\n"
mimetype:
type: "string"
example: "application/xml+jats"
+ description: "Mimetype of abstract contents. `text/plain` is the default if\
+ \ content\nisn't encoded.\n"
lang:
type: "string"
example: "en"
+ description: "ISO language code of the abstract. Same semantics as release\
+ \ `language` field.\n"
example:
sha1: "e9dd75237c94b209dc3ccd52722de6931a310ba3"
mimetype: "application/xml+jats"
@@ -8326,8 +8801,12 @@ definitions:
properties:
edit_extra:
type: "object"
+ description: "Free-form JSON metadata that will be stored with specific entity\
+ \ edits\n(eg, creation/update/delete).\n"
extra:
type: "object"
+ description: "Free-form JSON metadata that will be stored with the other entity\n\
+ metadata. See guide for (unenforced) schema conventions.\n"
redirect:
type: "string"
example: "q3nouwy3nnbsvo3h5klxsx4a7y"
@@ -8351,6 +8830,7 @@ definitions:
pattern: "[a-zA-Z2-7]{26}"
state:
type: "string"
+ example: "active"
enum:
- "wip"
- "active"
@@ -8360,7 +8840,7 @@ definitions:
redirect: "q3nouwy3nnbsvo3h5klxsx4a7y"
ident: "q3nouwy3nnbsvo3h5klxsx4a7y"
extra: "{}"
- state: "wip"
+ state: "active"
edit_extra: "{}"
revision: "86daea5b-1b6b-432a-bb67-ea97795f80fe"
upperCaseName: "WORK_ENTITY"
@@ -8380,10 +8860,10 @@ definitions:
example:
editgroup:
editor:
- is_admin: true
+ is_admin: false
is_active: true
editor_id: "q3nouwy3nnbsvo3h5klxsx4a7y"
- is_bot: true
+ is_bot: false
username: "zerocool93"
changelog_index: 1048576
submitted: "2000-01-23T04:56:07.000+00:00"
@@ -8500,10 +8980,10 @@ definitions:
annotations:
- annotation_id: "86daea5b-1b6b-432a-bb67-ea97795f80fe"
editor:
- is_admin: true
+ is_admin: false
is_active: true
editor_id: "q3nouwy3nnbsvo3h5klxsx4a7y"
- is_bot: true
+ is_bot: false
username: "zerocool93"
created: "2000-01-23T04:56:07.000+00:00"
extra: "{}"
@@ -8512,10 +8992,10 @@ definitions:
comment_markdown: "comment_markdown"
- annotation_id: "86daea5b-1b6b-432a-bb67-ea97795f80fe"
editor:
- is_admin: true
+ is_admin: false
is_active: true
editor_id: "q3nouwy3nnbsvo3h5klxsx4a7y"
- is_bot: true
+ is_bot: false
username: "zerocool93"
created: "2000-01-23T04:56:07.000+00:00"
extra: "{}"
@@ -8534,10 +9014,10 @@ definitions:
changelog_entry:
editgroup:
editor:
- is_admin: true
+ is_admin: false
is_active: true
editor_id: "q3nouwy3nnbsvo3h5klxsx4a7y"
- is_bot: true
+ is_bot: false
username: "zerocool93"
changelog_index: 1048576
submitted: "2000-01-23T04:56:07.000+00:00"
@@ -8654,10 +9134,10 @@ definitions:
annotations:
- annotation_id: "86daea5b-1b6b-432a-bb67-ea97795f80fe"
editor:
- is_admin: true
+ is_admin: false
is_active: true
editor_id: "q3nouwy3nnbsvo3h5klxsx4a7y"
- is_bot: true
+ is_bot: false
username: "zerocool93"
created: "2000-01-23T04:56:07.000+00:00"
extra: "{}"
@@ -8666,10 +9146,10 @@ definitions:
comment_markdown: "comment_markdown"
- annotation_id: "86daea5b-1b6b-432a-bb67-ea97795f80fe"
editor:
- is_admin: true
+ is_admin: false
is_active: true
editor_id: "q3nouwy3nnbsvo3h5klxsx4a7y"
- is_bot: true
+ is_bot: false
username: "zerocool93"
created: "2000-01-23T04:56:07.000+00:00"
extra: "{}"
@@ -8691,42 +9171,45 @@ definitions:
edit_id:
type: "string"
example: "86daea5b-1b6b-432a-bb67-ea97795f80fe"
- description: "UUID (lower-case, dash-separated, hex-encoded 128-bit)"
+ description: "Unique UUID for this specific edit object.\n"
minLength: 36
maxLength: 36
pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}"
ident:
type: "string"
example: "q3nouwy3nnbsvo3h5klxsx4a7y"
- description: "base32-encoded unique identifier"
+ description: "Fatcat identifier of the entity this edit is mutating.\n"
minLength: 26
maxLength: 26
pattern: "[a-zA-Z2-7]{26}"
revision:
type: "string"
example: "86daea5b-1b6b-432a-bb67-ea97795f80fe"
- description: "UUID (lower-case, dash-separated, hex-encoded 128-bit)"
+ description: "Entity revision that this edit will set the entity to. May be\n\
+ `null` in the case of deletions.\n"
minLength: 36
maxLength: 36
pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}"
prev_revision:
type: "string"
example: "86daea5b-1b6b-432a-bb67-ea97795f80fe"
- description: "UUID (lower-case, dash-separated, hex-encoded 128-bit)"
+ description: "Revision of entity just before this edit. May be used in the\
+ \ future\nto prevent edit race conditions.\n"
minLength: 36
maxLength: 36
pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}"
redirect_ident:
type: "string"
example: "q3nouwy3nnbsvo3h5klxsx4a7y"
- description: "base32-encoded unique identifier"
+ description: "When an edit is to merge entities (redirect one to another),\
+ \ this\nis the entity fatcat identifier for the target entity.\n"
minLength: 26
maxLength: 26
pattern: "[a-zA-Z2-7]{26}"
editgroup_id:
type: "string"
example: "q3nouwy3nnbsvo3h5klxsx4a7y"
- description: "base32-encoded unique identifier"
+ description: "Editgroup identifier that this edit is part of.\n"
minLength: 26
maxLength: 26
pattern: "[a-zA-Z2-7]{26}"
@@ -8749,24 +9232,35 @@ definitions:
editor_id:
type: "string"
example: "q3nouwy3nnbsvo3h5klxsx4a7y"
- description: "base32-encoded unique identifier"
+ description: "Fatcat identifier for the editor. Can not be changed.\n"
minLength: 26
maxLength: 26
pattern: "[a-zA-Z2-7]{26}"
username:
type: "string"
example: "zerocool93"
+ description: "Username/handle (short slug-like string) to identify this editor.\
+ \ May\nbe changed at any time by the editor; use the `editor_id` as a\n\
+ persistend identifer.\n"
is_admin:
type: "boolean"
+ example: false
+ description: "Whether this editor has the `admin` role.\n"
is_bot:
type: "boolean"
+ example: false
+ description: "Whether this editor is a bot (as opposed to a human making manual\n\
+ edits)\n"
is_active:
type: "boolean"
+ example: true
+ description: "Whether this editor's account is enabled (if not API tokens\
+ \ and web\nlogins will not work).\n"
example:
- is_admin: true
+ is_admin: false
is_active: true
editor_id: "q3nouwy3nnbsvo3h5klxsx4a7y"
- is_bot: true
+ is_bot: false
username: "zerocool93"
upperCaseName: "EDITOR"
editgroup:
@@ -8775,45 +9269,60 @@ definitions:
editgroup_id:
type: "string"
example: "q3nouwy3nnbsvo3h5klxsx4a7y"
- description: "base32-encoded unique identifier"
+ description: "Fatcat identifier for this editgroup. Assigned on creation.\n"
minLength: 26
maxLength: 26
pattern: "[a-zA-Z2-7]{26}"
editor_id:
type: "string"
example: "q3nouwy3nnbsvo3h5klxsx4a7y"
- description: "base32-encoded unique identifier"
+ description: "Fatcat identifer of editor that created this editgroup.\n"
minLength: 26
maxLength: 26
pattern: "[a-zA-Z2-7]{26}"
editor:
+ description: "Complete editor object identified by `container_id` field. Only\n\
+ included in GET responses.\n"
$ref: "#/definitions/editor"
changelog_index:
type: "integer"
format: "int64"
example: 1048576
+ description: "For accepted/merged editgroups, the changelog index that the\
+ \ accept\noccured at. WARNING: not populated in all contexts that an editgroup\n\
+ could be included in a response.\n"
created:
type: "string"
format: "date-time"
+ description: "Timestamp when this editgroup was first created.\n"
submitted:
type: "string"
format: "date-time"
+ description: "Timestamp when this editgroup was most recently submitted for\
+ \ review.\nIf withdrawn, or never submitted, will be `null`.\n"
description:
type: "string"
+ description: "Comment describing the changes in this editgroup. Can be updated\
+ \ with\nPUT request.\n"
extra:
type: "object"
+ description: "Free-form JSON metadata attached to this editgroup. Eg, metadata\n\
+ provenance, or script user-agent details. See guide for (unenforced)\nschema\
+ \ norms.\n"
annotations:
type: "array"
+ description: "Only included in GET responses, and not in all contexts. Do\
+ \ not\ninclude this field in PUT or POST requests.\n"
items:
$ref: "#/definitions/editgroup_annotation"
edits:
$ref: "#/definitions/editgroup_edits"
example:
editor:
- is_admin: true
+ is_admin: false
is_active: true
editor_id: "q3nouwy3nnbsvo3h5klxsx4a7y"
- is_bot: true
+ is_bot: false
username: "zerocool93"
changelog_index: 1048576
submitted: "2000-01-23T04:56:07.000+00:00"
@@ -8930,10 +9439,10 @@ definitions:
annotations:
- annotation_id: "86daea5b-1b6b-432a-bb67-ea97795f80fe"
editor:
- is_admin: true
+ is_admin: false
is_active: true
editor_id: "q3nouwy3nnbsvo3h5klxsx4a7y"
- is_bot: true
+ is_bot: false
username: "zerocool93"
created: "2000-01-23T04:56:07.000+00:00"
extra: "{}"
@@ -8942,10 +9451,10 @@ definitions:
comment_markdown: "comment_markdown"
- annotation_id: "86daea5b-1b6b-432a-bb67-ea97795f80fe"
editor:
- is_admin: true
+ is_admin: false
is_active: true
editor_id: "q3nouwy3nnbsvo3h5klxsx4a7y"
- is_bot: true
+ is_bot: false
username: "zerocool93"
created: "2000-01-23T04:56:07.000+00:00"
extra: "{}"
@@ -8967,33 +9476,39 @@ definitions:
editgroup_id:
type: "string"
example: "q3nouwy3nnbsvo3h5klxsx4a7y"
- description: "base32-encoded unique identifier"
+ description: "Editgroup that this annotation applies to. Set automatically\
+ \ in\ncreations based on URL parameter.\n"
minLength: 26
maxLength: 26
pattern: "[a-zA-Z2-7]{26}"
editor_id:
type: "string"
example: "q3nouwy3nnbsvo3h5klxsx4a7y"
- description: "base32-encoded unique identifier"
+ description: "Defaults to editor created the annotation via POST request.\n"
minLength: 26
maxLength: 26
pattern: "[a-zA-Z2-7]{26}"
editor:
+ description: "Only included in GET responses; ignored in PUT or POST requests.\n"
$ref: "#/definitions/editor"
created:
type: "string"
format: "date-time"
+ description: "Timestamp when annotation was first created.\n"
comment_markdown:
type: "string"
extra:
type: "object"
+ description: "Additional free-form JSON metadata that can be included as part\
+ \ of\nthe annotation (or even as the primary annotation itself). See guide\n\
+ for details.\n"
example:
annotation_id: "86daea5b-1b6b-432a-bb67-ea97795f80fe"
editor:
- is_admin: true
+ is_admin: false
is_active: true
editor_id: "q3nouwy3nnbsvo3h5klxsx4a7y"
- is_bot: true
+ is_bot: false
username: "zerocool93"
created: "2000-01-23T04:56:07.000+00:00"
extra: "{}"
@@ -9011,21 +9526,24 @@ definitions:
index:
type: "integer"
format: "int64"
+ description: "Monotonically increasing sequence number of this changelog entry.\n"
editgroup_id:
type: "string"
example: "q3nouwy3nnbsvo3h5klxsx4a7y"
+ description: "Identifier of editgroup accepted/merged in this changelog entry.\n"
timestamp:
type: "string"
format: "date-time"
+ description: "Date and time when the editgroup was accpeted.\n"
editgroup:
$ref: "#/definitions/editgroup"
example:
editgroup:
editor:
- is_admin: true
+ is_admin: false
is_active: true
editor_id: "q3nouwy3nnbsvo3h5klxsx4a7y"
- is_bot: true
+ is_bot: false
username: "zerocool93"
changelog_index: 1048576
submitted: "2000-01-23T04:56:07.000+00:00"
@@ -9142,10 +9660,10 @@ definitions:
annotations:
- annotation_id: "86daea5b-1b6b-432a-bb67-ea97795f80fe"
editor:
- is_admin: true
+ is_admin: false
is_active: true
editor_id: "q3nouwy3nnbsvo3h5klxsx4a7y"
- is_bot: true
+ is_bot: false
username: "zerocool93"
created: "2000-01-23T04:56:07.000+00:00"
extra: "{}"
@@ -9154,10 +9672,10 @@ definitions:
comment_markdown: "comment_markdown"
- annotation_id: "86daea5b-1b6b-432a-bb67-ea97795f80fe"
editor:
- is_admin: true
+ is_admin: false
is_active: true
editor_id: "q3nouwy3nnbsvo3h5klxsx4a7y"
- is_bot: true
+ is_bot: false
username: "zerocool93"
created: "2000-01-23T04:56:07.000+00:00"
extra: "{}"
@@ -9175,36 +9693,54 @@ definitions:
index:
type: "integer"
format: "int64"
+ description: "Zero-indexed sequence number of this reference in the list of\n\
+ references. Assigned automatically and used internally; don't confuse\n\
+ with `key`.\n"
target_release_id:
type: "string"
example: "q3nouwy3nnbsvo3h5klxsx4a7y"
- description: "base32-encoded unique identifier"
+ description: "Optional, fatcat identifier of release entity that this reference\
+ \ is\nciting.\n"
minLength: 26
maxLength: 26
pattern: "[a-zA-Z2-7]{26}"
extra:
type: "object"
+ description: "Additional free-form JSON metadata about this citation. Generally\n\
+ follows Citation Style Language (CSL) JSON schema. See guide for\ndetails.\n"
key:
type: "string"
+ example: "SMITH2016"
+ description: "Short string used to indicate this reference from within the\
+ \ release\ntext; or numbering of references as typeset in the release itself.\n\
+ Optional; don't confuse with `index` field.\n"
year:
type: "integer"
format: "int64"
+ example: 1972
+ description: "Year that the cited work was published in.\n"
container_name:
type: "string"
+ description: "Name of the container (eg, journal) that the citation work was\n\
+ published as part of. May be an acronym or full name.\n"
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\ncited. Not to be confused with the first page (or page range) of\
+ \ an\nentire paper or chapter being cited.\n"
example:
target_release_id: "q3nouwy3nnbsvo3h5klxsx4a7y"
container_name: "container_name"
- year: 6
+ year: 1972
extra: "{}"
index: 0
title: "title"
locator: "p123"
- key: "key"
+ key: "SMITH2016"
upperCaseName: "RELEASE_REF"
release_contrib:
type: "object"
@@ -9212,29 +9748,47 @@ definitions:
index:
type: "integer"
format: "int64"
+ example: 0
+ description: "Internally assigned zero-indexed sequence number of contribution.\n\
+ Authors should come first; this encodes the order of attriubtion.\n"
creator_id:
type: "string"
example: "q3nouwy3nnbsvo3h5klxsx4a7y"
- description: "base32-encoded unique identifier"
+ description: "If known, indicates the creator entity this contribution was\
+ \ made by.\n"
minLength: 26
maxLength: 26
pattern: "[a-zA-Z2-7]{26}"
creator:
- description: "Optional; GET-only"
+ description: "Complete creator entity. Only returned in GET responses, and\
+ \ only if\n`contribs` included in the `expand` query parameter.\n"
$ref: "#/definitions/creator_entity"
raw_name:
type: "string"
+ example: "Jane K. Doe"
+ description: "Full name of the contributor as typeset in the release.\n"
given_name:
type: "string"
+ example: "Jane"
+ description: "In English commonly the first name, but ordering is context\
+ \ and\nculture specific.\n"
surname:
type: "string"
+ example: "Doe"
+ description: "In English commonly the last, or family name, but ordering is\
+ \ context\nand culture specific.\n"
role:
type: "string"
+ example: "author"
+ description: "Short string (slug) indicating type of contribution (eg, \"\
+ author\",\n\"translator\"). See guide for list of accpeted values.\n"
raw_affiliation:
type: "string"
description: "Raw affiliation string as displayed in text"
extra:
type: "object"
+ description: "Additional free-form JSON metadata about this\ncontributor/contribution.\
+ \ See guide for normative schema.\n"
example:
raw_affiliation: "raw_affiliation"
creator:
@@ -9243,19 +9797,19 @@ definitions:
ident: "q3nouwy3nnbsvo3h5klxsx4a7y"
extra: "{}"
orcid: "0000-0002-1825-0097"
- wikidata_qid: "wikidata_qid"
- state: "wip"
+ wikidata_qid: "Q42812"
+ state: "active"
given_name: "given_name"
display_name: "Grace Hopper"
edit_extra: "{}"
revision: "86daea5b-1b6b-432a-bb67-ea97795f80fe"
- raw_name: "raw_name"
- role: "role"
- surname: "surname"
+ raw_name: "Jane K. Doe"
+ role: "author"
+ surname: "Doe"
extra: "{}"
creator_id: "q3nouwy3nnbsvo3h5klxsx4a7y"
- index: 1
- given_name: "given_name"
+ index: 0
+ given_name: "Jane"
upperCaseName: "RELEASE_CONTRIB"
container_auto_batch:
type: "object"
@@ -9358,12 +9912,24 @@ definitions:
properties:
provider:
type: "string"
+ example: "orcid"
+ description: "Fatcat-specific short name (slug) for remote service being used\
+ \ for\nauthentication.\n"
sub:
type: "string"
+ example: "https://orcid.org"
+ description: "`SUB` from OIDC protocol. Usually a URL."
iss:
type: "string"
+ example: "0000-0002-8593-9468"
+ description: "`ISS` from OIDC protocol. Usually a stable account username,\
+ \ number, or identifier."
preferred_username:
type: "string"
+ example: "bnewbold"
+ description: "What it sounds like; returned by OIDC, and used as a hint when\n\
+ creating new editor accounts. Fatcat usernames are usually this\nstring\
+ \ with the `provider` slug as a suffix, though some munging may\noccur.\n"
upperCaseName: "AUTH_OIDC"
auth_oidc_result:
type: "object"
@@ -9375,14 +9941,15 @@ definitions:
$ref: "#/definitions/editor"
token:
type: "string"
+ example: "AgEPZGV2LmZhdGNhdC53aWtpAhYyMDE5MDEwMS1kZXYtZHVtbXkta2V5AAImZWRpdG9yX2lkID0gYWFhYWFhYWFhYWFhYmt2a2FhYWFhYWFhYWkAAht0aW1lID4gMjAxOS0wMS0wOVQwMDo1Nzo1MloAAAYgnroNha1hSftChtxHGTnLEmM/pY8MeQS/jBSV0UNvXug="
example:
editor:
- is_admin: true
+ is_admin: false
is_active: true
editor_id: "q3nouwy3nnbsvo3h5klxsx4a7y"
- is_bot: true
+ is_bot: false
username: "zerocool93"
- token: "token"
+ token: "AgEPZGV2LmZhdGNhdC53aWtpAhYyMDE5MDEwMS1kZXYtZHVtbXkta2V5AAImZWRpdG9yX2lkID0gYWFhYWFhYWFhYWFhYmt2a2FhYWFhYWFhYWkAAht0aW1lID4gMjAxOS0wMS0wOVQwMDo1Nzo1MloAAAYgnroNha1hSftChtxHGTnLEmM/pY8MeQS/jBSV0UNvXug="
upperCaseName: "AUTH_OIDC_RESULT"
editgroup_edits:
properties:
@@ -9414,6 +9981,8 @@ definitions:
type: "array"
items:
$ref: "#/definitions/entity_edit"
+ description: "Only included in GET responses, and not in all contexts. Do not\n\
+ include this field in PUT or POST requests.\n"
example:
works:
- ident: "q3nouwy3nnbsvo3h5klxsx4a7y"
@@ -9521,50 +10090,84 @@ definitions:
prev_revision: "86daea5b-1b6b-432a-bb67-ea97795f80fe"
revision: "86daea5b-1b6b-432a-bb67-ea97795f80fe"
upperCaseName: "EDITGROUP_EDITS"
+x-servers:
+- url: "https://api.fatcat.wiki/v0"
+ description: "Production Server"
+- url: "https://api.qa.fatcat.wiki/v0"
+ description: "QA Server"
+x-tagGroups:
+- name: "Entities"
+ tags:
+ - "containers"
+ - "creators"
+ - "files"
+ - "filesets"
+ - "webcaptures"
+ - "releases"
+ - "works"
+- name: "Editing"
+ tags:
+ - "editors"
+ - "editgroups"
+ - "changelog"
+- name: "Other"
+ tags:
+ - "auth"
x-fatcat-ident:
type: "string"
- example: "q3nouwy3nnbsvo3h5klxsx4a7y"
pattern: "[a-zA-Z2-7]{26}"
minLength: 26
maxLength: 26
description: "base32-encoded unique identifier"
+x-fatcat-ident-example:
+ example: "q3nouwy3nnbsvo3h5klxsx4a7y"
x-fatcat-uuid:
type: "string"
- example: "86daea5b-1b6b-432a-bb67-ea97795f80fe"
pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}"
minLength: 36
maxLength: 36
description: "UUID (lower-case, dash-separated, hex-encoded 128-bit)"
+x-fatcat-uuid-example:
+ example: "86daea5b-1b6b-432a-bb67-ea97795f80fe"
x-issn:
type: "string"
- example: "1234-5678"
pattern: "\\d{4}-\\d{3}[0-9X]"
minLength: 9
maxLength: 9
+x-issn-example:
+ example: "1234-5678"
x-orcid:
type: "string"
- example: "0000-0002-1825-0097"
pattern: "\\d{4}-\\d{4}-\\d{4}-\\d{3}[\\dX]"
minLength: 19
maxLength: 19
+ description: "ORCiD (https://orcid.org) identifier"
+x-orcid-example:
+ example: "0000-0002-1825-0097"
x-md5:
type: "string"
- example: "1b39813549077b2347c0f370c3864b40"
pattern: "[a-f0-9]{32}"
minLength: 32
maxLength: 32
+ description: "MD5 hash of data, in hex encoding"
+x-md5-example:
+ example: "1b39813549077b2347c0f370c3864b40"
x-sha1:
type: "string"
- example: "e9dd75237c94b209dc3ccd52722de6931a310ba3"
pattern: "[a-f0-9]{40}"
minLength: 40
maxLength: 40
+ description: "SHA-1 hash of data, in hex encoding"
+x-sha1-example:
+ example: "e9dd75237c94b209dc3ccd52722de6931a310ba3"
x-sha256:
type: "string"
- example: "cb1c378f464d5935ddaa8de28446d82638396c61f042295d7fb85e3cccc9e452"
pattern: "[a-f0-9]{64}"
minLength: 64
maxLength: 64
+ description: "SHA-256 hash of data, in hex encoding"
+x-sha256-example:
+ example: "cb1c378f464d5935ddaa8de28446d82638396c61f042295d7fb85e3cccc9e452"
x-entity-props:
state:
type: "string"
@@ -9573,32 +10176,37 @@ x-entity-props:
- "active"
- "redirect"
- "deleted"
+ example: "active"
ident:
+ example: "q3nouwy3nnbsvo3h5klxsx4a7y"
description: "base32-encoded unique identifier"
maxLength: 26
minLength: 26
pattern: "[a-zA-Z2-7]{26}"
- example: "q3nouwy3nnbsvo3h5klxsx4a7y"
type: "string"
revision:
+ example: "86daea5b-1b6b-432a-bb67-ea97795f80fe"
description: "UUID (lower-case, dash-separated, hex-encoded 128-bit)"
maxLength: 36
minLength: 36
pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}"
- example: "86daea5b-1b6b-432a-bb67-ea97795f80fe"
type: "string"
redirect:
- type: "string"
example: "q3nouwy3nnbsvo3h5klxsx4a7y"
+ type: "string"
pattern: "[a-zA-Z2-7]{26}"
minLength: 26
maxLength: 26
description: "base32-encoded unique identifier"
extra:
type: "object"
+ description: "Free-form JSON metadata that will be stored with the other entity\n\
+ metadata. See guide for (unenforced) schema conventions.\n"
additionalProperties: {}
edit_extra:
type: "object"
+ description: "Free-form JSON metadata that will be stored with specific entity\
+ \ edits\n(eg, creation/update/delete).\n"
additionalProperties: {}
x-auth-responses:
401:
generated by cgit v1.2.3 (git 2.39.1) at 2024-11-27 01:23:46 +0000