Benutzer-Werkzeuge

Webseiten-Werkzeuge


docuteam:bridge

Unterschiede

Hier werden die Unterschiede zwischen zwei Versionen angezeigt.

Link zu dieser Vergleichsansicht

Beide Seiten der vorigen Revision Vorhergehende Überarbeitung
Nächste Überarbeitung
Vorhergehende Überarbeitung
Nächste Überarbeitung Beide Seiten der Revision
docuteam:bridge [2019/09/13 13:30]
jan [1 - depositions API]
docuteam:bridge [2020/01/24 14:13]
Andreas Nef
Zeile 1: Zeile 1:
 ====== docuteam bridge ====== ====== docuteam bridge ======
-===== documentation for client applications ===== 
  
-Documentation for docuteam bridge ​v.1.0.0+Documentation for docuteam bridge ​v1.0.0
  
-===== 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 ​in a repository. After a successful ingest, feeder (and subsequently bridge) return PIDs for every object (file, folder) within the deposition. Using these PIDs, clients are able to access ​(read and change) ​the +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 ​in a preservation ​repository. After a successful ingest, feeder (and subsequently bridge) return ​persistent identifiers (PIDsfor every object (file, folder) within the deposition. Using these PIDs, clients are able to access the deposited objects ​again.
-deposited objects.+
  
 In the [[https://​en.wikipedia.org/​wiki/​Open_Archival_Information_System|Open Archival Information System (OAIS)]] terminology:​ In the [[https://​en.wikipedia.org/​wiki/​Open_Archival_Information_System|Open Archival Information System (OAIS)]] terminology:​
-  * the bridge ​deposition API recieves ​Submission Information ​Package ​(SIP) +  * docuteam ​bridge ​receives ​Submission Information ​Packages ​(SIP) on its [[docuteam:​bridge#​depositions_api|depositions API]]. 
-  * after preservation actions, the SIP are ingested into the repository ​by feeder and become ​Archival Information ​Package ​(AIP) +  * The SIPs are processed ​by [[docuteam:feeder|docuteam feeder]] (quality assurance, optional initial preservation actions) ​and stored into a repository as Archival Information ​Packages ​(AIP). 
-  * the bridge access API enables client application to retrieve Dissemination Information ​Package ​(DIP)+  * Client applications ​retrieve Dissemination Information ​Packages ​(DIP) of their originally submitted objects using the [[docuteam:​bridge#​access_api|access API]] of docuteam bridge.
  
 {{ :​docuteam:​bridge-situation.svg.png?​nolink&​200 |}} {{ :​docuteam:​bridge-situation.svg.png?​nolink&​200 |}}
  
  
-===== key points ​=====+===== Overview ​=====
  
-  * Bridge ​is a set of rest APIs that respond in JSON (and binary data) +  * bridge ​is a set of REST APIs that usually return a JSON (and binary data) response. 
-  * Bridge ​is agnostic to package format +  * bridge ​is agnostic to the package format ​of the deposition, e.g.: 
-    * Use the simple, ​bagit-based format docuteam dublin core 1.0 (see [[docuteam:​sip_dc_public_documentation|SIP docuteam dublin ​core1.0]]) +    * Use the simple, ​BagIt-based format docuteam dublin core (see [[docuteam:​sip_dc_public_documentation|SIP docuteam dublin ​core]]) 
-    * Use Matterhorn METS (see [[https://​wiki.docuteam.ch/​lib/​exe/​fetch.php?​media=oais:​spezifikation_matterhorn-mets_20160830_wi.pdf|specification]]) +    * Use Matterhorn METS (see its [[media=oais:​spezifikation_matterhorn-mets_20160830_wi.pdf|specification]] or the registered [[http://​www.loc.gov/​standards/​mets/​profiles/​00000041.xml|METS profile]]) 
-    * Use other formats like eg. eCH-0160 or SEDA. +    * Use other formats like [[https://​www.ech.ch/​de/​standards/​39187|eCH-0160]] or [[https://​redirect.francearchives.fr/​seda/​|SEDA]]
-  * Bridge is composed ​of APIs: +  * bridge consists ​of three APIs: 
-    * **depositions**:​ deposition of new packages +    * **[[docuteam:​bridge#​depositions_api|depositions]]**: deposition of new packages 
-    * **access**: read data successfully deposited ​in the repository +      * New depositions are temporarily stored by bridge. They are made available to feeder, which in turn processes and stores them into the repository. 
-    * **changes**:​ update or purge repository objects +      * Depositions are identified by bridge IDs. These identifiers are returned with the HTTP response of a new deposition request. 
-===== bridge APIs =====+      * Upon successful archiving in the repository,​ 
 +        * the status of the deposition is set to "​archived",​ 
 +        * persistent identifiers (PIDs) for each of the deposition'​s objects are returned by bridge, 
 +        * and the SIP is deleted from the depositions as it is now preserved in the repository. 
 +    * **[[docuteam:​bridge#​access_api|access]]**: read/​access ​data successfully deposited ​into the repository 
 +      * Gives access to the full DIP corresponding to a deposited SIP.  
 +      * Gives access to metadata, data or previews of specific repository objects. 
 +    * **[[docuteam:​bridge#​changes_api|changes]]**: update or purge specific ​repository objects 
 +      * metadata only (data remains unchanged) 
 +      * data only (metadata remains unchanged) 
 +      * object (metadata and data are modified)
  
-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** +===== Authentication =====
-    * 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, that are returned with the HTTP response to a deposition creation request, +
-    * upon successful archiving in the repository,​ +
-      * the status of the deposition is set to "​archived"​ +
-      * PIDs, which are the repository’s Persistent IDs are made available by bridge. PIDs are required to access (read, modify, purge) repository objects. +
-      * Each digital object in the repository (folder, file) gets its own PID and relations between the customer'​s application IDs and PIDs are explicit in the deposition metadata  +
-      * the SIP is deleted from bridge as the information is preserved by the repository +
-  * **changes** target (for update or purge) one single object in the repository identified by its PID. They can be limited to: +
-    * metadata only (data is unchanged, only for updates) +
-    * data only (metadata is unchanged) +
-    * object (metadata+data are modified) +
-  * **access** +
-    * gives access to the full DIP corresponding to a deposited SIP,  +
-    * or gives access to metadata, data or on-the-fly converted formats of specific repository objects, +
-    * this API is a proxy to docuteam rservices (a component offering high level access to Fedora objects, such as DIP and preview generation)+
  
-==== 0 - authentication and roles ==== +Access is restricted via tokens that must be transmitted with each request using the "​token"​ parameter. This is required for all HTTP methods, i.e. GET, POST, PUT, DELETE. ​Bridge relies solely on tokens for authentication an authorization. Tokens are bound to organizations ​and roles and restrict the API.
- +
-Bridge relies solely on tokens for authentication an authorization. Tokens are bound to institutions ​and roles and restrict the API usage on that basis.+
  
   * An authentication token must be at least 15 characters long.   * An authentication token must be at least 15 characters long.
-  * Tokens are passed ​via the “token” HTTP parameter, ​for example when using GET, this results in urls of the form:+  * Tokens are passed ​using a "token" ​HTTP request ​parameter, ​i.e. ''​https://​server:​port/​api/​method?​token=123456789012345''​
  
-<​code>​http://​server/​access/​sync_original/:​pid?​token=123456789012345</​code>​+===== Roles =====
  
-=== roles == +Roles are associated ​to tokens ​and limit their scope of operation.
-There are 5 roles: +
-  * The 3 first roles are limited ​to the organization they are bound to: +
-    * **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.etoken administration via the API or the GUI +
-    * **feeder**: super user, can do anything except token administration,​ including depositions status updates+
  
-=== recommendation === +There are five roles: 
-  * use only one token with read roles in applications that do not require ​to create nor update depositions,​ +  * The following three roles are limited ​to a single organization:​ 
-  use only one token with create ​role in application that make use of the deposition API but not the changes API+    * **read**: is restricted to the [[docuteam:​bridge#​access_api|access API]] 
-  * use only one token with manage role in applications that make use the changes ​API.+    * **create**: has the same authorizations as read, but can in addition list, create and delete depositions via the [[docuteam:​bridge#​depositions_api|deposition API]] 
 +    * **manage**: has the same authorizations as createand can in addition update or purge repository objects via the [[docuteam:​bridge#​changes_api|change API]] 
 +  * 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,​ including status updates for depositions of any organization.
  
-==== 1 - depositions ​API ====+===== Depositions ​API =====
  
-=== deposition statuses ​=== +==== Status Model ====
-  * //​submitted//:​ the deposition was received by bridge +
-  * //queued//: the deposition has been attributed to a queue in feeder +
-  * //​processing//:​ the deposition has been downloaded by feeder, which is processing it (preservation actions and storage in the repository) +
-  * //​archived//:​ the deposition was successfully processed by feeder and archived into the repository. Persistent identifiers allocated to the deposition'​s objects are available in bridge and the binary object has been deleted from bridge. +
-  * //error//: something went wrong during the deposition'​s processing by feeder, see “message” fields in response) +
-  * //​deleted//:​ the deposition was deleted from bridge (not from the repository!)+
  
-The deposition status can be managed by the role feeder. Other non-reader ​roles may only delete ​depositions (set the status to deleted), except ​when status is set to “processing.+Depositions have one of the following status: 
 +  * **submitted**:​ the deposition was received by bridge 
 +  * **queued**: the deposition has been queued for processing by feeder 
 +  * **processing**:​ the deposition has been downloaded by feeder, which is processing it (validation,​ quality assurance, preservation actions and storage into the repository) 
 +  * **archived**:​ the deposition was successfully processed by feeder and archived into the repository. This implies that: 
 +    * Persistent identifiers (PIDs) allocated to the deposition'​s objects are available in bridge. Each digital object in the repository (folder, file) gets its own PID, and relations between the customer'​s application IDs (if contained in the original deposition) and PIDs are explicit in the deposition metadata.\\ PIDs are required to access (read, modify, purge) repository objects through the [[docuteam:​bridge#​access_api|access API]]. 
 +    * The originally deposited package has been deleted from bridge. 
 +  * **error**: something went wrong during the deposition'​s processing by feeder. In this case, the "​message"​ fields of the deposition will contain error information. 
 +  * **deleted**:​ the deposition was deleted from bridge.\\ This only means that the deposition was removed from bridge, not from the repository. 
 + 
 +The deposition status can only be managed ​directly ​by the role "feeder". Other non-reader may only set the status implicitly by creating or deleting depositions. Deleting ​depositions (set the status to deleted) ​is blocked ​when status is either "​queued"​ or "processing".
  
 {{ :​docuteam:​bridge-status.svg.png?​nolink&​200 |}} {{ :​docuteam:​bridge-status.svg.png?​nolink&​200 |}}
  
 +==== Routes ====
 +
 +<​code>​
 +POST   /​depositions ​      ​depositions#​create
 +GET    /​depositions ​      ​depositions#​index
 +GET    /​depositions/:​id ​  ​depositions#​show
 +PUT    /​depositions/:​id ​  ​depositions#​update
 +</​code>​
 +
 +==== Create ====
 +Creates a new deposition.
 +
 +=== Allowed calls ===
 +POST   /​depositions
 +
 +=== Requirements ===
 +Token with role ''​create'',​ ''​manage'',​ or ''​feeder''​.
 +
 +=== Parameters ===
 +  * ''​token''​
 +  * ''​package_format''​ => indicate the format of the submitted package, e.g. "​MatterhornMets"​ or "​DocuteamDublincore1.0"​ (optional, default: "​MatterhornMets"​)
 +  * ''​[binary data]''​
 +
 +=== Examples ===
 +<​code>​curl -X POST -F "​package=@sip.zip"​ "​https://​bridge.docuteam.ch/​depositions?​token=123456789012345&​package_format=DocuteamDublincore1.0"</​code>​
 +
 +==== index ====
 +Lists/shows the existing depositions with details.
 +
 +=== Allowed calls ===
 +GET   /​depositions
 +
 +=== Requirements ===
 +Token with role ''​create'',​ ''​manage'',​ or ''​feeder''​.
 +
 +=== Parameters ===
 +  * ''​token''​
 +  * ''​id''​ (optional)
 +  * ''​status''​ (optional)
 +  * ''​from''​ (optional, format:​YYYY-MM-DD)
 +  * ''​until''​ (optional, format:​YYYY-MM-DD)
 +  * ''​organization''​ (optional)
 +
 +=== Examples ===
 +<​code>​curl "​https://​bridge.docuteam.ch/​depositions?​token=123456789012345"</​code>​
 +<​code>​curl "​https://​bridge.docuteam.ch/​depositions?​token=123456789012345&​id=2"</​code>​
 +<​code>​curl "​https://​bridge.docuteam.ch/​depositions?​token=123456789012345&​status=submitted"</​code>​
 +<​code>​curl "​https://​bridge.docuteam.ch/​depositions?​token=123456789012345&​status=submitted&​organization=XY"</​code>​
 +<​code>​curl "​https://​bridge.docuteam.ch/​depositions?​token=123456789012345&​from=2018-11-01&​until=2018-11-30"</​code>​
 +<​code>​curl "​https://​bridge.docuteam.ch/​depositions?​token=123456789012345&​status=error&​from=2018-11-01"</​code>​
 +
 +==== Show ====
 +Retrieve the binary content of a deposition.
 +
 +=== Allowed calls ===
 +GET    /​depositions/:​id
 +
 +=== Requirements ===
 +Token with role ''​create'',​ ''​manage'',​ or ''​feeder''​.
 +
 +=== Parameters ===
 +  * ''​token''​ (mandatory)
 +
 +=== Examples ===
 +<​code>​curl "​https://​bridge.docuteam.ch/​depositions/​1?​token=123456789012345"​ --output sip.zip</​code>​
 +
 +==== Update ====
 +Set status and processing details. By setting the status to ''​deleted'',​ the depositions binary content will be removed.
 +
 +=== Allowed calls ===
 +PUT    /​depositions/:​id
 +
 +=== Requirements ===
 +Token with role ''​create'',​ ''​manage''​ (limited to delete a deposition),​ or ''​feeder''​.
 +
 +=== Parameters ===
 +  * '':​id''​ deposition ID
 +  * ''​token''​
 +  * ''​status''​ => supported values are ''​deleted | queued | processing | archived | error''​
 +  * ''​feeder_response''​ (optional, url encoded string)
 +
 +=== Examples ===
 +<​code>​curl -X PUT "​https://​bridge.docuteam.ch/​depositions/​12345?​token=123456789012345&​status=deleted"</​code>​
 +<​code>​curl -X PUT "​https://​bridge.docuteam.ch/​depositions/​23?​token=12super34token56&​status=archived&​feeder_response=%7B%22pids%22%3A%5B%221%22%2C%222%22%5D%7D"</​code> ​
  
-=== deposition responses ​===+==== Responses ====
  
-Responses are given in JSON or a binary ​format. Each JSON response is a list of depositions metadata matching the queryGeneric ​structure:+Responses are given in JSON or (for the show method) as a binary. Each JSON response is a list of deposition with their detailsThe generic ​structure ​looks like this:
  
 <​code>​ <​code>​
 { "​api"​ : { "​api"​ :
    { "​name":​ "​docuteam bridge",​    { "​name":​ "​docuteam bridge",​
-     "​version": ​1.0.0 },+     "​version": ​"v1.0.0" ​},
  "​response"​ :  "​response"​ :
    [    [
Zeile 122: Zeile 196:
 Key elements include: Key elements include:
  
-  * id” is the deposition ​identificaterin other words bridge internal reference ​to depositions. It is notably required ​to access a specific deposition, +  * ''​id'' ​is the deposition ​identifieri.e. the bridge internal reference ​for depositions. It is used to access a specific deposition 
-  * status” is the deposition status, as described above, +  * ''​status'' ​is the deposition'​s ​status, as described above. 
-  * feeder_response” is also formatted in JSON. It is a black box from bridge'​s perspective. Upon deposition success, feeder will return a structure of the form:+  * ''​feeder_response''​ contains feedback from the processing of the deposition in feeder. The content of this field is also formatted in JSON. It is a black box from bridge'​s perspective. Upon deposition success, feeder will return a structure of the form:
  
 <​code>​ <​code>​
Zeile 138: Zeile 212:
  
 It must be noted that:  It must be noted that: 
-  * the "clientId" ​corresponds to the mandatory ​id'​s ​submitted by the client application for each object within the SIP (for example in the case of Docuteam DublinCore SIP it is located in dc.xml files and using the following syntax // <​dc:​identifier>​clientId:​d4FTw3v6T</​dc:​identifier>​ //).  +  * the ''​clientId'' ​corresponds to the mandatory ​ids submitted by the client application for each object within the SIP (for example in the case of Docuteam DublinCore SIP it is located in dc.xml files and using the following syntax // <​dc:​identifier>​clientId:​d4FTw3v6T</​dc:​identifier>​ //).  
-  * the "pid" ​is the persistent identifier allocated by the repository. It is of the form namespace:​id where namespace is generally the institutional [[https://​www.nb.admin.ch/​snl/​en/​home/​information-professionals/​isil.html|ISIL]] code (for example: CH-1234565-7:​2) ​+  * the ''​pid'' ​is the persistent identifier allocated by the repository. It is of the form "{namespace}:{id}", ​where "namespace" ​is generally the institutional ​or [[https://​www.nb.admin.ch/​snl/​en/​home/​information-professionals/​isil.html|ISIL]] code (for example: CH-1234565-7:​2), and "​id"​ the unique number for that namespace in the repository.
  
-=== 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/​thumbnail and, more generally, format migrations. 
 + 
 +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/​callback requests are not yet possible. 
 + 
 +==== Routes ====
  
 <​code>​ <​code>​
-GET    /​depositions ​      ​depositions#​index +GET   /access/​sync_metadata/:​pid ​  ​sync_metadata#download 
-POST   /depositions ​      ​depositions#create +GET   ​/access/​sync_dip/:pid        sync_dip#download 
-GET    /depositions/:id   ​depositions#show +GET   /access/​sync_original/:pid   ​sync_original#download 
-PATCH  ​/depositions/:id   ​depositions#update +GET   /access/​sync_preview/:pid    sync_preview#download
-PUT    ​/depositions/:id   ​depositions#update+
 </​code>​ </​code>​
  
-== deposition routes detailed ​== +==== Metadata ==== 
-^ Action ​     ^ Description ​      ^ Examples ​        ^+Get the EAD metadata of a repository object.
  
-| **create** ​   | HTTP POST on depositions | <​code>​curl -X POST -F "​package=@sip.zip"​ "​https://​bridge-stage.docuteam.ch/​depositions?​token=123456789012345&​package_format=DocuteamDublincore1.0"</​code> ​      | +=== Allowed calls === 
-|    | parameter: `package_format`,​ \\ constrain: binary data is mandatory |    | +GET    /access/sync_metadata/:pid
-| **list** / **show** | **HTTP GET** on /​depositions,​\\ **parameters:​** \\ - id (optional, deposition id), \\ -status (optional), \\ -from (optional, format:​YYYY-MM-DD),​ \\ -until (optional, format:​YYYY-MM-DD),​ \\ -organization (optional) ​  | <​code>​curl "​https://​bridge-stage.docuteam.ch/​depositions?​token=123456789012345"</​code>​ <​code>​curl "​https://​bridge-stage.docuteam.ch/​depositions?​token=123456789012345&​id=2"</​code>​ <​code>​curl "​https://​bridge-stage.docuteam.ch/​depositions?​token=123456789012345&​status=submitted"</​code>​ <​code>​curl "​https://​bridge-stage.docuteam.ch/​depositions?​token=123456789012345&​status=submitted&​organization=customerx"</​code>​ <​code>​curl "​https://​bridge-stage.docuteam.ch/​depositions?​token=123456789012345&​from=2018-11-01&​until=2018-11-30"</​code>​ <​code>​curl "​https://​bridge-stage.docuteam.ch/​depositions?​token=123456789012345&​status=error&​from=2018-11-01"</​code>​ | +
-| **retrieve binary data** | **HTTP ​GET** on /depositions/:id returns SIP | <​code>​curl "​https://​bridge-stage.docuteam.ch/​depositions/​1?​token=123456789012345"​ --output sip.zip</​code>​ | +
-| **update** ​     | **HTTP PUT** on /​depositions/:id  \\ **parameters:​** \\ - id (deposition_id) \\ - status (values: deleted, processing, ...) \\ - feeder_response (url encoded string)| <​code>​curl -X PUT "​https://​bridge-stage.docuteam.ch/​depositions/​12345?​token=123456789012345&​status=deleted"</​code>​ <​code>​curl -X PUT "​https://​bridge-stage.docuteam.ch/​depositions/​23?​token=12super34token56&​status=archived&​feeder_response=%7B%22pids%22%3A%5B%221%22%2C%222%22%5D%7D"</​code> ​      |+
  
-==== 2 - access API ====+=== Requirements ​=== 
 +Token with role ''​read'',​ ''​create'',​ ''​manage'', ​ or ''​admin''​.
  
-This API is 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 ​of an archival package and assembling it recursively. Another notable feature is the the on-the-fly generation of thumbnails and, more generally, format migrations.+=== Parameters === 
 +  * '':​pid''​ persistent identifier of repository ​object 
 +  * ''​token''​
  
-Bridge adds an authentication and authorization layer on top of rservices.+=== Examples === 
 +<​code>​curl "​https://​bridge.docuteam.ch/​access/​sync_metadata/​CH-123456-7:​38?​token=123456789012345"​ --output ead.xml</​code>​
  
-This API retrieves data from the archive, hence expects PIDs (and not bridge internal IDs, as it is the case for the depositions API).+==== Preview ==== 
 +Get a preview representation of a repository object.
  
-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. +=== Allowed calls === 
 +GET    /​access/​sync_preview/:​pid
  
-== access routes overview ​==+=== Requirements ​=== 
 +Token with role ''​read'',​ ''​create'',​ ''​manage'', ​ or ''​admin''​.
  
-<​code>​ +=== Parameters === 
-GET   /​access/​sync_preview/​:pid    ​sync_preview#​download +  * ''​:pid''​ persistent identifier of a repository object 
-GET   /​access/​sync_original/:​pid ​  ​sync_original#​download +  * ''​token''​
-GET   /​access/​sync_dip/:​pid ​       sync_dip#​download +
-GET   /​access/​sync_metadata/:​pid ​  ​sync_metadata#​download +
-</​code>​+
  
-== access routes detailed ​=+=== Examples ==
-^ Action ​     ^ Description ​      ​^ ​Examples ​        ^ +<​code>​curl "​https://​bridge.docuteam.ch/​access/​sync_preview/​CH-123456-7:​38?​token=123456789012345"​ --output ​file.pdf</​code>​ 
-| **dip** ​     | **HTTP GET** on /​access/​sync_dip/:​pid will generate a MatterhornMets DIP,  **parameters:​** \\ - recursively=(true or false, default is false), \\ - verifyChecksum=(true or false, default is false) ​  ​| ​<​code>​curl "​https://​bridge-stage.docuteam.ch/​access/​sync_dip/​CH-123456-7:​38?​token=123456789012345"​ --output ​dip.zip</​code> ​ <​code>​curl "​https://​bridge-stage.docuteam.ch/access/sync_dip/CH-123456-7:38?token=123456789012345&​recursively=true  --output dip.zip</​code> ​    | + 
-**original** ​     | **HTTP GET** on /​access/​sync_original/​:pid, sends back the original file from the archive ​ <​code>​curl "​https://​bridge-stage.docuteam.ch/​access/​sync_original/​CH-123456-7:​38?​token=123456789012345"​ --output file.pdf</​code> ​    | +==== Original ==== 
-| **preview / file migration** ​     | **HTTP ​GET** on /access/sync_preview/:​pid, ​compute on-the-fly and returns a file migration ​of archived file according to rservices migration settings ​ <​code>​curl "​https://​bridge-stage.docuteam.ch/​access/​sync_original/​CH-123456-7:​38?​token=123456789012345"​ --output ​file.pdf</​code> ​    | +Get the original format of a repository object. 
-| **metadata** ​     | **HTTP GET** on /​access/​sync_metadata/:​pid,​ returns the EAD metadata of object ​ | <​code>​curl "​https://​bridge-stage.docuteam.ch/​access/​sync_original/​CH-123456-7:​38?​token=123456789012345" ​--output ​ead.xml</​code> ​    |+ 
 +=== Allowed calls === 
 +GET    ​/access/sync_original/:pid 
 + 
 +=== Requirements === 
 +Token with role ''​read'',​ ''​create'',​ ''​manage'', ​ or ''​admin''​
 + 
 +=== Parameters === 
 +  ​''​:pid''​ persistent identifier of a repository object 
 +  * ''​token''​ 
 + 
 +=== Examples === 
 +<​code>​curl "​https://​bridge.docuteam.ch/​access/​sync_original/​CH-123456-7:​38?​token=123456789012345"​ --output file.pdf</​code>​ 
 + 
 +==== 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    /access/sync_dip/:pid 
 + 
 +=== Requirements === 
 +Token with role ''​read''​''​create'',​ ''​manage'', ​ or ''​admin''​. 
 + 
 +=== Parameters === 
 +  * '':​pid''​ persistent identifier ​of a repository object 
 +  * ''​token''​ 
 + 
 +=== Examples === 
 +<​code>​curl "​https://​bridge.docuteam.ch/​access/​sync_dip/​CH-123456-7:​38?​token=123456789012345"​ --output ​dip.zip</​code>​ 
 +<​code>​curl "​https://​bridge.docuteam.ch/​access/​sync_dip/​CH-123456-7:​38?​token=123456789012345&​recursively=true  ​--output ​dip.zip</​code>​
  
  
 +===== Changes API =====
  
-==== 3 - changes API ====+Changes target specific objects in the repository, using their persistent identifier (PID), in order to replace or purge them. Similar to depositions,​ they need to be queued and processed by docuteam feeder to get their effect into the repository.
  
-Changes are similar to depositions,​ however they target only on specific existing object in the repository in order to replace or purge it. The targeting is done via the object'​s PID.+==== Status Model ====
  
-=== changes statuses === +  * **submitted**: a new change corresponding to an update or purge was created in bridge 
-  ​//submitted//: a new change corresponding to an update or purge was created in bridge +  * **queued**: the change has been queued for processing ​in feeder 
-  * //queued//: the change has been attributed to a queue in feeder +  * **processing**: the change has been downloaded ​and is being processed ​by feeder 
-  * //processing: the change has been downloaded by feeder, which is processing it +  * **archived**: the change was successfully processed, ​i.e. the object in the repository was updated (depending on the repository setting this may create a new version of the object or replace it) 
-  * //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 change ​was successfully ​processed, i.e. the object was purged from the repository 
-  * //purged//: the object ​was successfully purged from the repository +  * **error**: something went wrong, see the message in the "​feeder_response" ​field of the change 
-  * //error//: something went wrong, see the message” field itself located ​in "​feeder_response" ​within ​the JSON +  * **deleted**: the change was deleted from bridge
-  * //deleted//: the change was deleted from bridge+
  
 {{ :​docuteam:​bridge-sitatus-change.svg.png?​nolink&​200 |}} {{ :​docuteam:​bridge-sitatus-change.svg.png?​nolink&​200 |}}
  
-=== changes responses ===+ 
 +==== Routes ==== 
 + 
 +<​code>​ 
 +GET   /​changes ​      ​changes#​index 
 +GET   /​changes/:​id ​  ​changes#​show 
 +POST  /​changes/:​id ​  ​changes#​create 
 +PUT   /​changes/:​id ​  ​changes#​update 
 +</​code>​ 
 + 
 +==== Create ==== 
 +Creates a new change. 
 + 
 +=== Allowed calls === 
 +POST  /changes 
 + 
 +=== Requirements === 
 +Token with role ''​read'',​ ''​create'',​ ''​manage'', ​ or ''​admin''​. 
 + 
 +=== Parameters === 
 +  * '':​pid''​ persistent identifier of a repository object 
 +  * ''​token''​ 
 + 
 +=== Examples === 
 +<​code>​curl "​https://​bridge.docuteam.ch/​access/​sync_metadata/​CH-123456-7:​38?​token=123456789012345"​ --output ead.xml</​code>​ 
 + 
 +== changes routes detailed == 
 +^ Action ​     ^ Description ​      ^ Examples ​        ^ 
 +| **create** ​     | **HTTP POST** on /​changes/:​id,​\\ ​ **parameters:​** \\ - pid (repository persistent identifier) \\ - package_fromat (default: MatterhornMets) \\ - task (data_update,​ metadata_update,​ object_update or data_delete,​ object_delete) | <​code>​curl -X POST -F "​package=@sip.zip"​ "​https://​bridge-stage.docuteam.ch/​changes 
 +          ?​token=123456789012345&​pid=CH-654321-0:​3&​task=object_update&​package_format=DocuteamDublincore1.0"</​code>​ <​code>​curl -X POST "​https://​bridge-stage.docuteam.ch/​changes/​CH-654321-0:​3?​token=123456789012345&​task=object_delete"</​code> ​      | 
 +| **list** / **show** | **HTTP GET** on /changes,\\ **parameters:​** \\ - id (optional, change id), \\ -status (optional), \\ -from (optional, format:​YYYY-MM-DD),​ \\ -until (optional, format:​YYYY-MM-DD),​ \\ -organization (optional) ​  | <​code>​curl "​https://​bridge-stage.docuteam.ch/​changes?​token=123456789012345"</​code>​ <​code>​curl "​https://​bridge-stage.docuteam.ch/​changes 
 +           ?​token=123456789012345&​id=2"</​code>​ <​code>​curl "​https://​bridge-stage.docuteam.ch/​changes?​token=123456789012345&​status=submitted"</​code>​ <​code>​curl "​https://​bridge-stage.docuteam.ch/​changes 
 +           ?​token=123456789012345&​status=submitted&​organization=customerx"</​code>​ <​code>​curl "​https://​bridge-stage.docuteam.ch/​changes?​token=123456789012345&​from=2018-11-01&​until=2018-11-30"</​code>​ <​code>​curl "​https://​bridge-stage.docuteam.ch/​changes?​token=123456789012345&​status=error&​from=2018-11-01"</​code>​ | 
 +| **retrieve binary data** | **HTTP GET** on /​changess/:​id returns SIP | <​code>​curl "​https://​bridge-stage.docuteam.ch/​changes/​1 
 +           ?​token=123456789012345"​ --output sip.zip</​code>​ | 
 +| **update** ​     | **HTTP PUT** on /​changes/:​id ​ \\ **parameters:​** \\ - id (change_id) \\ - status (values: deleted, processing, ...) \\ - task (data_update,​ metadata_update,​ object_update or data_delete,​ object_delete) ​ \\ - feeder_response (url encoded string)| <​code>​curl -X PUT "​https://​bridge-stage.docuteam.ch/​changes/​12345 
 +           ?​token=123456789012345&​status=deleted"</​code>​ <​code>​curl -X PUT "​https://​bridge-stage.docuteam.ch/​changes/​23 
 +           ?​token=12super34token56&​status=archived&​feeder_response=%7B%22pids%22%3A%5B%221%22%2C%222%22%5D%7D"</​code> ​      | 
 + 
 +==== changes responses ​====
  
 The changes JSON responses are similar to the deposition responses, but have two additional fields: The changes JSON responses are similar to the deposition responses, but have two additional fields:
-  * pid” that relates to the repository ​targeted id in the archive +  * ''​pid'' ​relates to the target ​repository ​object of the update 
-  * task” that describes the action performed (update, purge)+  * ''​task'' ​describes the action ​to be performed (update, purge)
  
-Practically, ​changes ​responses look like this:+Practically, ​change ​responses look like this:
  
 <​code>​ <​code>​
 { "​api":​ { "​api":​
   { "​name":​ "​docuteam bridge",​   { "​name":​ "​docuteam bridge",​
-    "​version": ​1.0.0 },+    "​version": ​"v1.0.0" ​},
 "​response":​ "​response":​
   [   [
Zeile 243: Zeile 392:
 } }
 </​code>​ </​code>​
- 
-=== changes routes === 
- 
-== changes routes overview == 
- 
-<​code>​ 
-POST   /​changes/:​id ​  ​changes#​update 
-GET    /​changes ​      ​changes#​index 
-GET    /​changes/:​id ​  ​changes#​show 
-PUT    /​changes/:​id ​  ​depositions#​update 
-</​code>​ 
- 
-== changes routes detailed == 
-^ Action ​     ^ Description ​      ^ Examples ​        ^ 
-| **create** ​     | **HTTP POST** on /​changes/:​id,​\\ ​ **parameters:​** \\ - pid (repository persistent identifier) \\ - package_fromat (default: MatterhornMets) \\ - task (data_update,​ metadata_update,​ object_update or data_delete,​ object_delete) | <​code>​curl -X POST -F "​package=@sip.zip"​ "​https://​bridge-stage.docuteam.ch/​changes 
-          ?​token=123456789012345&​pid=CH-654321-0:​3&​task=object_update&​package_format=DocuteamDublincore1.0"</​code>​ <​code>​curl -X POST "​https://​bridge-stage.docuteam.ch/​changes/​CH-654321-0:​3?​token=123456789012345&​task=object_delete"</​code> ​      | 
-| **list** / **show** | **HTTP GET** on /changes,\\ **parameters:​** \\ - id (optional, change id), \\ -status (optional), \\ -from (optional, format:​YYYY-MM-DD),​ \\ -until (optional, format:​YYYY-MM-DD),​ \\ -organization (optional) ​  | <​code>​curl "​https://​bridge-stage.docuteam.ch/​changes?​token=123456789012345"</​code>​ <​code>​curl "​https://​bridge-stage.docuteam.ch/​changes 
-           ?​token=123456789012345&​id=2"</​code>​ <​code>​curl "​https://​bridge-stage.docuteam.ch/​changes?​token=123456789012345&​status=submitted"</​code>​ <​code>​curl "​https://​bridge-stage.docuteam.ch/​changes 
-           ?​token=123456789012345&​status=submitted&​organization=customerx"</​code>​ <​code>​curl "​https://​bridge-stage.docuteam.ch/​changes?​token=123456789012345&​from=2018-11-01&​until=2018-11-30"</​code>​ <​code>​curl "​https://​bridge-stage.docuteam.ch/​changes?​token=123456789012345&​status=error&​from=2018-11-01"</​code>​ | 
-| **retrieve binary data** | **HTTP GET** on /​changess/:​id returns SIP | <​code>​curl "​https://​bridge-stage.docuteam.ch/​changes/​1 
-           ?​token=123456789012345"​ --output sip.zip</​code>​ | 
-| **update** ​     | **HTTP PUT** on /​changes/:​id ​ \\ **parameters:​** \\ - id (change_id) \\ - status (values: deleted, processing, ...) \\ - task (data_update,​ metadata_update,​ object_update or data_delete,​ object_delete) ​ \\ - feeder_response (url encoded string)| <​code>​curl -X PUT "​https://​bridge-stage.docuteam.ch/​changes/​12345 
-           ?​token=123456789012345&​status=deleted"</​code>​ <​code>​curl -X PUT "​https://​bridge-stage.docuteam.ch/​changes/​23 
-           ?​token=12super34token56&​status=archived&​feeder_response=%7B%22pids%22%3A%5B%221%22%2C%222%22%5D%7D"</​code> ​      | 
- 
  
docuteam/bridge.txt · Zuletzt geändert: 2020/03/13 09:14 von Andreas Nef