Benutzer-Werkzeuge

Webseiten-Werkzeuge


docuteam:bridge

Unterschiede

Hier werden die Unterschiede zwischen zwei Versionen angezeigt.

Link zu dieser Vergleichsansicht

Beide Seiten der vorigen RevisionVorhergehende Überarbeitung
Nächste Überarbeitung
Vorhergehende Überarbeitung
Nächste ÜberarbeitungBeide Seiten der Revision
docuteam:bridge [2019/09/13 13:31] – [1 - depositions API] jandocuteam:bridge [2020/03/13 09:14] – [Changes API] 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#changes_api|changes]] (under development)**: update or purge specific repository objects 
 +      * metadata only (data remains unchanged) 
 +      * data only (metadata remains unchanged) 
 +      * object (metadata and data are modified) 
 +    * **[[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.
  
-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.+===== Authentication =====
  
-  * **depositions** +Access is restricted via tokens that must be transmitted with each request using the "tokenparameterThis is required for all HTTP methodsi.eGETPOSTPUTDELETE. Bridge relies solely on tokens for authentication an authorization. Tokens are bound to organizations and roles and restrict the API.
-    * 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 bridgePIDs are required to access (read, modifypurge) 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 PIDThey can be limited to: +
-    * metadata only (data is unchangedonly 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 metadatadata 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 ==== +
- +
-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 "tokenHTTP 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"
 +curl "https://bridge.docuteam.ch/depositions?token=123456789012345&id=2"
 +curl "https://bridge.docuteam.ch/depositions?token=123456789012345&status=submitted"
 +curl "https://bridge.docuteam.ch/depositions?token=123456789012345&status=submitted&organization=XY"
 +curl "https://bridge.docuteam.ch/depositions?token=123456789012345&from=2018-11-01&until=2018-11-30"
 +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 ===
 +  * '':id'' deposition ID
 +  * ''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"
 +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'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 "clientIdcorresponds to the mandatory id'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 "pidis 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 "namespaceis 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` (default: MatterhornMets), \\ **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''
 + 
 +=== Parameters === 
 +  * '':pid'' persistent identifier of a repository object 
 +  * ''token'' 
 + 
 +=== Examples === 
 +<code>curl "https://bridge.docuteam.ch/access/sync_preview/CH-123456-7:38?token=123456789012345" --output file.pdf</code> 
 + 
 +==== Original ==== 
 +Get the original format of a repository object. 
 + 
 +=== 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 
 +curl "https://bridge.docuteam.ch/access/sync_dip/CH-123456-7:38?token=123456789012345&recursively=true  --output dip.zip</code> 
 + 
 + 
 +===== 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, they need to be queued and processed by docuteam feeder to get their effect into the repository. 
 + 
 +==== Status Model ==== 
 + 
 +  * **submitted**: a new change corresponding to an update or purge was created in bridge 
 +  * **queued**: the change has been queued for processing in feeder 
 +  * **processing**: the change has been downloaded and is being processed by feeder 
 +  * **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) 
 +  * **purged**: the change was successfully processed, i.e. the object was purged from the repository 
 +  * **error**: something went wrong, see the message in the "feeder_response" field of the change 
 +  * **deleted**: the change was deleted from bridge 
 + 
 +{{ :docuteam:bridge-sitatus-change.svg.png?nolink&200 |}} 
 + 
 + 
 +==== Routes ====
  
 <code> <code>
-GET   /access/sync_preview/:pid    sync_preview#download +POST  /changes        changes#create 
-GET   /access/sync_original/:pid   sync_original#download +GET   /changes        changes#index 
-GET   /access/sync_dip/:pid        sync_dip#download +GET   /changes/:id   changes#show 
-GET   /access/sync_metadata/:pid   sync_metadata#download+PUT   /changes/:id   changes#update
 </code> </code>
  
-== access routes detailed == +==== Create ==== 
-^ Action      ^ Description       ^ Examples         ^ +Creates new change.
-| **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>     | +
-| **preview / file migration**      | **HTTP GET** on /access/sync_preview/:pid, compute on-the-fly and returns 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>     | +
-| **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 ===
 +POST  /changes
  
 +=== Requirements ===
 +Token with role ''manage'' or ''admin''.
  
-==== 3 - changes API ====+=== Parameters === 
 +  * ''pid'' persistent identifier of a repository object 
 +  * ''token'' 
 +  * ''task'' => type of change, e.g. ''data_update'', ''metadata_update'', ''object_update'', ''data_delete'', or ''object_delete'' 
 +  * ''package_format'' => indicate the format of the submitted package, e.g. ''MatterhornMets'' or ''DocuteamDublincore1.0'' (optional, default: ''MatterhornMets''
 +  * ''[binary data]'' => mandatory if task is "*_update"
  
-Changes are similar to depositions, however they target only on specific existing object in the repository in order to replace or purge itThe targeting is done via the object's PID.+=== Examples === 
 +<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" 
 +curl -X POST "https://bridge-stage.docuteam.ch/changes?token=123456789012345&pid=CH-654321-0:3&task=object_delete"</code>
  
-=== changes statuses === +==== Index ==== 
-  * //submitted//: a new change corresponding to an update or purge was created in bridge +Lists the existing changes with details.
-  * //queued//: the change has been attributed to a queue in feeder +
-  * //processing: the change has been downloaded by feeder, which is processing 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 object was successfully purged from the repository +
-  * //error//: something went wrong, see the “message” field itself located in "feeder_response" within the JSON +
-  * //deleted//: the change was deleted from bridge+
  
-{{ :docuteam:bridge-sitatus-change.svg.png?nolink&200 |}}+=== Allowed calls === 
 +GET   /changes 
 + 
 +=== Requirements === 
 +Token with role ''manage'' or ''feeder''
 + 
 +=== Parameters === 
 +  * ''token'' 
 +  * ''id'' (optional) 
 +  * ''status'' (optional) 
 +  * ''from'' (optional, format:YYYY-MM-DD) 
 +  * ''until'' (optional, format:YYYY-MM-DD) 
 +  * ''user'' (optional) 
 +  * ''organization'' (optional) 
 + 
 +=== Examples === 
 +<code>curl "https://bridge.docuteam.ch/changes?token=123456789012345" 
 +curl "https://bridge.docuteam.ch/changes?token=123456789012345&id=2" 
 +curl "https://bridge.docuteam.ch/changes?token=123456789012345&status=submitted" 
 +curl "https://bridge.docuteam.ch/changes?token=123456789012345&status=submitted&organization=customerx" 
 +curl "https://bridge.docuteam.ch/changes?token=123456789012345&from=2018-11-01&until=2018-11-30" 
 +curl "https://bridge.docuteam.ch/changes?token=123456789012345&status=error&from=2018-11-01"</code> 
 + 
 +==== Show ==== 
 + 
 +Retrieve the binary content of a change. 
 + 
 +=== Allowed calls === 
 +GET   /changes/:id 
 + 
 +=== Requirements === 
 +Token with role ''manage'' or ''admin''
 + 
 +=== Parameters === 
 +  * '':id'' change ID 
 +  * ''token'' 
 + 
 +=== Examples === 
 +<code>curl "https://bridge.docuteam.ch/changes/1?token=123456789012345" --output sip.zip</code> 
 + 
 + 
 +==== Update ==== 
 + 
 +Retrieve the binary content of a change. 
 + 
 +=== Allowed calls === 
 +PUT   /changes/:id 
 + 
 +=== Requirements === 
 +Token with role ''manage'' or ''admin''
 + 
 +=== Parameters === 
 +  * '':id'' change ID 
 +  * ''token'' 
 +  * ''status'' => supported values are ''data_update metadata_update | object_update | data_delete | object_delete'' 
 +  * ''feeder_response'' (optional, url encoded string) 
 + 
 +=== Examples === 
 +<code>curl -X PUT "https://bridge.docuteam.ch/changes/12345?token=123456789012345&status=deleted" 
 +curl -X PUT "https://bridge.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 ===+==== Responses ====
  
-The changes JSON responses are similar to the deposition responses, but have two additional fields: +The responses on this API are similar to the [[docuteam:bridge#depositions_api|depositions API]] 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 447:
 } }
 </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>       | 
- 
  

Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki