diff options
Diffstat (limited to 'rust/fatcat-openapi/api/swagger.yaml')
| -rw-r--r-- | rust/fatcat-openapi/api/swagger.yaml | 1052 |
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: |