docuteam:bridge
Unterschiede
Hier werden die Unterschiede zwischen zwei Versionen angezeigt.
Beide Seiten der vorigen RevisionVorhergehende ÜberarbeitungNächste Überarbeitung | Vorhergehende ÜberarbeitungLetzte ÜberarbeitungBeide Seiten der Revision | ||
docuteam:bridge [2019/09/13 13:28] – [1 - depositions API] jan | docuteam:bridge [2020/05/05 08:25] – Administrator | ||
---|---|---|---|
Zeile 1: | Zeile 1: | ||
+ | **The new documentation site is located at https:// | ||
+ | |||
+ | \\ | ||
+ | |||
+ | \\ | ||
+ | |||
+ | |||
====== docuteam bridge ====== | ====== docuteam bridge ====== | ||
- | ===== documentation for client applications ===== | ||
- | Documentation for docuteam bridge | + | Documentation for docuteam bridge |
- | ===== goal ===== | + | ===== Goal ===== |
- | Client applications should be able to submit a deposition (data and metadata) to our ingest platform. Depositions are picked up by docuteam feeder workflows, usually processing and storing the information | + | Client applications should be able to submit a deposition (a package with data and metadata) to our ingest platform. Depositions are then picked up by docuteam feeder workflows, usually processing and storing the deposition |
- | deposited objects. | + | |
In the [[https:// | In the [[https:// | ||
- | * the bridge | + | * docuteam |
- | * after preservation actions, the SIP are ingested into the repository | + | * The SIPs are processed |
- | * the bridge access API enables client application to retrieve Dissemination Information | + | * Client applications |
{{ : | {{ : | ||
- | ===== key points | + | ===== Overview |
- | + | ||
- | * Bridge is a set of rest APIs that respond in JSON (and binary data) | + | |
- | * Bridge is agnostic to package format | + | |
- | * Use the simple, bagit-based format docuteam dublin core 1.0 (see [[docuteam: | + | |
- | * Use Matterhorn METS (see [[https:// | + | |
- | * Use other formats like e. g. eCH-0160 or SEDA. | + | |
- | * Bridge is composed of 3 APIs: | + | |
- | * **depositions**: | + | |
- | * **access**: read data successfully deposited in the repository | + | |
- | * **changes**: | + | |
- | ===== bridge APIs ===== | + | |
- | + | ||
- | For security reasons, bridge enforces HTTPS. Access is restricted via tokens that must be transmitted with each request via using the “token” parameter (regardless the HTTP method: GET, POST, PUT, PATCH, DELETE). Roles are associated to tokens and limit their scope of operation. | + | |
- | * **depositions** | + | * bridge is a set of REST APIs that usually return a JSON (and binary data) response. |
- | * new depositions are temporarily stored by bridge. They are made available to feeder, which in turn processes and stores them into the repository, | + | |
- | * depositions | + | |
- | * upon successful archiving in the repository, | + | |
- | * the status of the deposition is set to " | + | |
- | * PIDs, which are the repository’s Persistent IDs are made available | + | * bridge consists of three APIs: |
- | * Each digital object in the repository (folder, file) gets its own PID and relations between the customer' | + | * **[[docuteam: |
- | * the SIP is deleted from bridge as the information | + | * New depositions are temporarily stored by bridge. They are made available to feeder, which in turn processes and stores them into the repository. |
- | * **changes** | + | * Depositions |
- | * metadata only (data is unchanged, only for updates) | + | * Upon successful archiving in the repository, |
- | * data only (metadata | + | * the status of the deposition is set to " |
- | * object (metadata+data are modified) | + | * persistent identifiers (PIDs) for each of the deposition' |
- | * **access** | + | * and the SIP is deleted from the depositions as it is now preserved |
- | * gives access to the full DIP corresponding to a deposited SIP, | + | * **[[docuteam: |
- | * or gives access to metadata, data or on-the-fly converted formats | + | * metadata only (data remains |
- | * this API is a proxy to docuteam rservices (a component offering high level access to Fedora objects, such as DIP and preview generation) | + | * data only (metadata |
+ | * object (metadata | ||
+ | * **[[docuteam: | ||
+ | * Gives access to the full DIP corresponding to a deposited SIP. | ||
+ | * Gives access to metadata, data or previews | ||
- | ==== 0 - authentication and roles ==== | + | ===== Authentication ===== |
- | Bridge relies solely on tokens for authentication an authorization. Tokens are bound to institutions | + | Access is restricted via tokens that must be transmitted with each request using the " |
* An authentication token must be at least 15 characters long. | * An authentication token must be at least 15 characters long. | ||
- | * Tokens are passed | + | * Tokens are passed |
- | < | + | ===== Roles ===== |
- | === roles == | + | Roles are associated |
- | There are 5 roles: | + | |
- | * The 3 first roles are limited | + | |
- | * **read**: is restricted to the access API | + | |
- | * **create**: has the same authorizations as read, and can in addition list and create depositions via the deposition API | + | |
- | * **manage**: has the same authorizations as read, and can in addition update or purge repository objects via the nodes API | + | |
- | * The 2 last roles are not limited to any organization | + | |
- | * **admin**: authentication and authorization management, i.e. token administration via the API or the GUI | + | |
- | * **feeder**: super user, can do anything except token administration, | + | |
- | === recommendation === | + | There are five roles: |
- | * use only one token with read roles in applications that do not require | + | * The following three roles are limited |
- | * use only one token with create | + | * **read**: is restricted to the [[docuteam: |
- | * use only one token with manage role in applications that make use the changes | + | * **create**: has the same authorizations as read, but can in addition list, create and delete depositions via the [[docuteam: |
+ | * **manage**: has the same authorizations as create, and can in addition update or purge repository objects via the [[docuteam: | ||
+ | * The following two roles have a global scope: | ||
+ | * **admin**: authentication and authorization management, i.e. token administration using the API or the GUI | ||
+ | * **feeder**: super user, can do anything except token administration, | ||
- | ==== 1 - depositions | + | ===== Depositions |
- | === deposition statuses | + | ==== Status Model ==== |
- | * // | + | |
- | * //queued//: the deposition has been attributed to a queue in feeder | + | |
- | * // | + | |
- | * // | + | |
- | * //error//: something went wrong during the deposition' | + | |
- | * // | + | |
- | The deposition status can be managed by the role “feeder”. Other non-reader | + | Depositions have one of the following status: |
+ | * **submitted**: | ||
+ | * **queued**: the deposition has been queued for processing by feeder | ||
+ | * **processing**: | ||
+ | * **archived**: | ||
+ | * Persistent identifiers (PIDs) allocated to the deposition' | ||
+ | * The originally deposited package has been deleted from bridge. | ||
+ | * **error**: something went wrong during the deposition' | ||
+ | * **deleted**: | ||
+ | |||
+ | The deposition status can only be managed | ||
{{ : | {{ : | ||
+ | ==== Routes ==== | ||
+ | |||
+ | < | ||
+ | POST / | ||
+ | GET / | ||
+ | GET / | ||
+ | PUT / | ||
+ | </ | ||
+ | |||
+ | ==== Create ==== | ||
+ | Creates a new deposition. | ||
+ | |||
+ | === Allowed calls === | ||
+ | POST / | ||
+ | |||
+ | === Requirements === | ||
+ | Token with role '' | ||
+ | |||
+ | === Parameters === | ||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
+ | |||
+ | === Examples === | ||
+ | < | ||
+ | |||
+ | ==== Index ==== | ||
+ | Lists/shows the existing depositions with details. | ||
+ | |||
+ | === Allowed calls === | ||
+ | GET / | ||
+ | |||
+ | === Requirements === | ||
+ | Token with role '' | ||
+ | |||
+ | === Parameters === | ||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
+ | |||
+ | === Examples === | ||
+ | < | ||
+ | curl " | ||
+ | curl " | ||
+ | curl " | ||
+ | curl " | ||
+ | curl " | ||
+ | |||
+ | ==== Show ==== | ||
+ | Retrieve the binary content of a deposition. | ||
+ | |||
+ | === Allowed calls === | ||
+ | GET / | ||
+ | |||
+ | === Requirements === | ||
+ | Token with role '' | ||
+ | |||
+ | === Parameters === | ||
+ | * '': | ||
+ | * '' | ||
+ | |||
+ | === Examples === | ||
+ | < | ||
+ | |||
+ | ==== Update ==== | ||
+ | Set status and processing details. By setting the status to '' | ||
+ | |||
+ | === Allowed calls === | ||
+ | PUT / | ||
+ | |||
+ | === Requirements === | ||
+ | Token with role '' | ||
+ | |||
+ | === Parameters === | ||
+ | * '': | ||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
+ | |||
+ | === Examples === | ||
+ | < | ||
+ | curl -X PUT " | ||
- | === deposition responses | + | ==== Responses ==== |
- | Responses are given in JSON or a binary | + | Responses are given in JSON or (for the show method) as a binary. Each JSON response is a list of deposition with their details. The generic |
< | < | ||
{ " | { " | ||
{ " | { " | ||
- | " | + | " |
" | " | ||
[ | [ | ||
Zeile 122: | Zeile 203: | ||
Key elements include: | Key elements include: | ||
- | * “id” is the deposition | + | * '' |
- | * “status” is the deposition status, as described above, | + | * '' |
- | * “feeder_response” is also formatted in JSON. It is a black box from bridge' | + | * '' |
< | < | ||
Zeile 138: | Zeile 219: | ||
It must be noted that: | It must be noted that: | ||
- | * the "clientId" | + | * the '' |
- | * the "pid" | + | * the '' |
- | === deposition routes === | ||
- | == deposition routes overview | + | ===== Access API ===== |
+ | |||
+ | This API is a proxy to docuteam rservices. rservices offers high-level access functionality to repository objects. For example, it is able to generate DIPs starting from any level of an archival package and assemble it recursively. Another notable feature is the on-the-fly generation of preview/ | ||
+ | |||
+ | This access methods retrieve data from the repository, hence expects PIDs (and not bridge internal IDs, as it is the case for the depositions API). | ||
+ | |||
+ | In version 1.0, bridge is limited to synchronous requests, meaning that the required object is prepared and returned at once. Async/ | ||
+ | |||
+ | ==== Routes ==== | ||
< | < | ||
- | GET / | + | GET /access/ |
- | POST /depositions | + | GET |
- | GET /depositions/:id | + | GET /access/ |
- | PATCH | + | GET /access/ |
- | PUT | + | |
</ | </ | ||
- | == deposition routes detailed | + | ==== Metadata ==== |
- | ^ Action | + | Get the EAD metadata of a repository object. |
- | | **create** | + | === Allowed calls === |
- | | | parameter: | + | GET /access/sync_metadata/:pid |
- | | **list** / **show** | **HTTP GET** on / | + | |
- | | **retrieve binary data** | **HTTP | + | |
- | | **update** | + | |
- | ==== 2 - access API ==== | + | === Requirements |
+ | Token with role '' | ||
- | This API is a of proxy to docuteam rservices. Rservices is offers high level access to Fedora objects. For example, it is able to generate DIP starting from the top level object | + | === Parameters === |
+ | * '': | ||
+ | * '' | ||
- | Bridge adds an authentication and authorization layer on top of rservices. | + | === Examples === |
+ | < | ||
- | This API retrieves data from the archive, hence expects PIDs (and not bridge | + | ==== Preview ==== |
+ | Get a preview representation of a repository object. | ||
+ | |||
+ | === Allowed calls === | ||
+ | GET / | ||
+ | |||
+ | === Requirements === | ||
+ | Token with role '' | ||
+ | |||
+ | === Parameters === | ||
+ | * '': | ||
+ | * '' | ||
+ | |||
+ | === Examples === | ||
+ | < | ||
+ | |||
+ | ==== Original ==== | ||
+ | Get the original format of a repository object. | ||
+ | |||
+ | === Allowed calls === | ||
+ | GET / | ||
+ | |||
+ | === Requirements === | ||
+ | Token with role '' | ||
+ | |||
+ | === Parameters === | ||
+ | * '': | ||
+ | * '' | ||
+ | |||
+ | === Examples === | ||
+ | < | ||
+ | |||
+ | ==== DIP ==== | ||
+ | Get the dissemination package of a repository object, structured according to the Matterhorn METS format. For nested objects, it is possible to receive a package with both binaries and (technical and descriptive) metadata recursively. | ||
+ | |||
+ | === Allowed calls === | ||
+ | GET / | ||
+ | |||
+ | === Requirements === | ||
+ | Token with role '' | ||
+ | |||
+ | === Parameters === | ||
+ | * '': | ||
+ | * '' | ||
+ | |||
+ | === Examples === | ||
+ | < | ||
+ | curl " | ||
+ | |||
+ | |||
+ | ===== Changes API (under development) ===== | ||
+ | |||
+ | Changes target specific objects in the repository, using their persistent identifier (PID), in order to replace or purge them. Similar to depositions, | ||
+ | |||
+ | ==== Status Model ==== | ||
+ | |||
+ | * **submitted**: | ||
+ | * **queued**: | ||
+ | * **processing**: | ||
+ | * **archived**: | ||
+ | * **purged**: the change was successfully processed, i.e. the object was purged from the repository | ||
+ | * **error**: something went wrong, see the message in the " | ||
+ | * **deleted**: | ||
+ | |||
+ | {{ : | ||
- | In version 1.0.x, bridge is limited to synchronous requests, meaning that the required object is prepared and returned at once. In other words, it is not yet possible to ask for the generation of a DIP and to come back later to download it. | ||
- | == access routes overview | + | ==== Routes ==== |
< | < | ||
- | GET /access/ | + | POST |
- | GET /access/ | + | GET /changes |
- | GET /access/ | + | GET /changes/:id |
- | GET /access/ | + | PUT /changes/:id |
</ | </ | ||
- | == access routes detailed | + | ==== Create |
- | ^ Action | + | Creates |
- | | **dip** | + | |
- | | **original** | + | |
- | | **preview / file migration** | + | |
- | | **metadata** | + | |
+ | === Allowed calls === | ||
+ | POST /changes | ||
+ | === Requirements === | ||
+ | Token with role '' | ||
- | ==== 3 - changes API ==== | + | === Parameters |
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
- | Changes are similar to depositions, | + | === Examples === |
+ | < | ||
+ | curl -X POST " | ||
- | === changes statuses | + | ==== Index ==== |
- | * // | + | Lists the existing changes with details. |
- | * // | + | |
- | * // | + | |
- | * //archived: the change was successfully processed, meaning the object in the repository was updated (depending on the repository setting this may create a new version of the object or replace it) | + | |
- | * //purged//: the object was successfully purged from the repository | + | |
- | * //error//: something went wrong, see the “message” field itself located in " | + | |
- | * // | + | |
- | {{ : | + | === Allowed calls === |
+ | GET / | ||
+ | |||
+ | === Requirements === | ||
+ | Token with role '' | ||
+ | |||
+ | === Parameters === | ||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
+ | |||
+ | === Examples === | ||
+ | < | ||
+ | curl "https://bridge.docuteam.ch/ | ||
+ | curl " | ||
+ | curl " | ||
+ | curl " | ||
+ | curl " | ||
+ | |||
+ | ==== Show ==== | ||
+ | |||
+ | Retrieve the binary content of a change. | ||
+ | |||
+ | === Allowed calls === | ||
+ | GET / | ||
+ | |||
+ | === Requirements === | ||
+ | Token with role '' | ||
+ | |||
+ | === Parameters === | ||
+ | * '': | ||
+ | * '' | ||
+ | |||
+ | === Examples === | ||
+ | < | ||
+ | |||
+ | |||
+ | ==== Update ==== | ||
+ | |||
+ | Retrieve the binary content of a change. | ||
+ | |||
+ | === Allowed calls === | ||
+ | PUT / | ||
+ | |||
+ | === Requirements === | ||
+ | Token with role '' | ||
+ | |||
+ | === Parameters === | ||
+ | * '': | ||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
+ | |||
+ | === Examples === | ||
+ | < | ||
+ | curl -X PUT " | ||
- | === changes responses | + | ==== Responses ==== |
- | The changes JSON responses are similar to the deposition | + | The responses |
- | * “pid” that relates to the repository | + | * '' |
- | * “task” that describes the action performed (update, purge) | + | * '' |
- | Practically, | + | Practically, |
< | < | ||
{ " | { " | ||
{ " | { " | ||
- | " | + | " |
" | " | ||
[ | [ | ||
Zeile 243: | Zeile 454: | ||
} | } | ||
</ | </ | ||
- | |||
- | === changes routes === | ||
- | |||
- | == changes routes overview == | ||
- | |||
- | < | ||
- | POST / | ||
- | GET / | ||
- | GET / | ||
- | PUT / | ||
- | </ | ||
- | |||
- | == changes routes detailed == | ||
- | ^ Action | ||
- | | **create** | ||
- | ? | ||
- | | **list** / **show** | **HTTP GET** on /changes,\\ **parameters: | ||
- | ? | ||
- | ? | ||
- | | **retrieve binary data** | **HTTP GET** on / | ||
- | ? | ||
- | | **update** | ||
- | ? | ||
- | ? | ||
- | |||