docuteam:bridge
Unterschiede
Hier werden die Unterschiede zwischen zwei Versionen angezeigt.
Beide Seiten der vorigen RevisionVorhergehende ÜberarbeitungNächste Überarbeitung | Vorhergehende ÜberarbeitungNächste ÜberarbeitungBeide Seiten der Revision | ||
docuteam:bridge [2019/06/11 12:02] – Andreas Nef | docuteam:bridge [2020/03/13 09:13] – [Overview] Andreas Nef | ||
---|---|---|---|
Zeile 1: | Zeile 1: | ||
- | ====== docuteam bridge | + | ====== docuteam bridge ====== |
+ | Documentation for docuteam bridge v1.0.0 | ||
- | ==== Goal ==== | + | ===== Goal ===== |
- | Clients – mostly client applications, | + | |
- | {{:docuteam:bridge_v1.png?400|}} | + | 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 |
- | ==== Key points ==== | + | In the [[https://en.wikipedia.org/wiki/Open_Archival_Information_System|Open Archival Information System (OAIS)]] terminology: |
- | * Bridge is a set of rest APIs that respond in JSON (and binary data) | + | * docuteam bridge receives Submission Information Packages (SIP) on its [[docuteam:bridge# |
- | * Bridge is agnostic to package format | + | * The SIPs are processed by [[docuteam:feeder|docuteam feeder]] (quality assurance, optional initial preservation actions) and stored into a repository |
- | * Use the simple, bagit-based format docuteam dublin core 1.0 (see Appendix A) | + | * Client applications retrieve Dissemination Information Packages (DIP) of their originally submitted |
- | * Use Matterhorn METS (see [[https://wiki.docuteam.ch/lib/exe/ | + | |
- | * Use other formats, e.g. eCH-0160, SEDA | + | |
- | * Bridge is composed of 3 APIs: | + | |
- | * **depositions:** deposition of new packages | + | |
- | * **access:** read data from the repository | + | |
- | * **changes: | + | |
- | ==== Introduction to the APIs ==== | + | {{ :docuteam:bridge-situation.svg.png? |
- | For security reasons, | + | |
- | * Depositions | + | |
- | * use internal IDs | + | |
- | * upon success, the PIDs, which are the repository’s persistent IDs and different from bridge internal IDs, are made available via the feeder response field for the whole tree of the deposited objects | + | |
- | * Changes must imperatively target (for update or purge) one single object in the repository identified by a PID. They can be limited to: | + | |
- | * metadata (data is unchanged, only for updates) | + | |
- | * data (metadata is unchanged) | + | |
- | * object (metadata+data) | + | |
- | * Access | + | |
- | * is a proxy to docuteam rservices | + | |
- | ===== 1 - Authentication ===== | + | |
+ | ===== Overview ===== | ||
+ | |||
+ | * bridge is a set of REST APIs that usually return a JSON (and binary data) response. | ||
+ | * bridge is agnostic to the package format of the deposition, e.g.: | ||
+ | * Use the simple, BagIt-based format docuteam dublin core (see [[docuteam: | ||
+ | * Use Matterhorn METS (see its [[media=oais: | ||
+ | * Use other formats like [[https:// | ||
+ | * bridge consists of three APIs: | ||
+ | * **[[docuteam: | ||
+ | * New depositions are temporarily stored by bridge. They are made available to feeder, which in turn processes and stores them into the repository. | ||
+ | * Depositions are identified by bridge IDs. These identifiers are returned with the HTTP response of a new deposition request. | ||
+ | * Upon successful archiving in the repository, | ||
+ | * the status of the deposition is set to " | ||
+ | * persistent identifiers (PIDs) for each of the deposition' | ||
+ | * and the SIP is deleted from the depositions as it is now preserved in the repository. | ||
+ | * **[[docuteam: | ||
+ | * metadata only (data remains unchanged) | ||
+ | * data only (metadata remains unchanged) | ||
+ | * object (metadata and data are modified) | ||
+ | * **[[docuteam: | ||
+ | * Gives access to the full DIP corresponding to a deposited SIP. | ||
+ | * Gives access to metadata, data or previews of specific repository objects. | ||
+ | |||
+ | ===== Authentication ===== | ||
+ | |||
+ | 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 ==== | + | |
- | There are 5 roles: | + | ===== Roles ===== |
- | * The 3 first roles are limited to the organization | + | |
- | * read (is limited | + | Roles are associated to tokens and limit their scope of operation. |
- | * create | + | |
- | * manage | + | There are five roles: |
- | * The 2 last roles are not limited to any organization | + | * The following three roles are limited to a single |
- | * admin (authentication i.e. token administration | + | |
- | * feeder | + | |
+ | | ||
+ | * The following two roles have a global scope: | ||
+ | | ||
+ | | ||
+ | |||
+ | ===== Depositions API ===== | ||
+ | |||
+ | ==== Status Model ==== | ||
+ | |||
+ | 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 directly by the role " | ||
+ | |||
+ | {{ : | ||
+ | |||
+ | ==== 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 " | ||
+ | |||
+ | ==== Responses ==== | ||
+ | |||
+ | 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 structure looks like this: | ||
+ | |||
+ | < | ||
+ | { " | ||
+ | { " | ||
+ | " | ||
+ | " | ||
+ | [ | ||
+ | { " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | } | ||
+ | ] | ||
+ | " | ||
+ | { " | ||
+ | " | ||
+ | " | ||
+ | } | ||
+ | </ | ||
+ | |||
+ | Key elements include: | ||
+ | |||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
+ | |||
+ | < | ||
+ | { " | ||
+ | [ | ||
+ | { " | ||
+ | { " | ||
+ | ... | ||
+ | ], | ||
+ | " | ||
+ | } | ||
+ | </ | ||
+ | |||
+ | It must be noted that: | ||
+ | * the '' | ||
+ | * the '' | ||
+ | |||
+ | |||
+ | ===== 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 / | ||
+ | GET / | ||
+ | GET / | ||
+ | </ | ||
+ | |||
+ | ==== Metadata ==== | ||
+ | Get the EAD metadata of a repository object. | ||
+ | |||
+ | === Allowed calls === | ||
+ | GET / | ||
+ | |||
+ | === Requirements === | ||
+ | Token with role '' | ||
+ | |||
+ | === Parameters === | ||
+ | * '': | ||
+ | * '' | ||
+ | |||
+ | === Examples === | ||
+ | < | ||
+ | |||
+ | ==== 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 ===== | ||
+ | |||
+ | 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**: the change has been queued for processing in feeder | ||
+ | * **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**: | ||
+ | |||
+ | {{ : | ||
+ | |||
+ | |||
+ | ==== Routes ==== | ||
+ | |||
+ | < | ||
+ | POST / | ||
+ | GET / | ||
+ | GET / | ||
+ | PUT / | ||
+ | </ | ||
+ | |||
+ | ==== Create ==== | ||
+ | Creates a new change. | ||
+ | |||
+ | === Allowed calls === | ||
+ | POST /changes | ||
+ | |||
+ | === Requirements === | ||
+ | Token with role '' | ||
+ | |||
+ | === Parameters === | ||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
+ | |||
+ | === Examples === | ||
+ | < | ||
+ | curl -X POST " | ||
+ | |||
+ | ==== Index ==== | ||
+ | Lists the existing changes with details. | ||
+ | |||
+ | === Allowed calls === | ||
+ | GET / | ||
+ | |||
+ | === Requirements === | ||
+ | Token with role '' | ||
+ | |||
+ | === Parameters === | ||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
+ | |||
+ | === Examples === | ||
+ | < | ||
+ | curl " | ||
+ | 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 " | ||
+ | |||
+ | ==== Responses ==== | ||
+ | |||
+ | The responses on this API are similar to the [[docuteam: | ||
+ | * '' | ||
+ | * '' | ||
+ | |||
+ | Practically, | ||
- | Recommendation: | + | < |
- | | + | { " |
- | | + | |
- | | + | " |
+ | " | ||
+ | | ||
+ | { " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | } | ||
+ | | ||
+ | " | ||
+ | { " | ||
+ | "role": " | ||
+ | " | ||
+ | } | ||
+ | </ | ||
- | ===== Documentation ===== | ||
- | The documentation of docuteam bridge {{ : |