EndpointPermissions

Endpoint Permissions

This document describes the access permissions which are required to use the various Tradamus endpoints. The endpoints themselves are more full described in Tradamus Server API.

There are five ranked levels of access: NONE, VIEWER, CONTRIBUTOR, EDITOR, and OWNER. If a user has a particular level of access to a resource, they also implicitly have all the lower levels of access.

level	access
NONE	None
VIEWER	Read-only access.
CONTRIBUTOR	Can add new annotations but these will be unvetted.
EDITOR	Can add fully-vetted annotations. Can vet annotations for CONTRIBUTORs.
OWNER	Can assign permissions.

These levels are relative to a given resource. A particular user could have OWNER access to one edition while having no access at all to other editions.

Permissions can currently be set at three different points: the edition, the transcription, and the manifest. When verifying permissions, they are checked at the edition level first; if the user has sufficient permissions to access the edition, permissions are then checked at the transcription or manifest level. Accordingly, transcription and manifestt permissions can only be used to make access more restrictive.

Also new is the notion of annotations being vetted or unvetted. When a user with CONTRIBUTOR access adds an annotation, it is only visible to themselves and to users with EDITOR access. Once an EDITOR has approved an annotation, it becomes visible to all users with VIEWER access.

1. Users

Add new user

Endpoint: /users
Method: POST
Access: No restrictions.

Invite new user

Endpoint: /users
Method: POST
Access: EDITOR on edition to which user is being invited.

Get user details

Endpoint: /user/userID
Method: GET
Access: No restrictions.

Get user details by email

Endpoint: /user?mail=emailAddress
Method: GET
Access: No restrictions.

Modify user details

Endpoint: /user/userID
Method: PUT
Access: Only userID can modify their own details.

Reset user password

Endpoint: /user?reset=emailAddress
Method: POST
Access: No restrictions.

2. Login

Log in to Tradamus

Endpoint: /login
Method: POST
Access: No restrictions.

Check login status

Endpoint: /login
Method: GET
Access: The call always returns the status of the current user.

3. Editions

Add new edition

Endpoint: /editions
Method: POST
Access: No restrictions. The current user will be granted OWNER access to the newly-created edition.

List editions

Endpoint: /editions
Method: GET
Access: The call will only return editions for which the current user has VIEWER permissions.

Get edition details

Endpoint: /edition/edID
Method: GET
Access: VIEWER on the edition.

Set edition details

Endpoint: /edition/edID
Method: PUT
Access: EDITOR on the edition.

Add an edition metadatum

Endpoint: /edition/edID/metadata
Method: POST
Access: CONTRIBUTOR on the edition.

Set edition metadata

Endpoint: /edition/edID/metadata
Method: PUT
Access: CONTRIBUTOR on the edition. If access level is just CONTRIBUTOR, the call will fail with a 403 if it attempts to modify any metadata which belong to another user.

Get edition decisions

Endpoint: /edition/edID/decisions
Method: GET
Access: VIEWER on the edition.

Set edition decisions

Endpoint: /edition/edID/decisions
Method: PUT
Access: CONTRIBUTOR on the edition. If access level is just CONTRIBUTOR, the call will fail with a 403 if it attempts to modify any decisions which belong to another user.

Set edition permissions

Endpoint: /edition/edID/permissions
Method: PUT
Access: OWNER on the edition.

Delete an edition

Endpoint: /edition/edID
Method: DELETE
Access: OWNER on the edition.

4. Witnesses

Create a new witness

Endpoint: /witnesses
Method: POST
Access: EDITOR on the edition.

Get witness details

Endpoint: /witness/witID
Method: GET
Access: VIEWER on the edition.

Set witness details

Endpoint: /witness/witID
Method: PUT
Access: EDITOR on the edition.

Add a witness metadatum

Endpoint: /witness/witID/metadata
Method: POST
Access: CONTRIBUTOR on the edition.

Set witness metadata

Endpoint: /witness/witID/metadata
Method: PUT
Access: CONTRIBUTOR on the edition. If access level is just CONTRIBUTOR, the call will fail with a 403 if it attempts to modify any metadata which belong to another user.

Delete a witness

Endpoint: /witness/witID
Method: DELETE
Access: EDITOR on the edition.

Recursively get all witness annotations

Endpoint: /witness/witID/annotations
Method: GET
Access: VIEWER on the edition. The results will be filtered if access is more restricted at the transcription or manifest levels.

5. Transcriptions

Get transcription details

Endpoint: /transcription/transcrID
Method: GET
Access: VIEWER on the transcription.

Set transcription permissions

Endpoint: /transcription/transcrID/permissions
Method: PUT
Access: OWNER on the transcription.

6. Pages

Get page details

Endpoint: /page/pageID
Method: GET
Access: VIEWER on the transcription.

Set page details

Endpoint: /page/pageID
Method: PUT
Access: EDITOR on the transcription.

Add a page annotation

Endpoint: /page/pgID/annotations
Method: POST
Access: CONTRIBUTOR on the transcription.

Get page annotations

Endpoint: /page/pgID/annotations
Method: GET
Access: VIEWER on the transcription.

Set page annotations

Endpoint: /page/pageID/annotations
Method: PUT
Access: CONTRIBUTOR on the transcription. If access level is just CONTRIBUTOR, the call will fail with a 403 if it attempts to modify any annotations which belong to another user.

Get page lines

Endpoint: /page/pgID/lines
Method: GET
Access: VIEWER on the transcription.

Set page lines

Endpoint: /page/pageID/lines
Method: PUT
Access: CONTRIBUTOR on the transcription. If access level is just CONTRIBUTOR, the call will fail with a 403 if it attempts to modify any lines which belong to another user.

7. Manifests

Get manifest details

Endpoint: /manifest/manID
Method: GET
Access: VIEWER on the manifest.

Set manifest permissions

Endpoint: /manifest/manID/permissions
Method: PUT
Access: OWNER on the manifest.

8. Canvasses

Get canvas details

Endpoint: /canvas/canvID
Method: GET
Access: VIEWER on the manifest.

Set canvas details

Endpoint: /canvas/canvID
Method: PUT
Access: EDITOR on the manifest.

Add a canvas annotation

Endpoint: /canvas/canvID/annotations
Method: POST
Access: CONTRIBUTOR on the manifest.

Get canvas annotations

Endpoint: /canvas/canvID/annotations
Method: GET
Access: VIEWER on the manifest.

Set canvas annotations

Endpoint: /canvas/canvID/annotations
Method: PUT
Access: CONTRIBUTOR on the manifest. If access level is just CONTRIBUTOR, the call will fail with a 403 if it attempts to modify any annotations which belong to another user.

Get canvas lines

Endpoint: /canvas/canvID/lines
Method: GET
Access: VIEWER on the manifest.

Set canvas lines

Endpoint: /canvas/canvID/lines
Method: PUT
Access: CONTRIBUTOR on the manifest. If access level is just CONTRIBUTOR, the call will fail with a 403 if it attempts to modify any lines which belong to another user.

9. Annotations

Get annotation details

Endpoint: /annotation/annID
Method: GET
Access: VIEWER on the transcription or the manifest. In particular, if an annotation is anchored to both the page and the canvas, it is sufficient to have VIEWER access on one of the transcription or the manifest.

Set annotation details

Endpoint: /annotation/annID
Method: PUT
Access: CONTRIBUTOR on the transcription or the manifest. If access level is just CONTRIBUTOR, the call will fail with a 403 if it attempts to modify an annotation which belongs to another user.

Delete an annotation

Endpoint: /annotation/annID
Method: DELETE
Access: CONTRIBUTOR on the transcription or the manifest. If the access level is just CONTRIBUTOR, the call can only delete an annotation belonging to the current user.

10. Collation

Full-edition collation

Endpoint: /collation/edID
Method: GET
Access: Only transcriptions with VIEWER access will be included in the collation.

Sub-collation

Endpoint: /collation
Method: GET
Access: Only transcriptions with VIEWER access will be included in the collation.

11. Config

Endpoint: /config
Method: GET
Access: No restrictions.

12. Activity Log

Endpoint: /activity
Method: GET
Access: To be determined.