**Editgroups** are sets of changes, each to individual entities in the # TAGLINE catalog. Every edit must be part of an editgroup which is reviewed and # TAGLINE accepted (merged) as a whole. # TAGLINE
swagger: '2.0'
info:
title: fatcat auth editgroups API
version: 0.5.0
description: 'Fatcat is a scalable, versioned, API-oriented catalog of bibliographic
entities and file metadata.
<!-- STARTLONGDESCRIPTION -->
These API reference documents, along with client software libraries, are
generated automatically from an OpenAPI 2.0 ("Swagger") definition file.
## Introduction
A higher-level introduction to the API, as well as a description of the
fatcat data model, are available in ["The Fatcat Guide"](https://guide.fatcat.wiki/).
The guide also includes a [Cookbook](https://guide.fatcat.wiki/cookbook.html)
section demonstrating end-to-end tasks like creating entities as part of
editgroups, or safely merging duplicate entities.
### Expectations and Best Practices
A test/staging QA API instance of fatcat is available at
<https://api.qa.fatcat.wiki/v0>. The database backing this instance is
separate from the production interface, and is periodically rebuilt from
snapshots of the full production database, meaning that edits on the QA
server will *NOT* persist, and that semantics like the changelog index
monotonically increasing *MAY* be broken. Developers are expexcted to test
their scripts and tools against the QA instance before running against
production.
NOTE: as of Spring 2021, the QA server is temporarily unavailable.
Fatcat is made available as a gratis (no cost) and libre (freedom
preserving) service to the public, with limited funding and resources. We
welcome new and unforeseen uses and contributions, but may need to impose
restrictions (like rate-limits) to keep the service functional for other
users, and in extreme cases reserve the option to block accounts and IP
ranges if necessary to keep the service operational.
The Internet Archive owns and operates it''s own server equipment and data
centers, and operations are optimized for low-cost, not high-availability.
Users and partners should expect some downtime on the fatcat API, on the
order of hours a month.
Periodic metadata exports are available for batch processing, and database
snapshots can be used to create locally-hosted mirrors of the service for
more intensive and reliable querying.
### Other Nitty Gritties
Cross-origin requests are allowed for the API service, to enable third
parties to build in-browser applications.
A metadata search service is available at <https://search.fatcat.wiki>.
The API is currently the raw elasticsearch API, with only GET (read)
requests allowed. This public service is experimental and may be removed or
limited in the future.
## Authentication
The API allows basic read-only "GET" HTTP requests with no authentication.
Proposing changes to the metadata, or other mutating requests ("PUT",
"POST", "DELETE") all require authentication, and some operations require
additional account permissions.
End-user account creation and login happens through the web interface. From
a logged-in editor profile page, you can generate a API token. Tokens are
"macaroons", similar to JWT tokens, and are used for all API
authentication. The web interface includes macaroons in browser cookies and
passes them through to the API to authenticate editor actions.
<!-- ReDoc-Inject: <security-definitions> -->
<!-- ENDLONGDESCRIPTION -->
'
termsOfService: https://guide.fatcat.wiki/policies.html
contact:
name: Internet Archive Web Group
email: webservices@archive.org
url: https://fatcat.wiki
x-logo:
url: https://fatcat.wiki/static/paper_man_confused.gif
altText: Confused Papers Man (Logo)
backgroundColor: '#FFFFFF'
host: api.fatcat.wiki
basePath: /v0
schemes:
- https
consumes:
- application/json
produces:
- application/json
tags:
- name: editgroups
x-displayName: Editgroups
description: '**Editgroups** are sets of changes, each to individual entities in the # TAGLINE
catalog. Every edit must be part of an editgroup which is reviewed and # TAGLINE
accepted (merged) as a whole. # TAGLINE
'
paths:
/editgroup:
post:
operationId: create_editgroup
tags:
- editgroups
description: 'Creates a new editgroup. By default the editor making this request will
be the author of the editgroup.
'
parameters:
- name: editgroup
in: body
required: true
schema:
$ref: '#/definitions/editgroup'
security:
- Bearer: []
responses:
401:
description: Not Authorized
schema:
$ref: '#/definitions/error_response'
headers:
WWW_Authenticate:
type: string
403:
description: Forbidden
schema:
$ref: '#/definitions/error_response'
201:
description: Successfully Created
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}:
parameters:
- type: string
pattern: '[a-zA-Z2-7]{26}'
minLength: 26
maxLength: 26
description: base32-encoded unique identifier
name: editgroup_id
in: path
required: true
get:
operationId: get_editgroup
tags:
- editgroups
description: 'Returns a single editgroup object.
Unlike some similar methods, this method will return a full/expanded
editgroup object, which includes edit lists of each entity type (though
will not include the complete entity objects).
'
responses:
200:
description: Found
schema:
$ref: '#/definitions/editgroup'
400:
description: Bad Request
schema:
$ref: '#/definitions/error_response'
404:
description: Not Found
schema:
$ref: '#/definitions/error_response'
500:
description: Generic Error
schema:
$ref: '#/definitions/error_response'
put:
operationId: update_editgroup
tags:
- editgroups
description: 'Updates metadata for a single editgroup object. Note that only metadata
fields such as the `description` or `extra` metadata can be changed
with this method; it does not allow adding or removing edits to the
editgroup (for that use the individual entity create/update/delete
methods).
'
security:
- Bearer: []
parameters:
- name: editgroup
in: body
required: true
schema:
$ref: '#/definitions/editgroup'
- name: submit
in: query
type: boolean
required: false
responses:
401:
description: Not Authorized
schema:
$ref: '#/definitions/error_response'
headers:
WWW_Authenticate:
type: string
403:
description: Forbidden
schema:
$ref: '#/definitions/error_response'
200:
description: Updated Editgroup
schema:
$ref: '#/definitions/editgroup'
400:
description: Bad Request
schema:
$ref: '#/definitions/error_response'
404:
description: Not Found
schema:
$ref: '#/definitions/error_response'
500:
description: Generic Error
schema:
$ref: '#/definitions/error_response'
/editgroup/{editgroup_id}/accept:
parameters:
- type: string
pattern: '[a-zA-Z2-7]{26}'
minLength: 26
maxLength: 26
description: base32-encoded unique identifier
name: editgroup_id
in: path
required: true
post:
operationId: accept_editgroup
tags:
- editgroups
description: 'Accept ("merge") the given editgroup into the catalog. The editgroup
must be open (not already accepted), and the editor making this request
must have the `admin` role.
'
security:
- Bearer: []
responses:
401:
description: Not Authorized
schema:
$ref: '#/definitions/error_response'
headers:
WWW_Authenticate:
type: string
403:
description: Forbidden
schema:
$ref: '#/definitions/error_response'
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'
/editgroup/{editgroup_id}/annotations:
parameters:
- type: string
pattern: '[a-zA-Z2-7]{26}'
minLength: 26
maxLength: 26
description: base32-encoded unique identifier
name: editgroup_id
in: path
required: true
get:
operationId: get_editgroup_annotations
tags:
- editgroups
description: Returns a list of annotations made to a specific editgroup.
parameters:
- name: expand
in: query
type: string
required: false
description: 'List of sub-entities to expand in response. For editgroup annotations: ''editors'''
responses:
401:
description: Not Authorized
schema:
$ref: '#/definitions/error_response'
headers:
WWW_Authenticate:
type: string
403:
description: Forbidden
schema:
$ref: '#/definitions/error_response'
200:
description: Success
schema:
type: array
items:
$ref: '#/definitions/editgroup_annotation'
400:
description: Bad Request
schema:
$ref: '#/definitions/error_response'
404:
description: Not Found
schema:
$ref: '#/definitions/error_response'
500:
description: Generic Error
schema:
$ref: '#/definitions/error_response'
/editgroup/{editgroup_id}/annotation:
parameters:
- type: string
pattern: '[a-zA-Z2-7]{26}'
minLength: 26
maxLength: 26
description: base32-encoded unique identifier
name: editgroup_id
in: path
required: true
post:
operationId: create_editgroup_annotation
tags:
- editgroups
description: 'Submits a new annotation to the specified editgroup.
The editgroup must be open (not already accepted). The annotation will
automatically have authorship of the editor making this request.
'
security:
- Bearer: []
parameters:
- name: annotation
in: body
required: true
schema:
$ref: '#/definitions/editgroup_annotation'
responses:
401:
description: Not Authorized
schema:
$ref: '#/definitions/error_response'
headers:
WWW_Authenticate:
type: string
403:
description: Forbidden
schema:
$ref: '#/definitions/error_response'
201:
description: Created
schema:
$ref: '#/definitions/editgroup_annotation'
400:
description: Bad Request
schema:
$ref: '#/definitions/error_response'
404:
description: Not Found
schema:
$ref: '#/definitions/error_response'
500:
description: Generic Error
schema:
$ref: '#/definitions/error_response'
/editgroup/reviewable:
get:
operationId: get_editgroups_reviewable
tags:
- editgroups
description: 'Returns a set of editgroups which have been submitted but not yet accepted.
Query parameters can be used to sort and paginate the list returned.
'
parameters:
- name: expand
in: query
type: string
required: false
description: 'List of sub-entities to expand in response. For editgroups: ''editors'''
- name: limit
in: query
type: integer
format: int64
required: false
description: Maximum number of reviewable editgroups to return in response
- name: before
in: query
type: string
format: date-time
required: false
description: 'Return only reviewable editgroups submitted *before* the given
timestamp (not inclusive). Editgroups will be sorted by submission
time in descending order (most recent first). For use in pagination.
'
- name: since
in: query
type: string
format: date-time
required: false
description: 'Return only reviewable editgroups submitted *after* the given
timestamp (not inclusive). Editgroups will be sorted by submission
time in ascending order (most recent last). For use in pagination.
'
responses:
200:
description: Found
schema:
type: array
items:
$ref: '#/definitions/editgroup'
400:
description: Bad Request
schema:
$ref: '#/definitions/error_response'
404:
description: Not Found
schema:
$ref: '#/definitions/error_response'
500:
description: Generic Error
schema:
$ref: '#/definitions/error_response'
definitions:
entity_edit:
type: object
required:
- edit_id
- ident
- editgroup_id
properties:
edit_id:
type: string
pattern: '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}'
minLength: 36
maxLength: 36
description: 'Unique UUID for this specific edit object.
'
example: 86daea5b-1b6b-432a-bb67-ea97795f80fe
ident:
type: string
pattern: '[a-zA-Z2-7]{26}'
minLength: 26
maxLength: 26
description: 'Fatcat identifier of the entity this edit is mutating.
'
example: q3nouwy3nnbsvo3h5klxsx4a7y
revision:
type: string
pattern: '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}'
minLength: 36
maxLength: 36
description: 'Entity revision that this edit will set the entity to. May be
`null` in the case of deletions.
'
example: 86daea5b-1b6b-432a-bb67-ea97795f80fe
prev_revision:
type: string
pattern: '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}'
minLength: 36
maxLength: 36
description: 'Revision of entity just before this edit. May be used in the future
to prevent edit race conditions.
'
example: 86daea5b-1b6b-432a-bb67-ea97795f80fe
redirect_ident:
type: string
pattern: '[a-zA-Z2-7]{26}'
minLength: 26
maxLength: 26
description: 'When an edit is to merge entities (redirect one to another), this
is the entity fatcat identifier for the target entity.
'
example: q3nouwy3nnbsvo3h5klxsx4a7y
editgroup_id:
type: string
pattern: '[a-zA-Z2-7]{26}'
minLength: 26
maxLength: 26
description: 'Editgroup identifier that this edit is part of.
'
example: q3nouwy3nnbsvo3h5klxsx4a7y
extra:
type: object
additionalProperties: {}
error_response:
type: object
required:
- success
- error
- message
properties:
success:
type: boolean
example: false
error:
type: string
example: unexpected-thing
message:
type: string
example: A really confusing, totally unexpected thing happened
editgroup:
type: object
properties:
editgroup_id:
type: string
pattern: '[a-zA-Z2-7]{26}'
minLength: 26
maxLength: 26
description: 'Fatcat identifier for this editgroup. Assigned on creation.
'
example: q3nouwy3nnbsvo3h5klxsx4a7y
editor_id:
type: string
pattern: '[a-zA-Z2-7]{26}'
minLength: 26
maxLength: 26
description: 'Fatcat identifier of editor that created this editgroup.
'
example: q3nouwy3nnbsvo3h5klxsx4a7y
editor:
$ref: '#/definitions/editor'
description: 'Complete editor object identified by `container_id` field. Only
included in GET responses.
'
changelog_index:
type: integer
example: 1048576
format: int64
description: 'For accepted/merged editgroups, the changelog index that the accept
occurred at. WARNING: not populated in all contexts that an editgroup
could be included in a response.
'
created:
type: string
format: date-time
description: 'Timestamp when this editgroup was first created.
'
submitted:
type: string
format: date-time
description: 'Timestamp when this editgroup was most recently submitted for review.
If withdrawn, or never submitted, will be `null`.
'
description:
type: string
description: 'Comment describing the changes in this editgroup. Can be updated with
PUT request.
'
extra:
type: object
additionalProperties: {}
description: 'Free-form JSON metadata attached to this editgroup. Eg, metadata
provenance, or script user-agent details. See guide for (unenforced)
schema norms.
'
annotations:
type: array
items:
$ref: '#/definitions/editgroup_annotation'
description: 'Only included in GET responses, and not in all contexts. Do not
include this field in PUT or POST requests.
'
edits:
type: object
description: 'Only included in GET responses, and not in all contexts. Do not
include this field in PUT or POST requests.
'
properties:
containers:
type: array
items:
$ref: '#/definitions/entity_edit'
creators:
type: array
items:
$ref: '#/definitions/entity_edit'
files:
type: array
items:
$ref: '#/definitions/entity_edit'
filesets:
type: array
items:
$ref: '#/definitions/entity_edit'
webcaptures:
type: array
items:
$ref: '#/definitions/entity_edit'
releases:
type: array
items:
$ref: '#/definitions/entity_edit'
works:
type: array
items:
$ref: '#/definitions/entity_edit'
success:
type: object
required:
- success
- message
properties:
success:
type: boolean
example: true
message:
type: string
example: The computers did the thing successfully!
editgroup_annotation:
type: object
properties:
annotation_id:
type: string
pattern: '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}'
minLength: 36
maxLength: 36
description: UUID (lower-case, dash-separated, hex-encoded 128-bit)
example: 86daea5b-1b6b-432a-bb67-ea97795f80fe
editgroup_id:
type: string
pattern: '[a-zA-Z2-7]{26}'
minLength: 26
maxLength: 26
description: 'Editgroup that this annotation applies to. Set automatically in
creations based on URL parameter.
'
example: q3nouwy3nnbsvo3h5klxsx4a7y
editor_id:
type: string
pattern: '[a-zA-Z2-7]{26}'
minLength: 26
maxLength: 26
description: 'Defaults to editor created the annotation via POST request.
'
example: q3nouwy3nnbsvo3h5klxsx4a7y
editor:
$ref: '#/definitions/editor'
description: 'Only included in GET responses; ignored in PUT or POST requests.
'
created:
type: string
format: date-time
description: 'Timestamp when annotation was first created.
'
comment_markdown:
type: string
extra:
type: object
additionalProperties: {}
description: 'Additional free-form JSON metadata that can be included as part of
the annotation (or even as the primary annotation itself). See guide
for details.
'
editor:
type: object
required:
- username
properties:
editor_id:
type: string
pattern: '[a-zA-Z2-7]{26}'
minLength: 26
maxLength: 26
description: 'Fatcat identifier for the editor. Can not be changed.
'
example: q3nouwy3nnbsvo3h5klxsx4a7y
username:
type: string
example: zerocool93
description: 'Username/handle (short slug-like string) to identify this editor. May
be changed at any time by the editor; use the `editor_id` as a
persistend identifier.
'
is_admin:
type: boolean
example: false
description: 'Whether this editor has the `admin` role.
'
is_bot:
type: boolean
example: false
description: 'Whether this editor is a bot (as opposed to a human making manual
edits)
'
is_active:
type: boolean
example: true
description: 'Whether this editor''s account is enabled (if not API tokens and web
logins will not work).
'
securityDefinitions:
Bearer:
type: apiKey
name: Authorization
in: header
description: "The only current API authentication mechanism is HTTP bearer\nauthentication using the `Authorization` HTTP header. The header should\nbe formatted as the string \"Bearer\", then a space, then API token (in the\nusual base64 string encoding).\n\nAn example HTTP request would look on the wire like:\n\n GET /v0/auth/check HTTP/1.1\n Accept: */*\n Accept-Encoding: gzip, deflate\n Authorization: Bearer AgEPZGV2LmZhdGNhdC53aWtpAhYyMDE5MDEwMS1kZXYtZHVtbXkta2V5AAImZWRpdG9yX2lkID0gYWFhYWFhYWFhYWFhYmt2a2FhYWFhYWFhYWkAAht0aW1lID4gMjAxOS0wMS0wOVQwMDo1Nzo1MloAAAYgnroNha1hSftChtxHGTnLEmM/pY8MeQS/jBSV0UNvXug=\n Connection: keep-alive\n Host: api.qa.fatcat.wiki\n User-Agent: HTTPie/0.9.8\n\nHeaders can be passed on the command line using `http` (HTTPie) like:\n\n http get https://api.qa.fatcat.wiki/v0/auth/check Authorization:\"Bearer AgEPZGV2LmZhdGNhdC53aWtpAhYyMDE5MDEwMS1kZXYtZHVtbXkta2V5AAImZWRpdG9yX2lkID0gYWFhYWFhYWFhYWFhYmt2a2FhYWFhYWFhYWkAAht0aW1lID4gMjAxOS0wMS0wOVQwMDo1Nzo1MloAAAYgnroNha1hSftChtxHGTnLEmM/pY8MeQS/jBSV0UNvXug=\"\n\nOr with `curl`:\n\n curl -H \"Authorization: Bearer AgEPZGV2LmZhdGNhdC53aWtpAhYyMDE5MDEwMS1kZXYtZHVtbXkta2V5AAImZWRpdG9yX2lkID0gYWFhYWFhYWFhYWFhYmt2a2FhYWFhYWFhYWkAAht0aW1lID4gMjAxOS0wMS0wOVQwMDo1Nzo1MloAAAYgnroNha1hSftChtxHGTnLEmM/pY8MeQS/jBSV0UNvXug=\" https://qa.fatcat.wiki/v0/auth/check\n"
x-servers:
- url: https://api.fatcat.wiki/v0
description: Production Server
- url: https://api.qa.fatcat.wiki/v0
description: QA Server
x-tagGroups:
- name: Entities
tags:
- containers
- creators
- files
- filesets
- webcaptures
- releases
- works
- name: Editing
tags:
- editors
- editgroups
- changelog
- name: Other
tags:
- auth
x-fatcat-ident:
type: string
pattern: '[a-zA-Z2-7]{26}'
minLength: 26
maxLength: 26
description: base32-encoded unique identifier
x-fatcat-ident-example:
example: q3nouwy3nnbsvo3h5klxsx4a7y
x-fatcat-uuid:
type: string
pattern: '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}'
minLength: 36
maxLength: 36
description: UUID (lower-case, dash-separated, hex-encoded 128-bit)
x-fatcat-uuid-example:
example: 86daea5b-1b6b-432a-bb67-ea97795f80fe
x-issn:
type: string
pattern: \d{4}-\d{3}[0-9X]
minLength: 9
maxLength: 9
x-issn-example:
example: 1234-5678
x-orcid:
type: string
pattern: \d{4}-\d{4}-\d{4}-\d{3}[\dX]
minLength: 19
maxLength: 19
description: ORCiD (https://orcid.org) identifier
x-orcid-example:
example: 0000-0002-1825-0097
x-md5:
type: string
pattern: '[a-f0-9]{32}'
minLength: 32
maxLength: 32
description: MD5 hash of data, in hex encoding
x-md5-example:
example: 1b39813549077b2347c0f370c3864b40
x-sha1:
type: string
pattern: '[a-f0-9]{40}'
minLength: 40
maxLength: 40
description: SHA-1 hash of data, in hex encoding
x-sha1-example:
example: e9dd75237c94b209dc3ccd52722de6931a310ba3
x-sha256:
type: string
pattern: '[a-f0-9]{64}'
minLength: 64
maxLength: 64
description: SHA-256 hash of data, in hex encoding
x-sha256-example:
example: cb1c378f464d5935ddaa8de28446d82638396c61f042295d7fb85e3cccc9e452
x-entity-props:
state:
type: string
enum:
- wip
- active
- redirect
- deleted
example: active
ident:
type: string
pattern: '[a-zA-Z2-7]{26}'
minLength: 26
maxLength: 26
description: base32-encoded unique identifier
example: q3nouwy3nnbsvo3h5klxsx4a7y
revision:
type: string
pattern: '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}'
minLength: 36
maxLength: 36
description: UUID (lower-case, dash-separated, hex-encoded 128-bit)
example: 86daea5b-1b6b-432a-bb67-ea97795f80fe
redirect:
type: string
pattern: '[a-zA-Z2-7]{26}'
minLength: 26
maxLength: 26
description: base32-encoded unique identifier
example: q3nouwy3nnbsvo3h5klxsx4a7y
extra:
type: object
description: 'Free-form JSON metadata that will be stored with the other entity
metadata. See guide for (unenforced) schema conventions.
'
additionalProperties: {}
edit_extra:
type: object
description: 'Free-form JSON metadata that will be stored with specific entity edits
(eg, creation/update/delete).
'
additionalProperties: {}
x-auth-responses:
401:
description: Not Authorized
schema:
$ref: '#/definitions/error_response'
headers:
WWW_Authenticate:
type: string
403:
description: Forbidden
schema:
$ref: '#/definitions/error_response'
x-entity-responses:
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'