--- swagger: "2.0" info: title: fatcat description: A scalable, versioned, API-oriented catalog of bibliographic entities and file metadata version: 0.1.0 schemes: [https] basePath: /v0 host: api.fatcat.wiki consumes: - application/json produces: - application/json securityDefinitions: Bearer: type: apiKey name: Authorization in: header tags: # TAGLINE - name: containers # TAGLINE descriptions: "Container entities: such as journals, conferences, book series" # TAGLINE - name: creators # TAGLINE descriptions: "Creator entities: such as authors" # TAGLINE - name: files # TAGLINE descriptions: "File entities" # TAGLINE - name: releases # TAGLINE descriptions: "Release entities: individual articles, pre-prints, books" # TAGLINE - name: works # TAGLINE descriptions: "Work entities: grouping releases which are variants of the same work" # TAGLINE - name: edit-lifecycle # TAGLINE descriptions: "Endpoints relating to global edit submission and history" # TAGLINE # don't want these to be rust types (at least for now) x-fatcat-ident: &FATCATIDENT type: string example: "q3nouwy3nnbsvo3h5klxsx4a7y" pattern: "[a-zA-Z2-7]{26}" minLength: 26 maxLength: 26 description: "base32-encoded unique identifier" x-fatcat-uuid: &FATCATUUID type: string example: "86daea5b-1b6b-432a-bb67-ea97795f80fe" pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}" minLength: 36 maxLength: 36 description: "UUID (lower-case, dash-separated, hex-encoded 128-bit)" x-issn: &FATCATISSN type: string example: "1234-5678" pattern: "\\d{4}-\\d{3}[0-9X]" minLength: 9 maxLength: 9 x-orcid: &FATCATORCID type: string example: "0000-0002-1825-0097" pattern: "\\d{4}-\\d{4}-\\d{4}-\\d{3}[\\dX]" minLength: 19 maxLength: 19 x-md5: &FATCATMD5 type: string example: "1b39813549077b2347c0f370c3864b40" pattern: "[a-f0-9]{32}" minLength: 32 maxLength: 32 x-sha1: &FATCATSHA1 type: string example: "e9dd75237c94b209dc3ccd52722de6931a310ba3" pattern: "[a-f0-9]{40}" minLength: 40 maxLength: 40 x-sha256: &FATCATSHA256 type: string example: "cb1c378f464d5935ddaa8de28446d82638396c61f042295d7fb85e3cccc9e452" pattern: "[a-f0-9]{64}" minLength: 64 maxLength: 64 # Common properties across entities x-entity-props: &ENTITYPROPS state: type: string enum: ["wip", "active", "redirect", "deleted"] ident: <<: *FATCATIDENT revision: <<: *FATCATUUID redirect: <<: *FATCATIDENT extra: type: object additionalProperties: {} edit_extra: type: object additionalProperties: {} definitions: error_response: type: object required: - message properties: message: type: string example: "A really confusing, totally unexpected thing happened" success: type: object required: - message properties: message: type: string example: "The computers did the thing successfully!" container_entity: type: object # required for creation: name properties: <<: *ENTITYPROPS name: type: string example: "Journal of Important Results" description: "Required for valid entities" publisher: type: string example: "Society of Curious Students" issnl: <<: *FATCATISSN wikidata_qid: type: string abbrev: type: string coden: type: string creator_entity: type: object # required for creation: display_name properties: <<: *ENTITYPROPS display_name: type: string example: "Grace Hopper" description: "Required for valid entities" given_name: type: string surname: type: string orcid: <<: *FATCATORCID wikidata_qid: type: string file_entity: type: object properties: <<: *ENTITYPROPS size: type: integer example: 1048576 format: int64 md5: <<: *FATCATMD5 sha1: <<: *FATCATSHA1 sha256: <<: *FATCATSHA256 urls: type: array items: type: object required: - url - rel properties: url: type: string format: url example: "https://example.edu/~frau/prcding.pdf" rel: type: string example: "webarchive" mimetype: type: string example: "application/pdf" release_ids: type: array items: <<: *FATCATIDENT fileset_entity: type: object properties: <<: *ENTITYPROPS manifest: # limit of 200 files, at least to start type: array items: type: object required: - path - size properties: path: type: string example: "img/cat.png" size: type: integer example: 1048576 format: int64 md5: <<: *FATCATMD5 sha1: <<: *FATCATSHA1 sha256: <<: *FATCATSHA256 extra: type: object additionalProperties: {} urls: type: array items: type: object required: - url - rel properties: url: type: string format: url example: "https://example.edu/~frau/prcding.pdf" rel: type: string example: "webarchive" release_ids: type: array items: <<: *FATCATIDENT webcapture_entity: type: object properties: <<: *ENTITYPROPS cdx: # limit of 200 CDX lines, at least to start type: array items: type: object required: - surt - timestamp - url - sha1 properties: surt: type: string example: "org,asheesh)/apus/ch1/node15.html" timestamp: type: string example: "20020429162520" url: type: string # NOTE: not format:url to allow alternatives example: "http://www.asheesh.org:80/APUS/ch1/node15.html" mimetype: type: string example: "text/html" status_code: type: integer example: 200 format: int64 sha1: <<: *FATCATSHA1 sha256: <<: *FATCATSHA256 archive_urls: type: array items: type: object required: - url - rel properties: url: type: string format: url example: "https://web.archive.org/web/" rel: type: string example: "wayback" original_url: type: string format: url example: "http://asheesh.org" timestamp: type: string format: date-time release_ids: type: array items: <<: *FATCATIDENT release_entity: type: object # required for creation: title properties: <<: *ENTITYPROPS title: type: string description: "Required for valid entities" work_id: type: string example: "q3nouwy3nnbsvo3h5klxsx4a7y" container: $ref: "#/definitions/container_entity" description: "Optional; GET-only" files: description: "Optional; GET-only" type: array items: $ref: "#/definitions/file_entity" filesets: description: "Optional; GET-only" type: array items: $ref: "#/definitions/fileset_entity" webcaptures: description: "Optional; GET-only" type: array items: $ref: "#/definitions/webcapture_entity" container_id: type: string example: "q3nouwy3nnbsvo3h5klxsx4a7y" release_type: type: string example: "book" release_status: type: string example: "preprint" release_date: type: string format: date release_year: type: integer example: 2014 format: int64 doi: type: string #format: custom example: "10.1234/abcde.789" wikidata_qid: type: string isbn13: type: string #format: custom pmid: type: string pmcid: type: string core_id: type: string #format: custom volume: type: string issue: type: string example: "12" pages: type: string publisher: type: string language: description: "Two-letter RFC1766/ISO639-1 language code, with extensions" type: string contribs: type: array items: $ref: "#/definitions/release_contrib" refs: type: array items: $ref: "#/definitions/release_ref" abstracts: type: array items: type: object properties: sha1: <<: *FATCATSHA1 content: type: string example: "<jats:p>Some abstract thing goes here</jats:p>" mimetype: type: string example: "application/xml+jats" lang: type: string example: "en" 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 ident: <<: *FATCATIDENT revision: <<: *FATCATUUID prev_revision: <<: *FATCATUUID redirect_ident: <<: *FATCATIDENT editgroup_id: <<: *FATCATIDENT extra: type: object additionalProperties: {} editor: type: object required: - username properties: editor_id: <<: *FATCATIDENT username: type: string example: "zerocool93" editgroup: type: object required: - editor_id properties: editgroup_id: <<: *FATCATIDENT editor_id: <<: *FATCATIDENT description: type: string extra: type: object additionalProperties: {} edits: type: object 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" changelog_entry: type: object required: - index - editgroup_id - timestamp properties: index: type: integer format: int64 editgroup_id: type: string example: "q3nouwy3nnbsvo3h5klxsx4a7y" timestamp: type: string format: date-time editgroup: $ref: "#/definitions/editgroup" release_ref: type: object properties: index: type: integer format: int64 target_release_id: <<: *FATCATIDENT extra: type: object additionalProperties: {} key: type: string year: type: integer format: int64 container_name: type: string title: type: string locator: type: string example: "p123" release_contrib: type: object properties: index: type: integer format: int64 creator_id: type: string #format: ident creator: $ref: "#/definitions/creator_entity" description: "Optional; GET-only" raw_name: type: string extra: type: object additionalProperties: {} role: type: string x-entity-responses: &ENTITYRESPONSES 400: description: Bad Request schema: $ref: "#/definitions/error_response" 401: description: Not Authorized # "Authentication information is missing or invalid" schema: $ref: "#/definitions/error_response" headers: WWW_Authenticate: type: string 404: description: Not Found schema: $ref: "#/definitions/error_response" 500: description: Generic Error schema: $ref: "#/definitions/error_response" paths: /container: post: operationId: "create_container" tags: # TAGLINE - containers # TAGLINE parameters: - name: entity in: body required: true schema: $ref: "#/definitions/container_entity" - name: editgroup_id in: query required: false type: string security: - Bearer: [] responses: 201: description: Created Entity schema: $ref: "#/definitions/entity_edit" <<: *ENTITYRESPONSES /container/batch: post: operationId: "create_container_batch" tags: # TAGLINE - containers # TAGLINE parameters: - name: autoaccept in: query type: boolean required: false description: "If true, and editor is authorized, batch is accepted all at once" - name: editgroup_id in: query type: string required: false description: "Editgroup to auto-accept and apply to all entities (required if 'autoaccept' is True)" - name: entity_list in: body required: true schema: type: array items: $ref: "#/definitions/container_entity" security: - Bearer: [] responses: 201: description: Created Entities schema: type: array items: $ref: "#/definitions/entity_edit" <<: *ENTITYRESPONSES /container/{ident}: parameters: - name: ident in: path type: string required: true get: operationId: "get_container" tags: # TAGLINE - containers # TAGLINE 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 put: operationId: "update_container" tags: # TAGLINE - containers # TAGLINE parameters: - name: entity in: body required: true schema: $ref: "#/definitions/container_entity" - name: editgroup_id in: query required: false type: string security: - Bearer: [] responses: 200: description: Updated Entity schema: $ref: "#/definitions/entity_edit" <<: *ENTITYRESPONSES delete: operationId: "delete_container" tags: # TAGLINE - containers # TAGLINE parameters: - name: editgroup_id in: query required: false type: string security: - Bearer: [] responses: 200: description: Deleted Entity schema: $ref: "#/definitions/entity_edit" <<: *ENTITYRESPONSES /container/rev/{rev_id}: parameters: - name: rev_id in: path required: true <<: *FATCATUUID get: operationId: "get_container_revision" tags: # TAGLINE - containers # TAGLINE 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 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 get: tags: # TAGLINE - containers # TAGLINE 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: tags: # TAGLINE - containers # TAGLINE operationId: "get_container_redirects" responses: 200: description: Found Entity Redirects schema: type: array items: type: string #format: ident <<: *ENTITYRESPONSES /container/lookup: get: operationId: "lookup_container" tags: # TAGLINE - containers # TAGLINE parameters: - name: issnl in: query required: false <<: *FATCATISSN - name: wikidata_qid in: query required: false - name: expand in: query type: string required: false description: "List of sub-entities to expand in response." - name: hide in: query type: string required: false description: "List of entity fields to elide in response. For container, none accepted (yet)." responses: 200: description: Found Entity schema: $ref: "#/definitions/container_entity" <<: *ENTITYRESPONSES /container/edit/{edit_id}: get: operationId: "get_container_edit" tags: # TAGLINE - containers # TAGLINE parameters: - name: edit_id in: path required: true <<: *FATCATUUID responses: 200: description: Found Edit schema: $ref: "#/definitions/entity_edit" <<: *ENTITYRESPONSES delete: operationId: "delete_container_edit" tags: # TAGLINE - containers # TAGLINE parameters: - name: edit_id in: path required: true <<: *FATCATUUID responses: 200: description: Deleted Edit schema: $ref: "#/definitions/success" <<: *ENTITYRESPONSES /creator: post: operationId: "create_creator" tags: # TAGLINE - creators # TAGLINE parameters: - name: entity in: body required: true schema: $ref: "#/definitions/creator_entity" - name: editgroup_id in: query required: false type: string security: - Bearer: [] responses: 201: description: Created Entity schema: $ref: "#/definitions/entity_edit" <<: *ENTITYRESPONSES /creator/batch: post: operationId: "create_creator_batch" tags: # TAGLINE - creators # TAGLINE parameters: - name: autoaccept in: query type: boolean required: false description: "If true, and editor is authorized, batch is accepted all at once" - name: editgroup_id in: query type: string required: false description: "Editgroup to auto-accept and apply to all entities (required if 'autoaccept' is True)" - name: entity_list in: body required: true schema: type: array items: $ref: "#/definitions/creator_entity" security: - Bearer: [] responses: 201: description: Created Entities schema: type: array items: $ref: "#/definitions/entity_edit" <<: *ENTITYRESPONSES /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 containers, none accepted (yet)." responses: 200: description: Found Entity schema: $ref: "#/definitions/creator_entity" <<: *ENTITYRESPONSES put: operationId: "update_creator" tags: # TAGLINE - creators # TAGLINE parameters: - name: entity in: body required: true schema: $ref: "#/definitions/creator_entity" - name: editgroup_id in: query required: false type: string security: - Bearer: [] responses: 200: description: Updated Entity schema: $ref: "#/definitions/entity_edit" <<: *ENTITYRESPONSES delete: operationId: "delete_creator" tags: # TAGLINE - creators # TAGLINE parameters: - name: editgroup_id in: query required: false type: string security: - Bearer: [] responses: 200: description: Deleted Entity schema: $ref: "#/definitions/entity_edit" <<: *ENTITYRESPONSES /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. 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 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. For creators, none implemented yet." get: operationId: "get_creator_releases" tags: # TAGLINE - creators # TAGLINE 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: tags: # TAGLINE - creators # TAGLINE operationId: "get_creator_redirects" responses: 200: description: Found Entity Redirects schema: type: array items: type: string #format: ident <<: *ENTITYRESPONSES /creator/lookup: get: operationId: "lookup_creator" tags: # TAGLINE - creators # TAGLINE parameters: - name: orcid in: query required: false <<: *FATCATORCID - name: wikidata_qid in: query required: false - name: expand in: query type: string required: false description: "List of sub-entities to expand in response." - name: hide in: query type: string required: false description: "List of entity fields to elide in response. For creator, none accepted (yet)." 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 delete: operationId: "delete_creator_edit" tags: # TAGLINE - creators # TAGLINE parameters: - name: edit_id in: path required: true <<: *FATCATUUID responses: 200: description: Deleted Edit schema: $ref: "#/definitions/success" <<: *ENTITYRESPONSES /file: post: operationId: "create_file" tags: # TAGLINE - files # TAGLINE parameters: - name: entity in: body required: true schema: $ref: "#/definitions/file_entity" - name: editgroup_id in: query required: false type: string security: - Bearer: [] responses: 201: description: Created Entity schema: $ref: "#/definitions/entity_edit" <<: *ENTITYRESPONSES /file/batch: post: operationId: "create_file_batch" tags: # TAGLINE - files # TAGLINE parameters: - name: autoaccept in: query type: boolean required: false description: "If true, and editor is authorized, batch is accepted all at once" - name: editgroup_id in: query type: string required: false description: "Editgroup to auto-accept and apply to all entities (required if 'autoaccept' is True)" - name: entity_list in: body required: true schema: type: array items: $ref: "#/definitions/file_entity" security: - Bearer: [] responses: 201: description: Created Entities schema: type: array items: $ref: "#/definitions/entity_edit" <<: *ENTITYRESPONSES /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, none accepted (yet)." - 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 put: operationId: "update_file" tags: # TAGLINE - files # TAGLINE parameters: - name: entity in: body required: true schema: $ref: "#/definitions/file_entity" - name: editgroup_id in: query required: false type: string security: - Bearer: [] responses: 200: description: Updated Entity schema: $ref: "#/definitions/entity_edit" <<: *ENTITYRESPONSES delete: operationId: "delete_file" tags: # TAGLINE - files # TAGLINE parameters: - name: editgroup_id in: query required: false type: string security: - Bearer: [] responses: 200: description: Deleted Entity schema: $ref: "#/definitions/entity_edit" <<: *ENTITYRESPONSES /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. For files, none accepted (yet)." - 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 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: tags: # TAGLINE - files # TAGLINE operationId: "get_file_redirects" responses: 200: description: Found Entity Redirects schema: type: array items: type: string #format: ident <<: *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." - 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 /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 delete: operationId: "delete_file_edit" tags: # TAGLINE - files # TAGLINE parameters: - name: edit_id in: path required: true <<: *FATCATUUID responses: 200: description: Deleted Edit schema: $ref: "#/definitions/success" <<: *ENTITYRESPONSES /fileset: post: operationId: "create_fileset" tags: # TAGLINE - filesets # TAGLINE parameters: - name: entity in: body required: true schema: $ref: "#/definitions/fileset_entity" - name: editgroup_id in: query required: false type: string responses: 201: description: Created Entity schema: $ref: "#/definitions/entity_edit" <<: *ENTITYRESPONSES /fileset/batch: post: operationId: "create_fileset_batch" tags: # TAGLINE - filesets # TAGLINE parameters: - name: autoaccept in: query type: boolean required: false description: "If true, and editor is authorized, batch is accepted all at once" - name: editgroup_id in: query type: string required: false description: "Editgroup to auto-accept and apply to all entities (required if 'autoaccept' is True)" - name: entity_list in: body required: true schema: type: array items: $ref: "#/definitions/fileset_entity" responses: 201: description: Created Entities schema: type: array items: $ref: "#/definitions/entity_edit" <<: *ENTITYRESPONSES /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, none accepted (yet)." - 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 put: operationId: "update_fileset" tags: # TAGLINE - filesets # TAGLINE parameters: - name: entity in: body required: true schema: $ref: "#/definitions/fileset_entity" - name: editgroup_id in: query required: false type: string responses: 200: description: Updated Entity schema: $ref: "#/definitions/entity_edit" <<: *ENTITYRESPONSES delete: operationId: "delete_fileset" tags: # TAGLINE - filesets # TAGLINE parameters: - name: editgroup_id in: query required: false type: string responses: 200: description: Deleted Entity schema: $ref: "#/definitions/entity_edit" <<: *ENTITYRESPONSES /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. For filesets, none accepted (yet)." - 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 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: tags: # TAGLINE - filesets # TAGLINE operationId: "get_fileset_redirects" responses: 200: description: Found Entity Redirects schema: type: array items: type: string #format: ident <<: *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 delete: operationId: "delete_fileset_edit" tags: # TAGLINE - filesets # TAGLINE parameters: - name: edit_id in: path required: true <<: *FATCATUUID responses: 200: description: Deleted Edit schema: $ref: "#/definitions/success" <<: *ENTITYRESPONSES /webcapture: post: operationId: "create_webcapture" tags: # TAGLINE - webcaptures # TAGLINE parameters: - name: entity in: body required: true schema: $ref: "#/definitions/webcapture_entity" - name: editgroup_id in: query required: false type: string responses: 201: description: Created Entity schema: $ref: "#/definitions/entity_edit" <<: *ENTITYRESPONSES /webcapture/batch: post: operationId: "create_webcapture_batch" tags: # TAGLINE - webcaptures # TAGLINE parameters: - name: autoaccept in: query type: boolean required: false description: "If true, and editor is authorized, batch is accepted all at once" - name: editgroup_id in: query type: string required: false description: "Editgroup to auto-accept and apply to all entities (required if 'autoaccept' is True)" - name: entity_list in: body required: true schema: type: array items: $ref: "#/definitions/webcapture_entity" responses: 201: description: Created Entities schema: type: array items: $ref: "#/definitions/entity_edit" <<: *ENTITYRESPONSES /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, none accepted (yet)." - 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 put: operationId: "update_webcapture" tags: # TAGLINE - webcaptures # TAGLINE parameters: - name: entity in: body required: true schema: $ref: "#/definitions/webcapture_entity" - name: editgroup_id in: query required: false type: string responses: 200: description: Updated Entity schema: $ref: "#/definitions/entity_edit" <<: *ENTITYRESPONSES delete: operationId: "delete_webcapture" tags: # TAGLINE - webcaptures # TAGLINE parameters: - name: editgroup_id in: query required: false type: string responses: 200: description: Deleted Entity schema: $ref: "#/definitions/entity_edit" <<: *ENTITYRESPONSES /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. For webcaptures, none accepted (yet)." - 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 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: tags: # TAGLINE - webcaptures # TAGLINE operationId: "get_webcapture_redirects" responses: 200: description: Found Entity Redirects schema: type: array items: type: string #format: ident <<: *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 delete: operationId: "delete_webcapture_edit" tags: # TAGLINE - webcaptures # TAGLINE parameters: - name: edit_id in: path required: true <<: *FATCATUUID responses: 200: description: Deleted Edit schema: $ref: "#/definitions/success" <<: *ENTITYRESPONSES /release: post: operationId: "create_release" tags: # TAGLINE - releases # TAGLINE parameters: - name: entity in: body required: true schema: $ref: "#/definitions/release_entity" - name: editgroup_id in: query required: false type: string responses: 201: description: Created Entity schema: $ref: "#/definitions/entity_edit" <<: *ENTITYRESPONSES /release/batch: post: operationId: "create_release_batch" tags: # TAGLINE - releases # TAGLINE parameters: - name: autoaccept in: query type: boolean required: false description: "If true, and editor is authorized, batch is accepted all at once" - name: editgroup_id in: query type: string required: false description: "Editgroup to auto-accept and apply to all entities (required if 'autoaccept' is True)" - name: entity_list in: body required: true schema: type: array items: $ref: "#/definitions/release_entity" responses: 201: description: Created Entities schema: type: array items: $ref: "#/definitions/entity_edit" <<: *ENTITYRESPONSES /release/{ident}: parameters: - name: ident in: path type: string required: true get: operationId: "get_release" tags: # TAGLINE - releases # TAGLINE 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 releases, 'abstracts', 'refs', and 'contribs' are valid." responses: 200: description: Found Entity schema: $ref: "#/definitions/release_entity" <<: *ENTITYRESPONSES put: operationId: "update_release" tags: # TAGLINE - releases # TAGLINE parameters: - name: entity in: body required: true schema: $ref: "#/definitions/release_entity" - name: editgroup_id in: query required: false type: string responses: 200: description: Updated Entity schema: $ref: "#/definitions/entity_edit" <<: *ENTITYRESPONSES delete: operationId: "delete_release" tags: # TAGLINE - releases # TAGLINE parameters: - name: editgroup_id in: query required: false type: string responses: 200: description: Deleted Entity schema: $ref: "#/definitions/entity_edit" <<: *ENTITYRESPONSES /release/rev/{rev_id}: parameters: - name: rev_id in: path required: true <<: *FATCATUUID get: operationId: "get_release_revision" tags: # TAGLINE - releases # TAGLINE parameters: - name: expand in: query type: string required: false description: "List of sub-entities to expand in response. For releases, none accepted (yet)." - name: hide in: query type: string required: false description: "List of entity fields to elide in response. For releases, none accepted (yet)." 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 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. For files, none accepted (yet)." get: operationId: "get_release_files" tags: # TAGLINE - releases # TAGLINE 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. For filesets, 'manifest' is valid." get: operationId: "get_release_filesets" tags: # TAGLINE - releases # TAGLINE 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. For webcaptures, 'cdx' is valid." get: operationId: "get_release_webcaptures" tags: # TAGLINE - releases # TAGLINE 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: tags: # TAGLINE - releases # TAGLINE operationId: "get_release_redirects" responses: 200: description: Found Entity Redirects schema: type: array items: type: string #format: ident <<: *ENTITYRESPONSES /release/lookup: get: operationId: "lookup_release" tags: # TAGLINE - releases # TAGLINE parameters: - 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_id in: query type: string required: false - name: expand in: query type: string required: false description: "List of sub-entities to expand in response." - name: hide in: query type: string required: false description: "List of sub-entities to expand in response. For releases, 'files', 'filesets, 'webcaptures', 'container', and 'creators' are valid." responses: 200: description: Found Entity schema: $ref: "#/definitions/release_entity" <<: *ENTITYRESPONSES /release/edit/{edit_id}: get: operationId: "get_release_edit" tags: # TAGLINE - releases # TAGLINE parameters: - name: edit_id in: path required: true <<: *FATCATUUID responses: 200: description: Found Edit schema: $ref: "#/definitions/entity_edit" <<: *ENTITYRESPONSES delete: operationId: "delete_release_edit" tags: # TAGLINE - releases # TAGLINE parameters: - name: edit_id in: path required: true <<: *FATCATUUID responses: 200: description: Deleted Edit schema: $ref: "#/definitions/success" <<: *ENTITYRESPONSES /work: post: operationId: "create_work" tags: # TAGLINE - releases # TAGLINE parameters: - name: entity in: body required: true schema: $ref: "#/definitions/work_entity" - name: editgroup_id in: query required: false type: string responses: 201: description: Created Entity schema: $ref: "#/definitions/entity_edit" <<: *ENTITYRESPONSES /work/batch: post: operationId: "create_work_batch" tags: # TAGLINE - works # TAGLINE parameters: - name: autoaccept in: query type: boolean required: false description: "If true, and editor is authorized, batch is accepted all at once" - name: editgroup_id in: query type: string required: false description: "Editgroup to auto-accept and apply to all entities (required if 'autoaccept' is True)" - name: entity_list in: body required: true schema: type: array items: $ref: "#/definitions/work_entity" responses: 201: description: Created Entities schema: type: array items: $ref: "#/definitions/entity_edit" <<: *ENTITYRESPONSES /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 put: operationId: "update_work" tags: # TAGLINE - works # TAGLINE parameters: - name: entity in: body required: true schema: $ref: "#/definitions/work_entity" - name: editgroup_id in: query required: false type: string responses: 200: description: Updated Entity schema: $ref: "#/definitions/entity_edit" <<: *ENTITYRESPONSES delete: operationId: "delete_work" tags: # TAGLINE - works # TAGLINE parameters: - name: editgroup_id in: query required: false type: string responses: 200: description: Deleted Entity schema: $ref: "#/definitions/entity_edit" <<: *ENTITYRESPONSES /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. 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 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: tags: # TAGLINE - works # TAGLINE operationId: "get_work_redirects" responses: 200: description: Found Entity Redirects schema: type: array items: type: string #format: ident <<: *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. For works, none implemented yet." get: operationId: "get_work_releases" tags: # TAGLINE - works # TAGLINE 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 delete: operationId: "delete_work_edit" tags: # TAGLINE - works # TAGLINE parameters: - name: edit_id in: path required: true <<: *FATCATUUID responses: 200: description: Deleted Edit schema: $ref: "#/definitions/success" <<: *ENTITYRESPONSES /editor/{editor_id}: parameters: - name: editor_id in: path type: string required: true get: operationId: "get_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" /editor/{editor_id}/changelog: parameters: - name: editor_id in: path type: string required: true get: operationId: "get_editor_changelog" responses: 200: description: Found schema: type: array items: $ref: "#/definitions/changelog_entry" 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" /editgroup: post: operationId: "create_editgroup" tags: # TAGLINE - edit-lifecycle # TAGLINE parameters: - name: editgroup in: body required: true schema: $ref: "#/definitions/editgroup" responses: 201: description: Successfully Created schema: $ref: "#/definitions/editgroup" 400: description: Bad Request schema: $ref: "#/definitions/error_response" 500: description: Generic Error schema: $ref: "#/definitions/error_response" /editgroup/{editgroup_id}: parameters: - name: editgroup_id in: path required: true <<: *FATCATIDENT get: operationId: "get_editgroup" tags: # TAGLINE - edit-lifecycle # TAGLINE 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" /editgroup/{editgroup_id}/accept: parameters: - name: editgroup_id in: path required: true <<: *FATCATIDENT post: operationId: "accept_editgroup" tags: # TAGLINE - edit-lifecycle # TAGLINE 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" /changelog: parameters: - name: limit in: query type: integer format: int64 required: false get: operationId: "get_changelog" tags: # TAGLINE - edit-lifecycle # TAGLINE responses: 200: description: Success schema: type: array items: $ref: "#/definitions/changelog_entry" 500: description: Generic Error schema: $ref: "#/definitions/error_response" /changelog/{index}: parameters: - name: index in: path type: integer format: int64 required: true get: operationId: "get_changelog_entry" tags: # TAGLINE - edit-lifecycle # TAGLINE responses: 200: description: Found Changelog Entry schema: $ref: "#/definitions/changelog_entry" 404: description: Not Found schema: $ref: "#/definitions/error_response" 500: description: Generic Error schema: $ref: "#/definitions/error_response"