diff options
Diffstat (limited to 'rust/fatcat-openapi/api.yaml')
| -rw-r--r-- | rust/fatcat-openapi/api.yaml | 4074 |
1 files changed, 0 insertions, 4074 deletions
diff --git a/rust/fatcat-openapi/api.yaml b/rust/fatcat-openapi/api.yaml deleted file mode 100644 index 1b533a30..00000000 --- a/rust/fatcat-openapi/api.yaml +++ /dev/null @@ -1,4074 +0,0 @@ ---- -swagger: "2.0" -info: - title: fatcat - version: 0.3.1 - description: | - Fatcat is a scalable, versioned, API-oriented catalog of bibliographic - entities and file metadata. - - <!-- STARTLONGDESCRIPTION --> - These API reference documents, along with client software libraries, are - generated automatically from an OpenAPI 2.0 ("Swagger") definition file. - - ## Introduction - - - 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> --> - <!-- ENDLONGDESCRIPTION --> - - termsOfService: "https://guide.fatcat.wiki/policies.html" - contact: - name: "Internet Archive Web Group" - email: "webservices@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 -consumes: - - application/json -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 - x-displayName: "Containers" # TAGLINE - description: | # TAGLINE - **Container** entities represent publication venues like journals, # TAGLINE - conference proceedings, book series, or blogs. They group publications # TAGLINE - ("releases"). # TAGLINE - - See the "Catalog Style Guide" section of the guide for details and # TAGLINE - semantics of what should be included in specific entity fields. # TAGLINE - Specifically, the # TAGLINE - [Container Entity Reference](https://guide.fatcat.wiki/entity_container.html). # TAGLINE - - name: creators # TAGLINE - x-displayName: "Creators" # TAGLINE - description: | # TAGLINE - **Creator** entities represent individuals (or organizations, or other # TAGLINE - agents) who contribute to the creation of specific releases # TAGLINE - (publications). # TAGLINE - - See the "Catalog Style Guide" section of the guide for details and # TAGLINE - semantics of what should be included in specific entity fields. # TAGLINE - Specifically, the # TAGLINE - [Creator Entity Reference](https://guide.fatcat.wiki/entity_creator.html). # TAGLINE - - name: files # TAGLINE - x-displayName: "Files" # TAGLINE - description: | # TAGLINE - **File** entities represent unique digital files which are full # TAGLINE - manifestations of specific releases (publications), such as fulltext PDF # TAGLINE - files, JATS XML documents, or video files. File entities also include a # TAGLINE - set of locations where they can be found on the public web. # TAGLINE - - See the "Catalog Style Guide" section of the guide for details and # TAGLINE - semantics of what should be included in specific entity fields. # TAGLINE - Specifically, the # TAGLINE - [File Entity Reference](https://guide.fatcat.wiki/entity_file.html). # TAGLINE - - name: filesets # TAGLINE - x-displayName: "Filesets" # TAGLINE - description: | # TAGLINE - **Fileset** entities represent sets of digital files, as well as locations # TAGLINE - where they can be found on the public web. Filesets most commonly # TAGLINE - represent datasets consisting of serveral data and metadata files. # TAGLINE - - See the "Catalog Style Guide" section of the guide for details and # TAGLINE - semantics of what should be included in specific entity fields. # TAGLINE - Specifically, the # TAGLINE - [Fileset Entity Reference](https://guide.fatcat.wiki/entity_fileset.html). # TAGLINE - - name: webcaptures # TAGLINE - x-displayName: "Webcaptures" # TAGLINE - description: | # TAGLINE - **Web Capture** entities represent archival snapshots of web pages (or # TAGLINE - other web resources), which are usually complete manifestations of a # TAGLINE - specific release entity. Web Captures also include a set of locations # TAGLINE - (wayback replay instances or WARC files) where the capture can be found. # TAGLINE - - See the "Catalog Style Guide" section of the guide for details and # TAGLINE - semantics of what should be included in specific entity fields. # TAGLINE - Specifically, the # TAGLINE - [Web Capture Entity Reference](https://guide.fatcat.wiki/entity_webcapture.html). # TAGLINE - - name: releases # TAGLINE - x-displayName: "Releases" # TAGLINE - description: | # TAGLINE - **Release** entities represent specific published versions of a research # TAGLINE - work, such as a pre-print, a journal article, a book (or chapter), or a # TAGLINE - scholarly blog post. Releases are always grouped together under Works; # TAGLINE - they may be published in a specific Container; they may have known # TAGLINE - Creators; and there may exist known File/Fileset/WebCapture digital copies # TAGLINE - of the release. # TAGLINE - - See the "Catalog Style Guide" section of the guide for details and # TAGLINE - semantics of what should be included in specific entity fields. # TAGLINE - Specifically, the # TAGLINE - [Release Entity Reference](https://guide.fatcat.wiki/entity_release.html). # TAGLINE - - name: works # TAGLINE - x-displayName: "Works" # TAGLINE - description: | # TAGLINE - **Work** entities group several Release entities which are different # TAGLINE - versions of the same abstract piece of research. For example, three # TAGLINE - release entities representing the pre-print, published article, and # TAGLINE - retraction stages of the same journal paper would be grouped under a # TAGLINE - single work. # TAGLINE - - See the "Catalog Style Guide" section of the guide for details and # TAGLINE - semantics of what should be included in specific entity fields. # TAGLINE - Specifically, the # TAGLINE - [Work Entity Reference](https://guide.fatcat.wiki/entity_work.html). # TAGLINE - - name: editgroups # TAGLINE - x-displayName: "Editgroups" # TAGLINE - description: | # TAGLINE - **Editgroups** are sets of changes, each to individual entities in the # TAGLINE - catalog. Every edit must be part of an editgroup which is reviewed and # TAGLINE - accepted (merged) as a whole. # TAGLINE - - name: editors # TAGLINE - x-displayName: "Editors" # TAGLINE - description: | # TAGLINE - **Editors** are human user accounts and bots that make changes to the # TAGLINE - Fatcat catalog. # TAGLINE - - The API allows fetching (and updating) metadata about individual editors, # TAGLINE - as well as fetching editor's annotation and edit history. # TAGLINE - - name: changelog # TAGLINE - x-displayName: "Changelog" # TAGLINE - description: | # TAGLINE - The **Changelog** is the ordered feed of editgroups which have been # TAGLINE - accepted into the catalog. # TAGLINE - - name: auth # TAGLINE - x-displayName: "Auth Methods" # TAGLINE - description: | # TAGLINE - Helper methods and internal APIs for editor authentication. # TAGLINE - -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 - type: string - pattern: "[a-zA-Z2-7]{26}" - minLength: 26 - maxLength: 26 - description: "base32-encoded unique identifier" -x-fatcat-ident-example: &FATCATIDENTEXAMPLE - example: "q3nouwy3nnbsvo3h5klxsx4a7y" -x-fatcat-uuid: &FATCATUUID - type: string - 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: &FATCATUUIDEXAMPLE - example: "86daea5b-1b6b-432a-bb67-ea97795f80fe" -x-issn: &FATCATISSN - type: string - pattern: "\\d{4}-\\d{3}[0-9X]" - minLength: 9 - maxLength: 9 -x-issn-example: &FATCATISSNEXAMPLE - example: "1234-5678" -x-orcid: &FATCATORCID - type: string - pattern: "\\d{4}-\\d{4}-\\d{4}-\\d{3}[\\dX]" - minLength: 19 - maxLength: 19 - description: "ORCiD (https://orcid.org) identifier" -x-orcid-example: &FATCATORCIDEXAMPLE - example: "0000-0002-1825-0097" -x-md5: &FATCATMD5 - type: string - pattern: "[a-f0-9]{32}" - minLength: 32 - maxLength: 32 - description: "MD5 hash of data, in hex encoding" -x-md5-example: &FATCATMD5EXAMPLE - example: "1b39813549077b2347c0f370c3864b40" -x-sha1: &FATCATSHA1 - type: string - pattern: "[a-f0-9]{40}" - minLength: 40 - maxLength: 40 - description: "SHA-1 hash of data, in hex encoding" -x-sha1-example: &FATCATSHA1EXAMPLE - example: "e9dd75237c94b209dc3ccd52722de6931a310ba3" -x-sha256: &FATCATSHA256 - type: string - pattern: "[a-f0-9]{64}" - minLength: 64 - maxLength: 64 - description: "SHA-256 hash of data, in hex encoding" -x-sha256-example: &FATCATSHA256EXAMPLE - example: "cb1c378f464d5935ddaa8de28446d82638396c61f042295d7fb85e3cccc9e452" - -# Common properties across entities -x-entity-props: &ENTITYPROPS - state: - type: string - enum: ["wip", "active", "redirect", "deleted"] - example: "active" - ident: - <<: *FATCATIDENT - <<: *FATCATIDENTEXAMPLE - revision: - <<: *FATCATUUID - <<: *FATCATUUIDEXAMPLE - redirect: - <<: *FATCATIDENT - <<: *FATCATIDENTEXAMPLE - 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: - error_response: - type: object - required: - - success - - error - - message - properties: - success: - type: boolean - example: false - error: - type: string - example: "unexpected-thing" - message: - type: string - example: "A really confusing, totally unexpected thing happened" - success: - type: object - required: - - success - - message - properties: - success: - type: boolean - example: true - message: - type: string - example: "The computers did the thing successfully!" - container_entity: - type: object - # required for creation: name - properties: - <<: *ENTITYPROPS - name: - type: string - description: "Name of the container (eg, Journal title). Required for entity creation." - example: "Journal of Important Results" - container_type: - type: string - 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 - <<: *FATCATISSNEXAMPLE - wikidata_qid: - type: string - example: "Q42812" - creator_entity: - type: object - # required for creation: display_name - properties: - <<: *ENTITYPROPS - display_name: - type: string - example: "Grace Hopper" - 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 - <<: *FATCATORCIDEXAMPLE - wikidata_qid: - type: string - example: "Q42812" - description: "Wikidata entity QID" - file_entity: - type: object - properties: - <<: *ENTITYPROPS - size: - type: integer - example: 1048576 - format: int64 - description: "Size of file in bytes. Non-zero." - md5: - <<: *FATCATMD5 - <<: *FATCATMD5EXAMPLE - sha1: - <<: *FATCATSHA1 - <<: *FATCATSHA1EXAMPLE - sha256: - <<: *FATCATSHA256 - <<: *FATCATSHA256EXAMPLE - urls: - type: array - items: - $ref: "#/definitions/file_url" - mimetype: - type: string - example: "application/pdf" - release_ids: - type: array - items: - <<: *FATCATIDENT - <<: *FATCATIDENTEXAMPLE - 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: | - 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" - file_url: - type: object - required: - - url - - rel - properties: - url: - 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: "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: - <<: *ENTITYPROPS - manifest: - # limit of 200 files, at least to start - type: array - items: - $ref: "#/definitions/fileset_file" - urls: - type: array - items: - $ref: "#/definitions/fileset_url" - release_ids: - type: array - items: - <<: *FATCATIDENT - <<: *FATCATIDENTEXAMPLE - description: | - Set of identifier of release entities this fileset represents a full - manifestation of. Usually a single release. - releases: - 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: - - url - - rel - properties: - url: - type: string - format: url - example: "https://example.edu/~frau/prcding.pdf" - 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: - - path - - size - properties: - 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 - <<: *FATCATMD5EXAMPLE - sha1: - <<: *FATCATSHA1 - <<: *FATCATSHA1EXAMPLE - sha256: - <<: *FATCATSHA256 - <<: *FATCATSHA256EXAMPLE - 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: - <<: *ENTITYPROPS - cdx: - # limit of 200 CDX lines, at least to start? - type: array - items: - $ref: "#/definitions/webcapture_cdx_line" - archive_urls: - type: array - items: - $ref: "#/definitions/webcapture_url" - original_url: - 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. Should generally be the timestamp of - capture of the primary resource URL. - release_ids: - type: array - items: - <<: *FATCATIDENT - <<: *FATCATIDENTEXAMPLE - description: | - Set of identifier of release entities this fileset represents a full - manifestation of. Usually a single release. - releases: - 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: - - surt - - timestamp - - url - - sha1 - properties: - 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: | - 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 - <<: *FATCATSHA1EXAMPLE - sha256: - <<: *FATCATSHA256 - <<: *FATCATSHA256EXAMPLE - webcapture_url: - type: object - required: - - url - - rel - properties: - url: - 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 - required: - - ext_ids - properties: - <<: *ENTITYPROPS - title: - type: string - 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: | - 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 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: | - 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: - 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: - 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: - 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" - 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: - 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 - example: "CC-BY" - description: | - Short string (slug) name of license under which release is openly - published (if applicable). - contribs: - type: array - items: - $ref: "#/definitions/release_contrib" - refs: - type: array - items: - $ref: "#/definitions/release_ref" - abstracts: - type: array - items: - $ref: "#/definitions/release_abstract" - release_ext_ids: - type: object - properties: - doi: - 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: - sha1: - <<: *FATCATSHA1 - <<: *FATCATSHA1EXAMPLE - 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: - <<: *ENTITYPROPS - entity_history_entry: - type: object - required: - - edit - - editgroup - - changelog_entry - properties: - edit: - $ref: "#/definitions/entity_edit" - editgroup: - $ref: "#/definitions/editgroup" - changelog_entry: - $ref: "#/definitions/changelog_entry" - entity_edit: - type: object - required: - - edit_id - - ident - - editgroup_id - properties: - edit_id: - <<: *FATCATUUID - <<: *FATCATUUIDEXAMPLE - description: | - Unique UUID for this specific edit object. - ident: - <<: *FATCATIDENT - <<: *FATCATIDENTEXAMPLE - description: | - Fatcat identifier of the entity this edit is mutating. - revision: - <<: *FATCATUUID - <<: *FATCATUUIDEXAMPLE - description: | - Entity revision that this edit will set the entity to. May be - `null` in the case of deletions. - prev_revision: - <<: *FATCATUUID - <<: *FATCATUUIDEXAMPLE - description: | - Revision of entity just before this edit. May be used in the future - to prevent edit race conditions. - redirect_ident: - <<: *FATCATIDENT - <<: *FATCATIDENTEXAMPLE - 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 - <<: *FATCATIDENTEXAMPLE - description: | - Editgroup identifier that this edit is part of. - extra: - type: object - additionalProperties: {} - editor: - type: object - required: - - username - properties: - editor_id: - <<: *FATCATIDENT - <<: *FATCATIDENTEXAMPLE - 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 - <<: *FATCATIDENTEXAMPLE - description: | - Fatcat identifier for this editgroup. Assigned on creation. - editor_id: - <<: *FATCATIDENT - <<: *FATCATIDENTEXAMPLE - 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 - items: - $ref: "#/definitions/entity_edit" - creators: - type: array - items: - $ref: "#/definitions/entity_edit" - files: - type: array - items: - $ref: "#/definitions/entity_edit" - filesets: - type: array - items: - $ref: "#/definitions/entity_edit" - webcaptures: - type: array - items: - $ref: "#/definitions/entity_edit" - releases: - type: array - items: - $ref: "#/definitions/entity_edit" - works: - type: array - items: - $ref: "#/definitions/entity_edit" - editgroup_annotation: - type: object - properties: - annotation_id: - <<: *FATCATUUID - <<: *FATCATUUIDEXAMPLE - editgroup_id: - <<: *FATCATIDENT - <<: *FATCATIDENTEXAMPLE - description: | - Editgroup that this annotation applies to. Set automatically in - creations based on URL parameter. - editor_id: - <<: *FATCATIDENT - <<: *FATCATIDENTEXAMPLE - 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: - - index - - editgroup_id - - timestamp - properties: - 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: - type: object - properties: - 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 - <<: *FATCATIDENTEXAMPLE - 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 - <<: *FATCATIDENTEXAMPLE - description: | - If known, indicates the creator entity this contribution was made by. - creator: - $ref: "#/definitions/creator_entity" - 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: - - editgroup - - entity_list - properties: - editgroup: - $ref: "#/definitions/editgroup" - entity_list: - type: array - items: - $ref: "#/definitions/container_entity" - creator_auto_batch: - type: object - required: - - editgroup - - entity_list - properties: - editgroup: - $ref: "#/definitions/editgroup" - entity_list: - type: array - items: - $ref: "#/definitions/creator_entity" - file_auto_batch: - type: object - required: - - editgroup - - entity_list - properties: - editgroup: - $ref: "#/definitions/editgroup" - entity_list: - type: array - items: - $ref: "#/definitions/file_entity" - fileset_auto_batch: - type: object - required: - - editgroup - - entity_list - properties: - editgroup: - $ref: "#/definitions/editgroup" - entity_list: - type: array - items: - $ref: "#/definitions/fileset_entity" - webcapture_auto_batch: - type: object - required: - - editgroup - - entity_list - properties: - editgroup: - $ref: "#/definitions/editgroup" - entity_list: - type: array - items: - $ref: "#/definitions/webcapture_entity" - release_auto_batch: - type: object - required: - - editgroup - - entity_list - properties: - editgroup: - $ref: "#/definitions/editgroup" - entity_list: - type: array - items: - $ref: "#/definitions/release_entity" - work_auto_batch: - type: object - required: - - editgroup - - entity_list - properties: - editgroup: - $ref: "#/definitions/editgroup" - entity_list: - type: array - items: - $ref: "#/definitions/work_entity" - auth_oidc: - type: object - required: - - provider - - sub - - iss - - preferred_username - 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: - - editor - - token - properties: - editor: - $ref: "#/definitions/editor" - token: - type: string - example: "AgEPZGV2LmZhdGNhdC53aWtpAhYyMDE5MDEwMS1kZXYtZHVtbXkta2V5AAImZWRpdG9yX2lkID0gYWFhYWFhYWFhYWFhYmt2a2FhYWFhYWFhYWkAAht0aW1lID4gMjAxOS0wMS0wOVQwMDo1Nzo1MloAAAYgnroNha1hSftChtxHGTnLEmM/pY8MeQS/jBSV0UNvXug=" - auth_token_result: - type: object - required: - - token - properties: - token: - type: string - example: "AgEPZGV2LmZhdGNhdC53aWtpAhYyMDE5MDEwMS1kZXYtZHVtbXkta2V5AAImZWRpdG9yX2lkID0gYWFhYWFhYWFhYWFhYmt2a2FhYWFhYWFhYWkAAht0aW1lID4gMjAxOS0wMS0wOVQwMDo1Nzo1MloAAAYgnroNha1hSftChtxHGTnLEmM/pY8MeQS/jBSV0UNvXug=" - -x-auth-responses: &AUTHRESPONSES - 401: - description: Not Authorized # "Authentication information is missing or invalid" - schema: - $ref: "#/definitions/error_response" - headers: - WWW_Authenticate: - type: string - 403: - description: Forbidden - schema: - $ref: "#/definitions/error_response" -x-entity-responses: &ENTITYRESPONSES - 400: - description: Bad Request - schema: - $ref: "#/definitions/error_response" - 404: - description: Not Found - schema: - $ref: "#/definitions/error_response" - 500: - description: Generic Error - schema: - $ref: "#/definitions/error_response" - -paths: - /editgroup/{editgroup_id}/container: - parameters: - - name: editgroup_id - in: path - type: string - required: true - post: - 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 - required: true - schema: - $ref: "#/definitions/container_entity" - security: - - Bearer: [] - responses: - 201: - description: Created Entity - schema: - $ref: "#/definitions/entity_edit" - <<: *ENTITYRESPONSES - <<: *AUTHRESPONSES - /editgroup/auto/container/batch: - post: - 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 - required: true - schema: - $ref: "#/definitions/container_auto_batch" - security: - - Bearer: [] - responses: - 201: - description: Created Editgroup - schema: - $ref: "#/definitions/editgroup" - <<: *ENTITYRESPONSES - <<: *AUTHRESPONSES - /container/{ident}: - parameters: - - name: ident - in: path - type: string - required: true - get: - operationId: "get_container" - tags: # TAGLINE - - containers # TAGLINE - description: | - Fetches a single container entity from the catalog. - parameters: - - name: expand - in: query - type: string - required: false - description: "List of sub-entities to expand in response. For containers, none accepted (yet)." - - name: hide - in: query - type: string - required: false - description: "List of entity fields to elide in response. For containers, none accepted (yet)." - responses: - 200: - description: Found Entity - schema: - $ref: "#/definitions/container_entity" - <<: *ENTITYRESPONSES - /editgroup/{editgroup_id}/container/{ident}: - parameters: - - name: editgroup_id - in: path - type: string - required: true - - name: ident - in: path - type: string - required: true - put: - 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 - required: true - schema: - $ref: "#/definitions/container_entity" - security: - - Bearer: [] - responses: - 200: - description: Updated Entity - schema: - $ref: "#/definitions/entity_edit" - <<: *ENTITYRESPONSES - <<: *AUTHRESPONSES - delete: - 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: - 200: - description: Deleted Entity - schema: - $ref: "#/definitions/entity_edit" - <<: *ENTITYRESPONSES - <<: *AUTHRESPONSES - /container/rev/{rev_id}: - parameters: - - name: rev_id - in: path - required: true - <<: *FATCATUUID - get: - 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. See `get_container`." - - name: hide - in: query - type: string - required: false - description: "List of entity fields to elide in response. See `get_container`." - responses: - 200: - description: Found Entity Revision - schema: - $ref: "#/definitions/container_entity" - <<: *ENTITYRESPONSES - /container/{ident}/history: - parameters: - - name: ident - in: path - type: string - required: true - - name: limit - in: query - 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: - description: Found Entity History - schema: - type: array - items: - $ref: "#/definitions/entity_history_entry" - <<: *ENTITYRESPONSES - /container/{ident}/redirects: - parameters: - - name: ident - in: path - type: string - required: true - get: - operationId: "get_container_redirects" - tags: # TAGLINE - - containers # TAGLINE - description: | - Returns the set of entity identifiers which currently redirect to this - identifier. - responses: - 200: - description: Found Entity Redirects - schema: - type: array - items: - <<: *FATCATIDENT - <<: *ENTITYRESPONSES - /container/lookup: - get: - 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 - required: false - <<: *FATCATISSN - - name: wikidata_qid - in: query - type: string - required: false - - name: expand - in: query - type: string - required: false - 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. See `get_container`." - responses: - 200: - description: Found Entity - schema: - $ref: "#/definitions/container_entity" - <<: *ENTITYRESPONSES - /container/edit/{edit_id}: - get: - 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 - required: true - <<: *FATCATUUID - responses: - 200: - description: Found Edit - schema: - $ref: "#/definitions/entity_edit" - <<: *ENTITYRESPONSES - /editgroup/{editgroup_id}/container/edit/{edit_id}: - parameters: - - name: editgroup_id - in: path - required: true - type: string - - name: edit_id - in: path - required: true - <<: *FATCATUUID - delete: - 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: - 200: - description: Deleted Edit - schema: - $ref: "#/definitions/success" - <<: *ENTITYRESPONSES - <<: *AUTHRESPONSES - - /editgroup/{editgroup_id}/creator: - parameters: - - name: editgroup_id - in: path - type: string - required: true - post: - operationId: "create_creator" - tags: # TAGLINE - - creators # TAGLINE - parameters: - - name: entity - in: body - required: true - schema: - $ref: "#/definitions/creator_entity" - security: - - Bearer: [] - responses: - 201: - description: Created Entity - schema: - $ref: "#/definitions/entity_edit" - <<: *ENTITYRESPONSES - <<: *AUTHRESPONSES - /editgroup/auto/creator/batch: - post: - operationId: "create_creator_auto_batch" - tags: # TAGLINE - - creators # TAGLINE - parameters: - - name: auto_batch - in: body - required: true - schema: - $ref: "#/definitions/creator_auto_batch" - security: - - Bearer: [] - responses: - 201: - description: Created Editgroup - schema: - $ref: "#/definitions/editgroup" - <<: *ENTITYRESPONSES - <<: *AUTHRESPONSES - /creator/{ident}: - parameters: - - name: ident - in: path - type: string - required: true - get: - operationId: "get_creator" - tags: # TAGLINE - - creators # TAGLINE - parameters: - - name: expand - in: query - type: string - required: false - description: "List of sub-entities to expand in response. For creators, none accepted (yet)." - - name: hide - in: query - type: string - required: false - description: "List of entity fields to elide in response. For creators, none accepted (yet)." - responses: - 200: - description: Found Entity - schema: - $ref: "#/definitions/creator_entity" - <<: *ENTITYRESPONSES - /editgroup/{editgroup_id}/creator/{ident}: - parameters: - - name: editgroup_id - in: path - type: string - required: true - - name: ident - in: path - type: string - required: true - put: - operationId: "update_creator" - tags: # TAGLINE - - creators # TAGLINE - parameters: - - name: entity - in: body - required: true - schema: - $ref: "#/definitions/creator_entity" - security: - - Bearer: [] - responses: - 200: - description: Updated Entity - schema: - $ref: "#/definitions/entity_edit" - <<: *ENTITYRESPONSES - <<: *AUTHRESPONSES - delete: - operationId: "delete_creator" - tags: # TAGLINE - - creators # TAGLINE - security: - - Bearer: [] - responses: - 200: - description: Deleted Entity - schema: - $ref: "#/definitions/entity_edit" - <<: *ENTITYRESPONSES - <<: *AUTHRESPONSES - /creator/rev/{rev_id}: - parameters: - - name: rev_id - in: path - required: true - <<: *FATCATUUID - get: - operationId: "get_creator_revision" - tags: # TAGLINE - - creators # TAGLINE - parameters: - - name: expand - in: query - type: string - required: false - 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. See `get_creator`." - responses: - 200: - description: Found Entity Revision - schema: - $ref: "#/definitions/creator_entity" - <<: *ENTITYRESPONSES - /creator/{ident}/history: - parameters: - - name: ident - in: path - type: string - required: true - - name: limit - in: query - type: integer - format: int64 - required: false - get: - operationId: "get_creator_history" - tags: # TAGLINE - - creators # TAGLINE - responses: - 200: - description: Found Entity History - schema: - type: array - items: - $ref: "#/definitions/entity_history_entry" - <<: *ENTITYRESPONSES - /creator/{ident}/releases: - parameters: - - name: ident - in: path - type: string - required: true - - name: hide - in: query - type: string - required: false - 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 - schema: - type: array - items: - $ref: "#/definitions/release_entity" - <<: *ENTITYRESPONSES - /creator/{ident}/redirects: - parameters: - - name: ident - in: path - type: string - required: true - get: - operationId: "get_creator_redirects" - tags: # TAGLINE - - creators # TAGLINE - responses: - 200: - description: Found Entity Redirects - schema: - type: array - items: - <<: *FATCATIDENT - <<: *ENTITYRESPONSES - /creator/lookup: - get: - operationId: "lookup_creator" - tags: # TAGLINE - - creators # TAGLINE - parameters: - - name: orcid - in: query - required: false - <<: *FATCATORCID - - name: wikidata_qid - in: query - type: string - required: false - - name: expand - in: query - type: string - required: false - 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. See `get_creator`." - responses: - 200: - description: Found Entity - schema: - $ref: "#/definitions/creator_entity" - <<: *ENTITYRESPONSES - /creator/edit/{edit_id}: - get: - operationId: "get_creator_edit" - tags: # TAGLINE - - creators # TAGLINE - parameters: - - name: edit_id - in: path - required: true - <<: *FATCATUUID - responses: - 200: - description: Found Edit - schema: - $ref: "#/definitions/entity_edit" - <<: *ENTITYRESPONSES - /editgroup/{editgroup_id}/creator/edit/{edit_id}: - parameters: - - name: editgroup_id - in: path - required: true - type: string - - name: edit_id - in: path - required: true - <<: *FATCATUUID - delete: - operationId: "delete_creator_edit" - tags: # TAGLINE - - creators # TAGLINE - security: - - Bearer: [] - responses: - 200: - description: Deleted Edit - schema: - $ref: "#/definitions/success" - <<: *ENTITYRESPONSES - <<: *AUTHRESPONSES - - /editgroup/{editgroup_id}/file: - parameters: - - name: editgroup_id - in: path - type: string - required: true - post: - operationId: "create_file" - tags: # TAGLINE - - files # TAGLINE - parameters: - - name: entity - in: body - required: true - schema: - $ref: "#/definitions/file_entity" - security: - - Bearer: [] - responses: - 201: - description: Created Entity - schema: - $ref: "#/definitions/entity_edit" - <<: *ENTITYRESPONSES - <<: *AUTHRESPONSES - /editgroup/auto/file/batch: - post: - operationId: "create_file_auto_batch" - tags: # TAGLINE - - files # TAGLINE - parameters: - - name: auto_batch - in: body - required: true - schema: - $ref: "#/definitions/file_auto_batch" - security: - - Bearer: [] - responses: - 201: - description: Created Editgroup - schema: - $ref: "#/definitions/editgroup" - <<: *ENTITYRESPONSES - <<: *AUTHRESPONSES - /file/{ident}: - parameters: - - name: ident - in: path - type: string - required: true - get: - operationId: "get_file" - tags: # TAGLINE - - files # TAGLINE - parameters: - - name: expand - in: query - type: string - required: false - description: "List of sub-entities to expand in response. For files, `releases` is accepted." - - name: hide - in: query - type: string - required: false - description: "List of entity fields to elide in response. For files, none accepted (yet)." - responses: - 200: - description: Found Entity - schema: - $ref: "#/definitions/file_entity" - <<: *ENTITYRESPONSES - /editgroup/{editgroup_id}/file/{ident}: - parameters: - - name: editgroup_id - in: path - type: string - required: true - - name: ident - in: path - type: string - required: true - put: - operationId: "update_file" - tags: # TAGLINE - - files # TAGLINE - parameters: - - name: entity - in: body - required: true - schema: - $ref: "#/definitions/file_entity" - security: - - Bearer: [] - responses: - 200: - description: Updated Entity - schema: - $ref: "#/definitions/entity_edit" - <<: *ENTITYRESPONSES - <<: *AUTHRESPONSES - delete: - operationId: "delete_file" - tags: # TAGLINE - - files # TAGLINE - security: - - Bearer: [] - responses: - 200: - description: Deleted Entity - schema: - $ref: "#/definitions/entity_edit" - <<: *ENTITYRESPONSES - <<: *AUTHRESPONSES - /file/rev/{rev_id}: - parameters: - - name: rev_id - in: path - required: true - <<: *FATCATUUID - get: - operationId: "get_file_revision" - tags: # TAGLINE - - files # TAGLINE - parameters: - - name: expand - in: query - type: string - required: false - 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. See `get_file`." - responses: - 200: - description: Found Entity Revision - schema: - $ref: "#/definitions/file_entity" - <<: *ENTITYRESPONSES - /file/{ident}/history: - parameters: - - name: ident - in: path - type: string - required: true - - name: limit - in: query - type: integer - format: int64 - required: false - get: - operationId: "get_file_history" - tags: # TAGLINE - - files # TAGLINE - responses: - 200: - description: Found Entity History - schema: - type: array - items: - $ref: "#/definitions/entity_history_entry" - <<: *ENTITYRESPONSES - /file/{ident}/redirects: - parameters: - - name: ident - in: path - type: string - required: true - get: - operationId: "get_file_redirects" - tags: # TAGLINE - - files # TAGLINE - responses: - 200: - description: Found Entity Redirects - schema: - type: array - items: - <<: *FATCATIDENT - <<: *ENTITYRESPONSES - /file/lookup: - get: - operationId: "lookup_file" - tags: # TAGLINE - - files # TAGLINE - parameters: - - name: md5 - in: query - required: false - <<: *FATCATMD5 - - name: sha1 - in: query - required: false - <<: *FATCATSHA1 - - name: sha256 - in: query - required: false - <<: *FATCATSHA256 - - name: expand - in: query - type: string - required: false - 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. See `get_file`." - responses: - 200: - description: Found Entity - schema: - $ref: "#/definitions/file_entity" - <<: *ENTITYRESPONSES - /file/edit/{edit_id}: - get: - operationId: "get_file_edit" - tags: # TAGLINE - - files # TAGLINE - parameters: - - name: edit_id - in: path - required: true - <<: *FATCATUUID - responses: - 200: - description: Found Edit - schema: - $ref: "#/definitions/entity_edit" - <<: *ENTITYRESPONSES - /editgroup/{editgroup_id}/file/edit/{edit_id}: - parameters: - - name: editgroup_id - in: path - required: true - type: string - - name: edit_id - in: path - required: true - <<: *FATCATUUID - delete: - operationId: "delete_file_edit" - tags: # TAGLINE - - files # TAGLINE - security: - - Bearer: [] - responses: - 200: - description: Deleted Edit - schema: - $ref: "#/definitions/success" - <<: *ENTITYRESPONSES - <<: *AUTHRESPONSES - - /editgroup/{editgroup_id}/fileset: - parameters: - - name: editgroup_id - in: path - type: string - required: true - post: - operationId: "create_fileset" - tags: # TAGLINE - - filesets # TAGLINE - parameters: - - name: entity - in: body - required: true - schema: - $ref: "#/definitions/fileset_entity" - security: - - Bearer: [] - responses: - 201: - description: Created Entity - schema: - $ref: "#/definitions/entity_edit" - <<: *ENTITYRESPONSES - <<: *AUTHRESPONSES - /editgroup/auto/fileset/batch: - post: - operationId: "create_fileset_auto_batch" - tags: # TAGLINE - - filesets # TAGLINE - parameters: - - name: auto_batch - in: body - required: true - schema: - $ref: "#/definitions/fileset_auto_batch" - security: - - Bearer: [] - responses: - 201: - description: Created Editgroup - schema: - $ref: "#/definitions/editgroup" - <<: *ENTITYRESPONSES - <<: *AUTHRESPONSES - /fileset/{ident}: - parameters: - - name: ident - in: path - type: string - required: true - get: - operationId: "get_fileset" - tags: # TAGLINE - - filesets # TAGLINE - parameters: - - name: expand - in: query - type: string - required: false - description: "List of sub-entities to expand in response. For filesets, `releases` is accepted." - - name: hide - in: query - type: string - required: false - description: "List of entity fields to elide in response. For filesets, 'manifest' is accepted." - responses: - 200: - description: Found Entity - schema: - $ref: "#/definitions/fileset_entity" - <<: *ENTITYRESPONSES - /editgroup/{editgroup_id}/fileset/{ident}: - parameters: - - name: editgroup_id - in: path - type: string - required: true - - name: ident - in: path - type: string - required: true - put: - operationId: "update_fileset" - tags: # TAGLINE - - filesets # TAGLINE - parameters: - - name: entity - in: body - required: true - schema: - $ref: "#/definitions/fileset_entity" - security: - - Bearer: [] - responses: - 200: - description: Updated Entity - schema: - $ref: "#/definitions/entity_edit" - <<: *ENTITYRESPONSES - <<: *AUTHRESPONSES - delete: - operationId: "delete_fileset" - tags: # TAGLINE - - filesets # TAGLINE - security: - - Bearer: [] - responses: - 200: - description: Deleted Entity - schema: - $ref: "#/definitions/entity_edit" - <<: *ENTITYRESPONSES - <<: *AUTHRESPONSES - /fileset/rev/{rev_id}: - parameters: - - name: rev_id - in: path - required: true - <<: *FATCATUUID - get: - operationId: "get_fileset_revision" - tags: # TAGLINE - - filesets # TAGLINE - parameters: - - name: expand - in: query - type: string - required: false - 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. See `get_fileset`." - responses: - 200: - description: Found Entity Revision - schema: - $ref: "#/definitions/fileset_entity" - <<: *ENTITYRESPONSES - /fileset/{ident}/history: - parameters: - - name: ident - in: path - type: string - required: true - - name: limit - in: query - type: integer - format: int64 - required: false - get: - operationId: "get_fileset_history" - tags: # TAGLINE - - filesets # TAGLINE - responses: - 200: - description: Found Entity History - schema: - type: array - items: - $ref: "#/definitions/entity_history_entry" - <<: *ENTITYRESPONSES - /fileset/{ident}/redirects: - parameters: - - name: ident - in: path - type: string - required: true - get: - operationId: "get_fileset_redirects" - tags: # TAGLINE - - filesets # TAGLINE - responses: - 200: - description: Found Entity Redirects - schema: - type: array - items: - <<: *FATCATIDENT - <<: *ENTITYRESPONSES - /fileset/edit/{edit_id}: - get: - operationId: "get_fileset_edit" - tags: # TAGLINE - - filesets # TAGLINE - parameters: - - name: edit_id - in: path - required: true - <<: *FATCATUUID - responses: - 200: - description: Found Edit - schema: - $ref: "#/definitions/entity_edit" - <<: *ENTITYRESPONSES - /editgroup/{editgroup_id}/fileset/edit/{edit_id}: - parameters: - - name: editgroup_id - in: path - required: true - type: string - - name: edit_id - in: path - required: true - <<: *FATCATUUID - delete: - operationId: "delete_fileset_edit" - tags: # TAGLINE - - filesets # TAGLINE - security: - - Bearer: [] - responses: - 200: - description: Deleted Edit - schema: - $ref: "#/definitions/success" - <<: *ENTITYRESPONSES - <<: *AUTHRESPONSES - - /editgroup/{editgroup_id}/webcapture: - parameters: - - name: editgroup_id - in: path - type: string - required: true - post: - operationId: "create_webcapture" - tags: # TAGLINE - - webcaptures # TAGLINE - parameters: - - name: entity - in: body - required: true - schema: - $ref: "#/definitions/webcapture_entity" - security: - - Bearer: [] - responses: - 201: - description: Created Entity - schema: - $ref: "#/definitions/entity_edit" - <<: *ENTITYRESPONSES - <<: *AUTHRESPONSES - /editgroup/auto/webcapture/batch: - post: - operationId: "create_webcapture_auto_batch" - tags: # TAGLINE - - webcaptures # TAGLINE - parameters: - - name: auto_batch - in: body - required: true - schema: - $ref: "#/definitions/webcapture_auto_batch" - security: - - Bearer: [] - responses: - 201: - description: Created Editgroup - schema: - $ref: "#/definitions/editgroup" - <<: *ENTITYRESPONSES - <<: *AUTHRESPONSES - /webcapture/{ident}: - parameters: - - name: ident - in: path - type: string - required: true - get: - operationId: "get_webcapture" - tags: # TAGLINE - - webcaptures # TAGLINE - parameters: - - name: expand - in: query - type: string - required: false - description: "List of sub-entities to expand in response. For webcaptures, `releases` is accepted." - - name: hide - in: query - type: string - required: false - description: "List of entity fields to elide in response. For webcaptures, 'cdx' is accepted." - responses: - 200: - description: Found Entity - schema: - $ref: "#/definitions/webcapture_entity" - <<: *ENTITYRESPONSES - /editgroup/{editgroup_id}/webcapture/{ident}: - parameters: - - name: editgroup_id - in: path - type: string - required: true - - name: ident - in: path - type: string - required: true - put: - operationId: "update_webcapture" - tags: # TAGLINE - - webcaptures # TAGLINE - parameters: - - name: entity - in: body - required: true - schema: - $ref: "#/definitions/webcapture_entity" - security: - - Bearer: [] - responses: - 200: - description: Updated Entity - schema: - $ref: "#/definitions/entity_edit" - <<: *ENTITYRESPONSES - <<: *AUTHRESPONSES - delete: - operationId: "delete_webcapture" - tags: # TAGLINE - - webcaptures # TAGLINE - security: - - Bearer: [] - responses: - 200: - description: Deleted Entity - schema: - $ref: "#/definitions/entity_edit" - <<: *ENTITYRESPONSES - <<: *AUTHRESPONSES - /webcapture/rev/{rev_id}: - parameters: - - name: rev_id - in: path - required: true - <<: *FATCATUUID - get: - operationId: "get_webcapture_revision" - tags: # TAGLINE - - webcaptures # TAGLINE - parameters: - - name: expand - in: query - type: string - required: false - 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. See `get_webcapture`." - responses: - 200: - description: Found Entity Revision - schema: - $ref: "#/definitions/webcapture_entity" - <<: *ENTITYRESPONSES - /webcapture/{ident}/history: - parameters: - - name: ident - in: path - type: string - required: true - - name: limit - in: query - type: integer - format: int64 - required: false - get: - operationId: "get_webcapture_history" - tags: # TAGLINE - - webcaptures # TAGLINE - responses: - 200: - description: Found Entity History - schema: - type: array - items: - $ref: "#/definitions/entity_history_entry" - <<: *ENTITYRESPONSES - /webcapture/{ident}/redirects: - parameters: - - name: ident - in: path - type: string - required: true - get: - operationId: "get_webcapture_redirects" - tags: # TAGLINE - - webcaptures # TAGLINE - responses: - 200: - description: Found Entity Redirects - schema: - type: array - items: - <<: *FATCATIDENT - <<: *ENTITYRESPONSES - /webcapture/edit/{edit_id}: - get: - operationId: "get_webcapture_edit" - tags: # TAGLINE - - webcaptures # TAGLINE - parameters: - - name: edit_id - in: path - required: true - <<: *FATCATUUID - responses: - 200: - description: Found Edit - schema: - $ref: "#/definitions/entity_edit" - <<: *ENTITYRESPONSES - /editgroup/{editgroup_id}/webcapture/edit/{edit_id}: - parameters: - - name: editgroup_id - in: path - required: true - type: string - - name: edit_id - in: path - required: true - <<: *FATCATUUID - delete: - operationId: "delete_webcapture_edit" - tags: # TAGLINE - - webcaptures # TAGLINE - security: - - Bearer: [] - responses: - 200: - description: Deleted Edit - schema: - $ref: "#/definitions/success" - <<: *ENTITYRESPONSES - <<: *AUTHRESPONSES - - /editgroup/{editgroup_id}/release: - parameters: - - name: editgroup_id - in: path - type: string - required: true - post: - 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 - required: true - schema: - $ref: "#/definitions/release_entity" - security: - - Bearer: [] - responses: - 201: - description: Created Entity - schema: - $ref: "#/definitions/entity_edit" - <<: *ENTITYRESPONSES - <<: *AUTHRESPONSES - /editgroup/auto/release/batch: - post: - 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 - required: true - schema: - $ref: "#/definitions/release_auto_batch" - security: - - Bearer: [] - responses: - 201: - description: Created Editgroup - schema: - $ref: "#/definitions/editgroup" - <<: *ENTITYRESPONSES - <<: *AUTHRESPONSES - /release/{ident}: - parameters: - - name: ident - in: path - type: string - required: true - get: - 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. - - name: hide - in: query - type: string - required: false - description: | - List of entity fields to elide in response (for efficiency). For - releases, 'abstracts', 'refs', and 'contribs' are valid. - responses: - 200: - description: Found Entity - schema: - $ref: "#/definitions/release_entity" - <<: *ENTITYRESPONSES - /editgroup/{editgroup_id}/release/{ident}: - parameters: - - name: editgroup_id - in: path - type: string - required: true - - name: ident - in: path - type: string - required: true - put: - 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 - required: true - schema: - $ref: "#/definitions/release_entity" - security: - - Bearer: [] - responses: - 200: - description: Updated Entity - schema: - $ref: "#/definitions/entity_edit" - <<: *ENTITYRESPONSES - <<: *AUTHRESPONSES - delete: - 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: - 200: - description: Deleted Entity - schema: - $ref: "#/definitions/entity_edit" - <<: *ENTITYRESPONSES - <<: *AUTHRESPONSES - /release/rev/{rev_id}: - parameters: - - name: rev_id - in: path - required: true - <<: *FATCATUUID - get: - 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. 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. See `get_release`." - responses: - 200: - description: Found Entity Revision - schema: - $ref: "#/definitions/release_entity" - <<: *ENTITYRESPONSES - /release/{ident}/history: - parameters: - - name: ident - in: path - type: string - required: true - - name: limit - in: query - type: integer - format: int64 - required: false - get: - 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 - schema: - type: array - items: - $ref: "#/definitions/entity_history_entry" - <<: *ENTITYRESPONSES - /release/{ident}/files: - parameters: - - name: ident - in: path - type: string - required: true - - name: hide - in: query - type: string - required: false - 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 - schema: - type: array - items: - $ref: "#/definitions/file_entity" - <<: *ENTITYRESPONSES - /release/{ident}/filesets: - parameters: - - name: ident - in: path - type: string - required: true - - name: hide - in: query - type: string - required: false - 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 - schema: - type: array - items: - $ref: "#/definitions/fileset_entity" - <<: *ENTITYRESPONSES - /release/{ident}/webcaptures: - parameters: - - name: ident - in: path - type: string - required: true - - name: hide - in: query - type: string - required: false - 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 - schema: - type: array - items: - $ref: "#/definitions/webcapture_entity" - <<: *ENTITYRESPONSES - /release/{ident}/redirects: - parameters: - - name: ident - in: path - type: string - required: true - get: - operationId: "get_release_redirects" - tags: # TAGLINE - - releases # TAGLINE - description: | - Returns the set of entity identifiers which currently redirect to this - identifier. - responses: - 200: - description: Found Entity Redirects - schema: - type: array - items: - <<: *FATCATIDENT - <<: *ENTITYRESPONSES - /release/lookup: - get: - 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 - required: false - - name: wikidata_qid - in: query - type: string - required: false - - name: isbn13 - in: query - type: string - required: false - - name: pmid - in: query - type: string - required: false - - name: pmcid - in: query - type: string - required: false - - name: core - in: query - type: string - required: false - - name: arxiv - in: query - type: string - required: false - - name: jstor - in: query - type: string - required: false - - name: ark - in: query - type: string - required: false - - name: mag - in: query - type: string - required: false - - name: expand - in: query - type: string - required: false - 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 elide in response. See `get_release`." - responses: - 200: - description: Found Entity - schema: - $ref: "#/definitions/release_entity" - <<: *ENTITYRESPONSES - /release/edit/{edit_id}: - get: - 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 - required: true - <<: *FATCATUUID - responses: - 200: - description: Found Edit - schema: - $ref: "#/definitions/entity_edit" - <<: *ENTITYRESPONSES - /editgroup/{editgroup_id}/release/edit/{edit_id}: - parameters: - - name: editgroup_id - in: path - required: true - type: string - - name: edit_id - in: path - required: true - <<: *FATCATUUID - delete: - 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: - 200: - description: Deleted Edit - schema: - $ref: "#/definitions/success" - <<: *ENTITYRESPONSES - <<: *AUTHRESPONSES - - /editgroup/{editgroup_id}/work: - parameters: - - name: editgroup_id - in: path - type: string - required: true - post: - operationId: "create_work" - tags: # TAGLINE - - works # TAGLINE - parameters: - - name: entity - in: body - required: true - schema: - $ref: "#/definitions/work_entity" - security: - - Bearer: [] - responses: - 201: - description: Created Entity - schema: - $ref: "#/definitions/entity_edit" - <<: *ENTITYRESPONSES - <<: *AUTHRESPONSES - /editgroup/auto/work/batch: - post: - operationId: "create_work_auto_batch" - tags: # TAGLINE - - works # TAGLINE - parameters: - - name: auto_batch - in: body - required: true - schema: - $ref: "#/definitions/work_auto_batch" - security: - - Bearer: [] - responses: - 201: - description: Created Editgroup - schema: - $ref: "#/definitions/editgroup" - <<: *ENTITYRESPONSES - <<: *AUTHRESPONSES - /work/{ident}: - parameters: - - name: ident - in: path - type: string - required: true - get: - operationId: "get_work" - tags: # TAGLINE - - works # TAGLINE - parameters: - - name: expand - in: query - type: string - required: false - description: "List of sub-entities to expand in response. For works, none accepted (yet)." - - name: hide - in: query - type: string - required: false - description: "List of entity fields to elide in response. For works, none accepted (yet)." - responses: - 200: - description: Found Entity - schema: - $ref: "#/definitions/work_entity" - <<: *ENTITYRESPONSES - /editgroup/{editgroup_id}/work/{ident}: - parameters: - - name: editgroup_id - in: path - type: string - required: true - - name: ident - in: path - type: string - required: true - put: - operationId: "update_work" - tags: # TAGLINE - - works # TAGLINE - parameters: - - name: entity - in: body - required: true - schema: - $ref: "#/definitions/work_entity" - security: - - Bearer: [] - responses: - 200: - description: Updated Entity - schema: - $ref: "#/definitions/entity_edit" - <<: *ENTITYRESPONSES - <<: *AUTHRESPONSES - delete: - operationId: "delete_work" - tags: # TAGLINE - - works # TAGLINE - security: - - Bearer: [] - responses: - 200: - description: Deleted Entity - schema: - $ref: "#/definitions/entity_edit" - <<: *ENTITYRESPONSES - <<: *AUTHRESPONSES - /work/rev/{rev_id}: - parameters: - - name: rev_id - in: path - required: true - <<: *FATCATUUID - get: - operationId: "get_work_revision" - tags: # TAGLINE - - works # TAGLINE - parameters: - - name: expand - in: query - type: string - required: false - 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. See `get_work`." - responses: - 200: - description: Found Entity Revision - schema: - $ref: "#/definitions/work_entity" - <<: *ENTITYRESPONSES - /work/{ident}/history: - parameters: - - name: ident - in: path - type: string - required: true - - name: limit - in: query - type: integer - format: int64 - required: false - get: - operationId: "get_work_history" - tags: # TAGLINE - - works # TAGLINE - responses: - 200: - description: Found Entity History - schema: - type: array - items: - $ref: "#/definitions/entity_history_entry" - <<: *ENTITYRESPONSES - /work/{ident}/redirects: - parameters: - - name: ident - in: path - type: string - required: true - get: - operationId: "get_work_redirects" - tags: # TAGLINE - - works # TAGLINE - responses: - 200: - description: Found Entity Redirects - schema: - type: array - items: - <<: *FATCATIDENT - <<: *ENTITYRESPONSES - /work/{ident}/releases: - parameters: - - name: ident - in: path - type: string - required: true - - name: hide - in: query - type: string - required: false - 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 - schema: - type: array - items: - $ref: "#/definitions/release_entity" - <<: *ENTITYRESPONSES - /work/edit/{edit_id}: - get: - operationId: "get_work_edit" - tags: # TAGLINE - - works # TAGLINE - parameters: - - name: edit_id - in: path - required: true - <<: *FATCATUUID - responses: - 200: - description: Found Edit - schema: - $ref: "#/definitions/entity_edit" - <<: *ENTITYRESPONSES - /editgroup/{editgroup_id}/work/edit/{edit_id}: - parameters: - - name: editgroup_id - in: path - required: true - type: string - - name: edit_id - in: path - required: true - <<: *FATCATUUID - delete: - operationId: "delete_work_edit" - tags: # TAGLINE - - works # TAGLINE - security: - - Bearer: [] - responses: - 200: - description: Deleted Edit - schema: - $ref: "#/definitions/success" - <<: *ENTITYRESPONSES - <<: *AUTHRESPONSES - - /editor/{editor_id}: - parameters: - - name: editor_id - in: path - type: string - 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 - schema: - $ref: "#/definitions/editor" - 400: - description: Bad Request - schema: - $ref: "#/definitions/error_response" - 404: - description: Not Found - schema: - $ref: "#/definitions/error_response" - 500: - description: Generic Error - schema: - $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 - required: true - schema: - $ref: "#/definitions/editor" - security: - - Bearer: [] - responses: - 200: - description: Updated Editor - schema: - $ref: "#/definitions/editor" - 400: - description: Bad Request - schema: - $ref: "#/definitions/error_response" - 404: - description: Not Found - schema: - $ref: "#/definitions/error_response" - 500: - description: Generic Error - schema: - $ref: "#/definitions/error_response" - <<: *AUTHRESPONSES - /editor/{editor_id}/editgroups: - parameters: - - name: editor_id - in: path - type: string - 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 - type: integer - format: int64 - required: false - - name: before - in: query - 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 - schema: - type: array - items: - $ref: "#/definitions/editgroup" - 400: - description: Bad Request - schema: - $ref: "#/definitions/error_response" - 404: - description: Not Found - schema: - $ref: "#/definitions/error_response" - 500: - description: Generic Error - schema: - $ref: "#/definitions/error_response" - /editor/{editor_id}/annotations: - parameters: - - name: editor_id - in: path - required: true - <<: *FATCATIDENT - get: - operationId: "get_editor_annotations" - tags: # 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 - schema: - type: array - items: - $ref: "#/definitions/editgroup_annotation" - 400: - description: Bad Request - schema: - $ref: "#/definitions/error_response" - 404: - description: Not Found - schema: - $ref: "#/definitions/error_response" - 500: - description: Generic Error - schema: - $ref: "#/definitions/error_response" - <<: *AUTHRESPONSES - - /editgroup: - post: - operationId: "create_editgroup" - tags: # 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 - required: true - schema: - $ref: "#/definitions/editgroup" - security: - - Bearer: [] - responses: - 201: - description: Successfully Created - schema: - $ref: "#/definitions/editgroup" - 400: - description: Bad Request - schema: - $ref: "#/definitions/error_response" - 404: # added only for response type consistency - description: Not Found - schema: - $ref: "#/definitions/error_response" - 500: - description: Generic Error - schema: - $ref: "#/definitions/error_response" - <<: *AUTHRESPONSES - /editgroup/{editgroup_id}: - parameters: - - name: editgroup_id - in: path - required: true - <<: *FATCATIDENT - get: - operationId: "get_editgroup" - tags: # 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 - schema: - $ref: "#/definitions/editgroup" - 400: - description: Bad Request - schema: - $ref: "#/definitions/error_response" - 404: - description: Not Found - schema: - $ref: "#/definitions/error_response" - 500: - description: Generic Error - schema: - $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: - - name: editgroup - in: body - required: true - schema: - $ref: "#/definitions/editgroup" - - name: submit - in: query - type: boolean - required: false - responses: - 200: - description: Updated Editgroup - schema: - $ref: "#/definitions/editgroup" - 400: - description: Bad Request - schema: - $ref: "#/definitions/error_response" - 404: - description: Not Found - schema: - $ref: "#/definitions/error_response" - 500: - description: Generic Error - schema: - $ref: "#/definitions/error_response" - <<: *AUTHRESPONSES - /editgroup/{editgroup_id}/accept: - parameters: - - name: editgroup_id - in: path - required: true - <<: *FATCATIDENT - post: - operationId: "accept_editgroup" - tags: # 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: - 200: - description: Merged Successfully - schema: - $ref: "#/definitions/success" - 400: - description: Bad Request - schema: - $ref: "#/definitions/error_response" - 404: - description: Not Found - schema: - $ref: "#/definitions/error_response" - 409: - description: Edit Conflict - schema: - $ref: "#/definitions/error_response" - 500: - description: Generic Error - schema: - $ref: "#/definitions/error_response" - <<: *AUTHRESPONSES - /editgroup/{editgroup_id}/annotations: - parameters: - - name: editgroup_id - in: path - required: true - <<: *FATCATIDENT - get: - operationId: "get_editgroup_annotations" - tags: # 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 editgroup annotations: 'editors'" - responses: - 200: - description: Success - schema: - type: array - items: - $ref: "#/definitions/editgroup_annotation" - 400: - description: Bad Request - schema: - $ref: "#/definitions/error_response" - 404: - description: Not Found - schema: - $ref: "#/definitions/error_response" - 500: - description: Generic Error - schema: - $ref: "#/definitions/error_response" - <<: *AUTHRESPONSES - /editgroup/{editgroup_id}/annotation: - parameters: - - name: editgroup_id - in: path - required: true - <<: *FATCATIDENT - post: - operationId: "create_editgroup_annotation" - tags: # 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: - - name: annotation - in: body - required: true - schema: - $ref: "#/definitions/editgroup_annotation" - responses: - 201: - description: Created - schema: - $ref: "#/definitions/editgroup_annotation" - 400: - description: Bad Request - schema: - $ref: "#/definitions/error_response" - 404: - description: Not Found - schema: - $ref: "#/definitions/error_response" - 500: - description: Generic Error - schema: - $ref: "#/definitions/error_response" - <<: *AUTHRESPONSES - /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 - type: string - required: false - description: "List of sub-entities to expand in response. For editgroups: 'editors'" - - name: limit - in: query - 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 - schema: - type: array - items: - $ref: "#/definitions/editgroup" - 400: - description: Bad Request - schema: - $ref: "#/definitions/error_response" - 404: - description: Not Found - schema: - $ref: "#/definitions/error_response" - 500: - description: Generic Error - schema: - $ref: "#/definitions/error_response" - /changelog: - parameters: - - name: limit - in: query - type: integer - format: int64 - required: false - description: "Maximum count of changelog entries to return in response" - get: - operationId: "get_changelog" - tags: # 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 - schema: - type: array - items: - $ref: "#/definitions/changelog_entry" - 400: # added only for response type consistency - description: Bad Request - schema: - $ref: "#/definitions/error_response" - 500: - description: Generic Error - schema: - $ref: "#/definitions/error_response" - /changelog/{index}: - parameters: - - name: index - in: path - type: integer - format: int64 - required: true - description: "Changelog index of entry to return" - get: - operationId: "get_changelog_entry" - tags: # 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 - schema: - $ref: "#/definitions/changelog_entry" - 400: # added only for response type consistency - description: Bad Request - schema: - $ref: "#/definitions/error_response" - 404: - description: Not Found - schema: - $ref: "#/definitions/error_response" - 500: - description: Generic Error - schema: - $ref: "#/definitions/error_response" - /auth/oidc: - 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: [] - parameters: - - name: oidc_params - in: body - required: true - schema: - $ref: "#/definitions/auth_oidc" - responses: - 200: - description: Found - schema: - $ref: "#/definitions/auth_oidc_result" - 201: - description: Created - schema: - $ref: "#/definitions/auth_oidc_result" - 400: - description: Bad Request - schema: - $ref: "#/definitions/error_response" - 409: - description: Conflict - schema: - $ref: "#/definitions/error_response" - 500: - description: Generic Error - schema: - $ref: "#/definitions/error_response" - <<: *AUTHRESPONSES - /auth/check: - 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: [] - parameters: - - name: role - in: query - required: false - type: string - responses: - 200: - description: Success - schema: - $ref: "#/definitions/success" - 400: - description: Bad Request - schema: - $ref: "#/definitions/error_response" - 500: - description: Generic Error - schema: - $ref: "#/definitions/error_response" - <<: *AUTHRESPONSES - /auth/token/{editor_id}: - parameters: - - name: editor_id - in: path - type: string - required: true - post: - operationId: "create_auth_token" - tags: # TAGLINE - - auth # TAGLINE - description: | - Generate a new auth token for a given editor (internal method). - - This method is used by the web interface to generate API tokens for - users. It can not be called by editors (human or bot) to generate new - tokens for themselves, at least at this time. - security: - # required admin privs - - Bearer: [] - parameters: - - name: duration_seconds - in: query - type: integer - example: 86400 - required: false - description: "How long API token should be valid for (in seconds)" - responses: - 200: - description: Success - schema: - $ref: "#/definitions/auth_token_result" - 400: - description: Bad Request - schema: - $ref: "#/definitions/error_response" - 500: - description: Generic Error - schema: - $ref: "#/definitions/error_response" - <<: *AUTHRESPONSES |