---
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
# Common properties across entities
x-entity-props: &ENTITYPROPS
state:
type: string
enum: ["wip", "active", "redirect", "deleted"]
ident:
type: string
#format: uuid
example: "f1f046a3-45c9-4b99-adce-000000000001"
revision:
type: integer
example: 42
format: int64
redirect:
type: string
#format: uuid
example: "f1f046a3-45c9-4b99-adce-000000000002"
editgroup_id:
type: integer
example: 16
format: int64
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:
type: string
#format: custom
example: "1234-5678"
abbrev:
type: string
coden:
type: string
creator_entity:
type: object
required:
- full_name
properties:
<<: *ENTITYPROPS
full_name:
type: string
example: "Grace Hopper"
orcid:
type: string
#format: custom
example: "0000-0002-1825-0097"
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"
url:
type: string
format: url
example: "https://example.edu/~frau/prcding.pdf"
releases:
type: array
items:
type: string
#format: uuid
release_entity:
type: object
required:
- title
- work_id
properties:
<<: *ENTITYPROPS
title:
type: string
work_id:
type: string
example: "f1f046a3-45c9-4b99-adce-000000000001"
container_id:
type: string
example: "f1f046a3-45c9-4b99-adce-000000000001"
release_type:
type: string
example: "preprint"
date:
type: string
format: date
doi:
type: string
#format: custom
example: "10.1234/abcde.789"
isbn13:
type: string
#format: custom
volume:
type: string
pages:
type: string
issue:
type: string
example: "12"
publisher:
type: string
contribs:
type: array
items:
$ref: "#/definitions/release_contrib"
refs:
type: array
items:
$ref: "#/definitions/release_ref"
work_entity:
type: object
properties:
<<: *ENTITYPROPS
work_type:
type: string
entity_edit:
type: object
required:
- edit_id
- ident
- editgroup_id
properties:
edit_id:
type: integer
example: 847
format: int64
ident:
type: string
example: "f1f046a3-45c9-4b99-adce-000000000001"
revision:
type: integer
example: 42
format: int64
redirect_ident:
type: string
example: "f1f046a3-45c9-4b99-adce-000000000002"
#format: uuid
editgroup_id:
type: integer
example: 16
format: int64
extra:
type: object
additionalProperties: {}
editor:
type: object
required:
- username
properties:
username:
type: string
example: "zerocool93"
editgroup:
type: object
required:
- editor_id
properties:
id:
type: integer
format: int64
editor_id:
type: integer
format: int64
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"
changelogentries:
type: array
items:
type: object
required:
- index
- editgroup_id
- timestamp
properties:
index:
type: integer
format: int64
editgroup_id:
type: integer
format: int64
timestamp:
type: string
format: date-time
release_ref:
type: object
properties:
index:
type: integer
format: int64
target_release_id:
type: string
#format: uuid
stub:
type: string
release_contrib:
type: object
properties:
index:
type: integer
format: int64
creator_id:
type: string
#format: uuid
creator_stub:
type: string
role:
type: string
x-entity-responses: &ENTITYRESPONSES
400:
description: Bad Request
schema:
$ref: "#/definitions/error_response"
404:
description: Not Found
schema:
$ref: "#/definitions/error_response"
default:
description: Generic Error
schema:
$ref: "#/definitions/error_response"
paths:
/container:
post:
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:
parameters:
- 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:
responses:
200:
description: Found Entity
schema:
$ref: "#/definitions/container_entity"
<<: *ENTITYRESPONSES
/container/lookup:
get:
parameters:
- name: issnl
in: query
type: string
required: true
responses:
200:
description: Found Entity
schema:
$ref: "#/definitions/container_entity"
<<: *ENTITYRESPONSES
/creator:
post:
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:
parameters:
- 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:
responses:
200:
description: Found Entity
schema:
$ref: "#/definitions/creator_entity"
<<: *ENTITYRESPONSES
/creator/lookup:
get:
parameters:
- name: orcid
in: query
type: string
required: true
responses:
200:
description: Found Entity
schema:
$ref: "#/definitions/creator_entity"
<<: *ENTITYRESPONSES
/file:
post:
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:
parameters:
- 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:
responses:
200:
description: Found Entity
schema:
$ref: "#/definitions/file_entity"
<<: *ENTITYRESPONSES
/file/lookup:
get:
parameters:
- name: sha1
in: query
type: string
required: true
responses:
200:
description: Found Entity
schema:
$ref: "#/definitions/file_entity"
<<: *ENTITYRESPONSES
/release:
post:
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:
parameters:
- 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:
responses:
200:
description: Found Entity
schema:
$ref: "#/definitions/release_entity"
<<: *ENTITYRESPONSES
/release/lookup:
get:
parameters:
- name: doi
in: query
type: string
required: true
responses:
200:
description: Found Entity
schema:
$ref: "#/definitions/release_entity"
<<: *ENTITYRESPONSES
/work:
post:
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:
parameters:
- 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:
responses:
200:
description: Found Entity
schema:
$ref: "#/definitions/work_entity"
<<: *ENTITYRESPONSES
/editor/{username}:
parameters:
- name: username
in: path
type: string
required: true
get:
responses:
200:
description: Found Editor
schema:
$ref: "#/definitions/editor"
404:
description: Not Found
schema:
$ref: "#/definitions/error_response"
default:
description: Generic Error
schema:
$ref: "#/definitions/error_response"
/editor/{username}/changelog:
parameters:
- name: username
in: path
type: string
required: true
get:
responses:
200:
description: Found Merged Changes
schema:
$ref: "#/definitions/changelogentries"
404:
description: Not Found
schema:
$ref: "#/definitions/error_response"
default:
description: Generic Error
schema:
$ref: "#/definitions/error_response"
/editgroup:
post:
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"
default:
description: Generic Error
schema:
$ref: "#/definitions/error_response"
/editgroup/{id}:
parameters:
- name: id
in: path
type: integer
format: int64
required: true
get:
responses:
200:
description: Found Entity
schema:
$ref: "#/definitions/editgroup"
400:
description: Bad Request
schema:
$ref: "#/definitions/error_response"
404:
description: Not Found
schema:
$ref: "#/definitions/error_response"
default:
description: Generic Error
schema:
$ref: "#/definitions/error_response"
/editgroup/{id}/accept:
parameters:
- name: id
in: path
type: integer
format: int64
required: true
post:
responses:
200:
description: Merged Successfully
schema:
$ref: "#/definitions/success"
400:
description: Unmergable
schema:
$ref: "#/definitions/error_response"
404:
description: Not Found
schema:
$ref: "#/definitions/error_response"
default:
description: Generic Error
schema:
$ref: "#/definitions/error_response"