--- swagger: "2.0" info: title: fatcat description: A scalable, versioned, API-oriented catalog of bibliographic entities and file metadata version: 0.1.0 # Actually HTTPS in QA and production schemes: [http] basePath: /v0 #host: api.fatcat.wiki consumes: - application/json produces: - application/json tags: - name: containers descriptions: "Container entities: such as journals, conferences, book series" - name: creators descriptions: "Creator entities: such as authors" - name: files descriptions: "File entities" - name: releases descriptions: "Release entities: individual articles, pre-prints, books" - name: works descriptions: "Work entities: grouping releases which are variants of the same work" - name: edit-lifecycle descriptions: "Endpoints relating to global edit submission and history" # 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 # 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: - name properties: <<: *ENTITYPROPS name: type: string example: "Journal of Important Results" 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: - display_name properties: <<: *ENTITYPROPS display_name: type: string example: "Grace Hopper" 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 sha1: type: string #format: custom example: "f013d66c7f6817d08b7eb2a93e6d0440c1f3e7f8" md5: type: string #format: custom example: "d41efcc592d1e40ac13905377399eb9b" sha256: type: string #format: custom example: "a77e4c11a57f1d757fca5754a8f83b5d4ece49a2d28596889127c1a2f3f28832" 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" releases: type: array items: type: string #format: uuid release_entity: type: object required: - title properties: <<: *ENTITYPROPS title: type: string 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" container_id: type: string example: "q3nouwy3nnbsvo3h5klxsx4a7y" release_type: type: string example: "book" release_status: type: string example: "preprint" release_date: type: string format: date doi: type: string #format: custom example: "10.1234/abcde.789" isbn13: type: string #format: custom core_id: type: string #format: custom pmid: type: string pmcid: type: string wikidata_qid: type: string 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: type: string example: "3f242a192acc258bdfdb151943419437f440c313" 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: type: integer example: 847 format: int64 ident: type: string example: "q3nouwy3nnbsvo3h5klxsx4a7y" revision: type: string #format: uuid example: "86daea5b-1b6b-432a-bb67-ea97795f80fe" prev_revision: type: string #format: uuid example: "86daea5b-1b6b-432a-bb67-ea97795f80fe" redirect_ident: type: string example: "q3nouwy3nnbsvo3h5klxsx4a7y" #format: ident editgroup_id: type: string example: "q3nouwy3nnbsvo3h5klxsx4a7y" extra: type: object additionalProperties: {} editor: type: object required: - username properties: id: type: string example: "q3nouwy3nnbsvo3h5klxsx4a7y" username: type: string example: "zerocool93" editgroup: type: object required: - editor_id properties: 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" 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: type: string #format: ident 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 stats_response: type: object properties: extra: type: object additionalProperties: {} 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: /container: post: operationId: "create_container" tags: - containers parameters: - name: entity in: body required: true schema: $ref: "#/definitions/container_entity" - name: editgroup in: query required: false type: string responses: 201: description: Created Entity schema: $ref: "#/definitions/entity_edit" <<: *ENTITYRESPONSES /container/batch: post: operationId: "create_container_batch" tags: - containers parameters: - name: autoaccept in: query type: boolean required: false description: "If true, and editor is authorized, batch is accepted all at once" - name: editgroup 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" responses: 201: description: Created Entities schema: type: array items: $ref: "#/definitions/entity_edit" <<: *ENTITYRESPONSES /container/{id}: parameters: - name: id in: path type: string required: true get: operationId: "get_container" tags: - containers parameters: - name: expand in: query type: string required: false description: "List of sub-entities to expand in response. For now, only 'all' accepted." responses: 200: description: Found Entity schema: $ref: "#/definitions/container_entity" <<: *ENTITYRESPONSES put: operationId: "update_container" tags: - containers parameters: - name: entity in: body required: true schema: $ref: "#/definitions/container_entity" - name: editgroup in: query required: false type: string responses: 200: description: Updated Entity schema: $ref: "#/definitions/entity_edit" <<: *ENTITYRESPONSES delete: operationId: "delete_container" tags: - containers parameters: - name: editgroup in: query required: false type: string responses: 200: description: Deleted Entity schema: $ref: "#/definitions/entity_edit" <<: *ENTITYRESPONSES /container/{id}/history: parameters: - name: id in: path type: string required: true - name: limit in: query type: integer format: int64 required: false get: tags: - containers operationId: "get_container_history" responses: 200: description: Found Entity History schema: type: array items: $ref: "#/definitions/entity_history_entry" <<: *ENTITYRESPONSES /container/lookup: get: operationId: "lookup_container" tags: - containers parameters: - name: issnl in: query required: true <<: *FATCATISSN responses: 200: description: Found Entity schema: $ref: "#/definitions/container_entity" <<: *ENTITYRESPONSES /creator: post: operationId: "create_creator" tags: - creators parameters: - name: entity in: body required: true schema: $ref: "#/definitions/creator_entity" - name: editgroup in: query required: false type: string responses: 201: description: Created Entity schema: $ref: "#/definitions/entity_edit" <<: *ENTITYRESPONSES /creator/batch: post: operationId: "create_creator_batch" tags: - creators parameters: - name: autoaccept in: query type: boolean required: false description: "If true, and editor is authorized, batch is accepted all at once" - name: editgroup 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" responses: 201: description: Created Entities schema: type: array items: $ref: "#/definitions/entity_edit" <<: *ENTITYRESPONSES /creator/{id}: parameters: - name: id in: path type: string required: true get: operationId: "get_creator" tags: - creators parameters: - name: expand in: query type: string required: false description: "List of sub-entities to expand in response. For now, only 'all' accepted." responses: 200: description: Found Entity schema: $ref: "#/definitions/creator_entity" <<: *ENTITYRESPONSES put: operationId: "update_creator" tags: - creators parameters: - name: entity in: body required: true schema: $ref: "#/definitions/creator_entity" - name: editgroup in: query required: false type: string responses: 200: description: Updated Entity schema: $ref: "#/definitions/entity_edit" <<: *ENTITYRESPONSES delete: operationId: "delete_creator" tags: - creators parameters: - name: editgroup in: query required: false type: string responses: 200: description: Deleted Entity schema: $ref: "#/definitions/entity_edit" <<: *ENTITYRESPONSES /creator/{id}/history: parameters: - name: id in: path type: string required: true - name: limit in: query type: integer format: int64 required: false get: operationId: "get_creator_history" tags: - creators responses: 200: description: Found Entity History schema: type: array items: $ref: "#/definitions/entity_history_entry" <<: *ENTITYRESPONSES /creator/{id}/releases: parameters: - name: id in: path type: string required: true get: operationId: "get_creator_releases" tags: - creators responses: 200: description: Found schema: type: array items: $ref: "#/definitions/release_entity" <<: *ENTITYRESPONSES /creator/lookup: get: operationId: "lookup_creator" tags: - creators parameters: - name: orcid in: query required: true <<: *FATCATORCID responses: 200: description: Found Entity schema: $ref: "#/definitions/creator_entity" <<: *ENTITYRESPONSES /file: post: operationId: "create_file" tags: - files parameters: - name: entity in: body required: true schema: $ref: "#/definitions/file_entity" - name: editgroup in: query required: false type: string responses: 201: description: Created Entity schema: $ref: "#/definitions/entity_edit" <<: *ENTITYRESPONSES /file/batch: post: operationId: "create_file_batch" tags: - files parameters: - name: autoaccept in: query type: boolean required: false description: "If true, and editor is authorized, batch is accepted all at once" - name: editgroup 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" responses: 201: description: Created Entities schema: type: array items: $ref: "#/definitions/entity_edit" <<: *ENTITYRESPONSES /file/{id}: parameters: - name: id in: path type: string required: true get: operationId: "get_file" tags: - files parameters: - name: expand in: query type: string required: false description: "List of sub-entities to expand in response. For now, only 'all' accepted." responses: 200: description: Found Entity schema: $ref: "#/definitions/file_entity" <<: *ENTITYRESPONSES put: operationId: "update_file" tags: - files parameters: - name: entity in: body required: true schema: $ref: "#/definitions/file_entity" - name: editgroup in: query required: false type: string responses: 200: description: Updated Entity schema: $ref: "#/definitions/entity_edit" <<: *ENTITYRESPONSES delete: operationId: "delete_file" tags: - files parameters: - name: editgroup in: query required: false type: string responses: 200: description: Deleted Entity schema: $ref: "#/definitions/entity_edit" <<: *ENTITYRESPONSES /file/{id}/history: parameters: - name: id in: path type: string required: true - name: limit in: query type: integer format: int64 required: false get: operationId: "get_file_history" tags: - files responses: 200: description: Found Entity History schema: type: array items: $ref: "#/definitions/entity_history_entry" <<: *ENTITYRESPONSES /file/lookup: get: operationId: "lookup_file" tags: - files parameters: - name: sha1 in: query type: string required: true responses: 200: description: Found Entity schema: $ref: "#/definitions/file_entity" <<: *ENTITYRESPONSES /release: post: operationId: "create_release" tags: - releases parameters: - name: entity in: body required: true schema: $ref: "#/definitions/release_entity" - name: editgroup 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: - releases parameters: - name: autoaccept in: query type: boolean required: false description: "If true, and editor is authorized, batch is accepted all at once" - name: editgroup 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/{id}: parameters: - name: id in: path type: string required: true get: operationId: "get_release" tags: - releases parameters: - name: expand in: query type: string required: false description: "List of sub-entities to expand in response. For now, only 'all' accepted." responses: 200: description: Found Entity schema: $ref: "#/definitions/release_entity" <<: *ENTITYRESPONSES put: operationId: "update_release" tags: - releases parameters: - name: entity in: body required: true schema: $ref: "#/definitions/release_entity" - name: editgroup in: query required: false type: string responses: 200: description: Updated Entity schema: $ref: "#/definitions/entity_edit" <<: *ENTITYRESPONSES delete: operationId: "delete_release" tags: - releases parameters: - name: editgroup in: query required: false type: string responses: 200: description: Deleted Entity schema: $ref: "#/definitions/entity_edit" <<: *ENTITYRESPONSES /release/{id}/history: parameters: - name: id in: path type: string required: true - name: limit in: query type: integer format: int64 required: false get: operationId: "get_release_history" tags: - releases responses: 200: description: Found Entity History schema: type: array items: $ref: "#/definitions/entity_history_entry" <<: *ENTITYRESPONSES /release/{id}/files: parameters: - name: id in: path type: string required: true get: operationId: "get_release_files" tags: - releases responses: 200: description: Found schema: type: array items: $ref: "#/definitions/file_entity" <<: *ENTITYRESPONSES /release/lookup: get: operationId: "lookup_release" tags: - releases parameters: - name: doi in: query type: string required: true responses: 200: description: Found Entity schema: $ref: "#/definitions/release_entity" <<: *ENTITYRESPONSES /work: post: operationId: "create_work" tags: - releases parameters: - name: entity in: body required: true schema: $ref: "#/definitions/work_entity" - name: editgroup 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: - works parameters: - name: autoaccept in: query type: boolean required: false description: "If true, and editor is authorized, batch is accepted all at once" - name: editgroup 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/{id}: parameters: - name: id in: path type: string required: true get: operationId: "get_work" tags: - works parameters: - name: expand in: query type: string required: false description: "List of sub-entities to expand in response. For now, only 'all' accepted." responses: 200: description: Found Entity schema: $ref: "#/definitions/work_entity" <<: *ENTITYRESPONSES put: operationId: "update_work" tags: - works parameters: - name: entity in: body required: true schema: $ref: "#/definitions/work_entity" - name: editgroup in: query required: false type: string responses: 200: description: Updated Entity schema: $ref: "#/definitions/entity_edit" <<: *ENTITYRESPONSES delete: operationId: "delete_work" tags: - works parameters: - name: editgroup in: query required: false type: string responses: 200: description: Deleted Entity schema: $ref: "#/definitions/entity_edit" <<: *ENTITYRESPONSES /work/{id}/history: parameters: - name: id in: path type: string required: true - name: limit in: query type: integer format: int64 required: false get: operationId: "get_work_history" tags: - works responses: 200: description: Found Entity History schema: type: array items: $ref: "#/definitions/entity_history_entry" <<: *ENTITYRESPONSES /work/{id}/releases: parameters: - name: id in: path type: string required: true get: operationId: "get_work_releases" tags: - works responses: 200: description: Found schema: type: array items: $ref: "#/definitions/release_entity" <<: *ENTITYRESPONSES /editor/{id}: parameters: - name: 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/{id}/changelog: parameters: - name: 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: - edit-lifecycle 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/{id}: parameters: - name: id in: path required: true <<: *FATCATIDENT get: operationId: "get_editgroup" tags: - edit-lifecycle 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/{id}/accept: parameters: - name: id in: path required: true <<: *FATCATIDENT post: operationId: "accept_editgroup" tags: - edit-lifecycle 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: - edit-lifecycle responses: 200: description: Success schema: type: array items: $ref: "#/definitions/changelog_entry" 500: description: Generic Error schema: $ref: "#/definitions/error_response" /changelog/{id}: parameters: - name: id in: path type: integer format: int64 required: true get: operationId: "get_changelog_entry" tags: - edit-lifecycle 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" /stats: get: operationId: "get_stats" parameters: - name: more in: query type: string required: false responses: 200: description: Success schema: $ref: "#/definitions/stats_response" 500: description: Generic Error schema: $ref: "#/definitions/error_response"