summaryrefslogtreecommitdiffstats
path: root/rust/fatcat-openapi/api.yaml
diff options
context:
space:
mode:
Diffstat (limited to 'rust/fatcat-openapi/api.yaml')
-rw-r--r--rust/fatcat-openapi/api.yaml4074
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