diff options
Diffstat (limited to 'rust/fatcat-api-spec/api.yaml')
| -rw-r--r-- | rust/fatcat-api-spec/api.yaml | 1280 |
1 files changed, 1280 insertions, 0 deletions
diff --git a/rust/fatcat-api-spec/api.yaml b/rust/fatcat-api-spec/api.yaml new file mode 100644 index 00000000..2b0615d2 --- /dev/null +++ b/rust/fatcat-api-spec/api.yaml @@ -0,0 +1,1280 @@ +--- +swagger: "2.0" +info: + title: fatcat + description: A scalable, versioned, API-oriented catalog of bibliographic entities + and file metadata + version: 0.1.0 +schemes: [http] +basePath: /v0 +#host: api.fatcat.wiki +consumes: + - application/json +produces: + - application/json + +# 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 + editgroup_id: + <<: *FATCATIDENT + extra: + type: object + additionalProperties: {} +# TODO: +# 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_title: + 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" + parameters: + - name: entity + in: body + required: true + schema: + $ref: "#/definitions/container_entity" + responses: + 201: + description: Created Entity + schema: + $ref: "#/definitions/entity_edit" + <<: *ENTITYRESPONSES + /container/batch: + post: + operationId: "create_container_batch" + 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" + 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" + parameters: + - name: entity + in: body + required: true + schema: + $ref: "#/definitions/container_entity" + responses: + 200: + description: Updated Entity + schema: + $ref: "#/definitions/entity_edit" + <<: *ENTITYRESPONSES + delete: + operationId: "delete_container" + 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: + 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" + parameters: + - name: issnl + in: query + required: true + <<: *FATCATISSN + responses: + 200: + description: Found Entity + schema: + $ref: "#/definitions/container_entity" + <<: *ENTITYRESPONSES + /creator: + post: + operationId: "create_creator" + parameters: + - name: entity + in: body + required: true + schema: + $ref: "#/definitions/creator_entity" + responses: + 201: + description: Created Entity + schema: + $ref: "#/definitions/entity_edit" + <<: *ENTITYRESPONSES + /creator/batch: + post: + operationId: "create_creator_batch" + 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" + 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" + parameters: + - name: entity + in: body + required: true + schema: + $ref: "#/definitions/creator_entity" + responses: + 200: + description: Updated Entity + schema: + $ref: "#/definitions/entity_edit" + <<: *ENTITYRESPONSES + delete: + operationId: "delete_creator" + 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" + 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" + responses: + 200: + description: Found + schema: + type: array + items: + $ref: "#/definitions/release_entity" + <<: *ENTITYRESPONSES + /creator/lookup: + get: + operationId: "lookup_creator" + parameters: + - name: orcid + in: query + required: true + <<: *FATCATORCID + responses: + 200: + description: Found Entity + schema: + $ref: "#/definitions/creator_entity" + <<: *ENTITYRESPONSES + /file: + post: + operationId: "create_file" + parameters: + - name: entity + in: body + required: true + schema: + $ref: "#/definitions/file_entity" + responses: + 201: + description: Created Entity + schema: + $ref: "#/definitions/entity_edit" + <<: *ENTITYRESPONSES + /file/batch: + post: + operationId: "create_file_batch" + 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" + 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" + parameters: + - name: entity + in: body + required: true + schema: + $ref: "#/definitions/file_entity" + responses: + 200: + description: Updated Entity + schema: + $ref: "#/definitions/entity_edit" + <<: *ENTITYRESPONSES + delete: + operationId: "delete_file" + 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" + responses: + 200: + description: Found Entity History + schema: + type: array + items: + $ref: "#/definitions/entity_history_entry" + <<: *ENTITYRESPONSES + /file/lookup: + get: + operationId: "lookup_file" + 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" + parameters: + - name: entity + in: body + required: true + schema: + $ref: "#/definitions/release_entity" + responses: + 201: + description: Created Entity + schema: + $ref: "#/definitions/entity_edit" + <<: *ENTITYRESPONSES + /release/batch: + post: + operationId: "create_release_batch" + 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" + 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" + parameters: + - name: entity + in: body + required: true + schema: + $ref: "#/definitions/release_entity" + responses: + 200: + description: Updated Entity + schema: + $ref: "#/definitions/entity_edit" + <<: *ENTITYRESPONSES + delete: + operationId: "delete_release" + 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" + 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" + responses: + 200: + description: Found + schema: + type: array + items: + $ref: "#/definitions/file_entity" + <<: *ENTITYRESPONSES + /release/lookup: + get: + operationId: "lookup_release" + 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" + parameters: + - name: entity + in: body + required: true + schema: + $ref: "#/definitions/work_entity" + responses: + 201: + description: Created Entity + schema: + $ref: "#/definitions/entity_edit" + <<: *ENTITYRESPONSES + /work/batch: + post: + operationId: "create_work_batch" + 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" + 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" + parameters: + - name: entity + in: body + required: true + schema: + $ref: "#/definitions/work_entity" + responses: + 200: + description: Updated Entity + schema: + $ref: "#/definitions/entity_edit" + <<: *ENTITYRESPONSES + delete: + operationId: "delete_work" + 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" + 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" + 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" + parameters: + - name: entity + 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" + 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" + responses: + 200: + description: Merged Successfully + schema: + $ref: "#/definitions/success" + 400: + description: Unmergable + schema: + $ref: "#/definitions/error_response" + 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" + 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" + 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" |