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