https://wiki.archivematica.org/api.php?action=feedcontributions&user=Mcantelon&feedformat=atomArchivematica - User contributions [en]2024-03-28T08:16:36ZUser contributionsMediaWiki 1.35.4https://wiki.archivematica.org/index.php?title=Widget:Twitter_Search&diff=11509Widget:Twitter Search2016-12-20T20:01:16Z<p>Mcantelon: </p>
<hr />
<div><noinclude>__NOTOC__<br />
Embed twitter widget<br />
<br />
Based on widget by [http://www.mediawikiwidgets.org/User:Sergey_Chernyshev Sergey Chernyshev]<br />
<br />
== Using this widget ==<br />
For information on how to use this widget, see [http://www.mediawikiwidgets.org/Twitter_Search widget description page on MediaWikiWidgets.org].<br />
</noinclude><includeonly><a class="twitter-timeline" data-height="800" href="https://twitter.com/archivematica">Tweets by archivematica</a> <script async src="//platform.twitter.com/widgets.js" charset="utf-8"></script><br />
</includeonly></div>Mcantelonhttps://wiki.archivematica.org/index.php?title=Widget:Twitter_Search&diff=11508Widget:Twitter Search2016-12-20T19:59:58Z<p>Mcantelon: </p>
<hr />
<div><noinclude>__NOTOC__<br />
Embed twitter widget<br />
<br />
Based on widget by [http://www.mediawikiwidgets.org/User:Sergey_Chernyshev Sergey Chernyshev]<br />
<br />
== Using this widget ==<br />
For information on how to use this widget, see [http://www.mediawikiwidgets.org/Twitter_Search widget description page on MediaWikiWidgets.org].<br />
</noinclude><includeonly><a class="twitter-timeline" href="https://twitter.com/archivematica">Tweets by Archivematica</a> <script async src="//platform.twitter.com/widgets.js" charset="utf-8"></script><br />
</includeonly></div>Mcantelonhttps://wiki.archivematica.org/index.php?title=Widget:Twitter_Search&diff=11507Widget:Twitter Search2016-12-20T19:33:41Z<p>Mcantelon: </p>
<hr />
<div><noinclude>__NOTOC__<br />
Embed twitter widget<br />
<br />
Based on widget by [http://www.mediawikiwidgets.org/User:Sergey_Chernyshev Sergey Chernyshev]<br />
<br />
== Using this widget ==<br />
For information on how to use this widget, see [http://www.mediawikiwidgets.org/Twitter_Search widget description page on MediaWikiWidgets.org].<br />
</noinclude><includeonly><a class="twitter-timeline" href="https://twitter.com/search?q=from:archivematica" height="300" width="100%" data-widget-id="345659717298814976" data-chrome="noheader nofooter noscrollbar">Tweets about "archivematica"</a><br />
<script>!function(d,s,id){var js,fjs=d.getElementsByTagName(s)[0],p=/^http:/.test(d.location)?'http':'https';if(!d.getElementById(id)){js=d.createElement(s);js.id=id;js.src=p+"://platform.twitter.com/widgets.js";fjs.parentNode.insertBefore(js,fjs);}}(document,"script","twitter-wjs");</script><br />
</includeonly></div>Mcantelonhttps://wiki.archivematica.org/index.php?title=Main_Page&diff=11505Main Page2016-12-19T08:40:32Z<p>Mcantelon: /* Twitter */</p>
<hr />
<div><div style="background: #fff; float: right; padding: 1em; width: 30%"><br />
<div class="download"><br />
<br />
== Free Demo and Download ==<br />
* [http://sandbox.archivematica.org Demo] - see [[Sandbox|Sandbox info]] for login<br />
* [[Release Notes|Release notes]]<br />
* [https://ww.archivematica.org/en/docs/latest/admin-manual/installation/installation/#installation Installation]<br />
* [http://www.artefactual.com/services/ Installation services]<br />
<br />
<br />
</div><br />
<br />
<div class="documentation"><br />
<br />
== [https://www.archivematica.org/ How to use Archivematica] ==<br />
* User and administrative manuals at [http://www.archivematica.org archivematica.org]<br />
* [https://www.artefactual.com/services/training/ Training services]<br />
<br />
</div><br />
<br />
<div class="development"><br />
<br />
== [[Development|Developer resources]] ==<br />
*[[Development roadmap: Archivematica|Development roadmap]]<br />
* Development [[Documentation|documentation]]<br />
*[https://projects.artefactual.com/projects/archivematica Issues list]<br />
*[https://www.artefactual.com/partners/ Become an innovation partner]<br />
<br />
<br />
</div><br />
<br />
<div class="community"><br />
<br />
== [[Community|Community]] ==<br />
*[https://groups.google.com/group/archivematica Discussion list]<br />
*[[Community|Free community resources]]<br />
*[http://www.artefactual.com/services/archivematica/maintenance/ Get support]<br />
*[[Contributors|Contributors]]<br />
<br />
</div><br />
<br />
<div class="twitter"><br />
<br />
== Twitter ==<br />
<br />
{{#widget:Twitter Search}}<br />
<br />
</div><br />
<br />
<div class="news"><br />
<br />
<br />
<br />
</div><br />
<br />
</div><div style="overflow: hidden;"><br />
<br />
== ''This is the Archivematica development wiki. For user and administrative manuals, as well as installation information, please visit [http://www.archivematica.org archivematica.org].'' ==<br />
<br />
='''What is Archivematica?'''=<br />
<br />
Archivematica is a free and open-source [[wikipedia:Digital preservation|digital preservation]] system that is designed to maintain long-term access to digital memory. Archivematica is packaged with the web-based content management system [https://www.accesstomemory.org/ AtoM] for access to your digital objects.<br />
<br />
The [[overview]] section provides a detailed description of Archivematica's functionality and technical architecture. This screencast gives a demo of the core features in the most current release of the system. <br />
<br />
{| width="100%" border="0" style="margin: 20px 0;" class="youtube"<br />
| align="center" | <youtube>EjStNDXK48U</youtube><br />
|}<br />
<br />
==='''Standards-based'''===<br />
<br />
Archivematica uses a [http://en.wikipedia.org/wiki/Microservices micro-services] design pattern to provide an integrated suite of software tools that allows users to process digital objects from ingest to access in compliance with the ISO-OAIS functional model. Users monitor and control the micro-services via a web-based dashboard. Archivematica uses METS, PREMIS (events, agents, rights and restrictions), Dublin Core, the Library of Congress BagIt specification and other best practice standards and practices to provide trustworthy, authentic, reliable, and interoperable archival packages (AIPs) for storage in your preferred repository.<br />
<br />
==='''Open source'''===<br />
<br />
All Archivematica code is released under a GNU Affero General Public License ([http://www.gnu.org/licenses/agpl.html AGPL 3.0]) – giving you the freedom to study, modify, improve, and distribute it. We believe that an important part of preservation is transparency, and that memory institutions should be able to demonstrate at every stage what happens when they process cultural heritage materials for preservation. Archivematica [https://github.com/artefactual code] is always freely available, and our documentation is also released under a Creative Commons Share-alike license.<br />
<br />
==='''Flexible and customizable'''===<br />
<br />
Archivematica provides several decision points that give the user control over choices about format identification tools, printing the original order of the directories ingested, examining contents for private and personal information, extracting contents of packages and forensic images, transcribing content, and more. Users may also preconfigure most of these options for seamless ingest to archival storage and access. Archivematica offers many ingest workflows: metadata and submission documentation import, zipped and unzipped Bag ingest, digital forensic image processing, SIP arrangement, manual normalization, and dataset management.<br />
<br />
==='''Compatible with hundreds of formats'''===<br />
<br />
In the Format Policy Registry (FPR), Archivematica implements its default [[media type preservation plans|format policies]] based on an analysis of the [[significant characteristics]] of file formats. The FPR also offers an editable, flexible framework for format identification, package extraction, transcription and normalization for preservation and access. Your institution can update tools, rules and commands in your local FPR from the Artefactual-managed FPR server. You can also add your own, local policies to your internal FPR. The FPR is integrated with PRONOM.<br />
<br />
==='''Advanced search and storage management'''===<br />
<br />
You can easily search your backlog and your archival storage from within your Archivematica web-based dashboard. This means you can download stored AIPs as complete packages, individual objects, or every package in an AIC. You can also manage your storage and processing locations using the Archivematica Storage Service, including a two-step deletion process that requires justification and approval to eliminate a stored AIP.<br />
<br />
==='''Integration with third-parties'''===<br />
<br />
Memory institutions have dedicated voluminous resources over the past couple of decades to implement various software platforms and tools to manage digital objects. For this reason, we believe in leveraging the strength of other tools and integrating with them wherever possible. Highlights include: [https://www.accesstomemory.org/en/ AtoM], [http://www.dspace.org/ DSpace], [http://www.contentdm.org/ CONTENTdm], [http://islandora.ca/ Islandora], [http://www.lockss.org/ LOCKSS], [http://www.duracloud.org/ DuraCloud], [http://arkivum.com/ Arkivum], [http://www.openstack.org/ OpenStack] and [http://www.archiviststoolkit.org/ Archivists' Toolkit]<br />
<br />
The software applications integrated into Archivematica are each released under their own open source license. These are checked for license compatibility before they are integrated into the project. A full list of applications with their respective license is available on the [[External tools|external software tools]] page.<br />
<br />
==='''Lead developers and partners'''===<br />
This project is managed by [http://artefactual.com/archivematica.html Artefactual Systems] in collaboration with the UNESCO Memory of the World's [http://portal.unesco.org/ci/en/ev.php-URL_ID=1720&URL_DO=DO_TOPIC&URL_SECTION=201.html Subcommittee on Technology], the [http://vancouver.ca/ctyclerk/archives/ City of Vancouver Archives], [http://www.library.hbs.edu/ Harvard Business School Baker Library], the [http://www.moma.org/ Museum of Modern Art (MoMA)], the [http://www.library.ualberta.ca/ University of Alberta Libraries], the [http://diginit.library.ubc.ca/ University of British Columbia Library], the [http://rockarch.org/ Rockefeller Archive Center], [http://www.sfu.ca/archives/ Simon Fraser University Archives and Records Management], [http://www.library.yale.edu/ Yale University Library], [http://www.zib.de/en/home.html Zuse-Institute Berlin], [http://www.coppul.ca/ Council of Prairie and Pacific University Libraries (COPPUL)], [http://bentley.umich.edu/ Bentley Historical Library, University of Michigan], [http://duraspace.org Duraspace], [http://libraries.mit.edu/ MIT Libraries], [http://www.ocul.on.ca/ Ontario Council of University Libraries], [https://www.llgc.org.uk/ National Library of Wales] and a number of other collaborators.<br />
</div><br />
<br />
[[File:Artefactual_Logo.png|240px|center|link=http://www.artefactual.com/]]<br />
</div><br />
[[File:Cva.gif|160px]] [[File:Ubcblue_full.png|80px]] [[File:RAC-logo.png|80px]] [[File:Logo_en.gif|140px]][[File:SFULogo.jpg|150px]] [[File:UofAlogo.png|180px]][[File:LOGO_ulib_4cp_under75_png_4f05de2698.png|200px]] [[File:MoMA.png|180px]] [[File:FinalULBlues_copy.png|300px]] [[File:ZIBlogo-mediumlines.png|75px]] [[File:HarvardBaker30_image.png|250px]] [[File:Coppullogo.jpg]] [[File:UM-BHL-logo.png|120px]] [[File:DuraSpace_logo_horiz_300.png|260px]][[File:Mit_logo.png]] [[File:ocul_logo.png|200 px]] [[File:york_logo.png|240px]] [[File:hull_logo.png|220px]] [[File:Logo_arkivum_blk.png|200px]] [[File:NLW_logo1.jpg|330px]]<br />
<br />
<br />
<br />
<br />
<br />
__NOTOC__</div>Mcantelonhttps://wiki.archivematica.org/index.php?title=Main_Page&diff=11504Main Page2016-12-19T08:40:13Z<p>Mcantelon: /* Twitter */</p>
<hr />
<div><div style="background: #fff; float: right; padding: 1em; width: 30%"><br />
<div class="download"><br />
<br />
== Free Demo and Download ==<br />
* [http://sandbox.archivematica.org Demo] - see [[Sandbox|Sandbox info]] for login<br />
* [[Release Notes|Release notes]]<br />
* [https://ww.archivematica.org/en/docs/latest/admin-manual/installation/installation/#installation Installation]<br />
* [http://www.artefactual.com/services/ Installation services]<br />
<br />
<br />
</div><br />
<br />
<div class="documentation"><br />
<br />
== [https://www.archivematica.org/ How to use Archivematica] ==<br />
* User and administrative manuals at [http://www.archivematica.org archivematica.org]<br />
* [https://www.artefactual.com/services/training/ Training services]<br />
<br />
</div><br />
<br />
<div class="development"><br />
<br />
== [[Development|Developer resources]] ==<br />
*[[Development roadmap: Archivematica|Development roadmap]]<br />
* Development [[Documentation|documentation]]<br />
*[https://projects.artefactual.com/projects/archivematica Issues list]<br />
*[https://www.artefactual.com/partners/ Become an innovation partner]<br />
<br />
<br />
</div><br />
<br />
<div class="community"><br />
<br />
== [[Community|Community]] ==<br />
*[https://groups.google.com/group/archivematica Discussion list]<br />
*[[Community|Free community resources]]<br />
*[http://www.artefactual.com/services/archivematica/maintenance/ Get support]<br />
*[[Contributors|Contributors]]<br />
<br />
</div><br />
<br />
<div class="twitter"><br />
<br />
== Twitter ==<br />
<br />
{{#widget:Twitter Search|query=atom}}<br />
<br />
</div><br />
<br />
<div class="news"><br />
<br />
<br />
<br />
</div><br />
<br />
</div><div style="overflow: hidden;"><br />
<br />
== ''This is the Archivematica development wiki. For user and administrative manuals, as well as installation information, please visit [http://www.archivematica.org archivematica.org].'' ==<br />
<br />
='''What is Archivematica?'''=<br />
<br />
Archivematica is a free and open-source [[wikipedia:Digital preservation|digital preservation]] system that is designed to maintain long-term access to digital memory. Archivematica is packaged with the web-based content management system [https://www.accesstomemory.org/ AtoM] for access to your digital objects.<br />
<br />
The [[overview]] section provides a detailed description of Archivematica's functionality and technical architecture. This screencast gives a demo of the core features in the most current release of the system. <br />
<br />
{| width="100%" border="0" style="margin: 20px 0;" class="youtube"<br />
| align="center" | <youtube>EjStNDXK48U</youtube><br />
|}<br />
<br />
==='''Standards-based'''===<br />
<br />
Archivematica uses a [http://en.wikipedia.org/wiki/Microservices micro-services] design pattern to provide an integrated suite of software tools that allows users to process digital objects from ingest to access in compliance with the ISO-OAIS functional model. Users monitor and control the micro-services via a web-based dashboard. Archivematica uses METS, PREMIS (events, agents, rights and restrictions), Dublin Core, the Library of Congress BagIt specification and other best practice standards and practices to provide trustworthy, authentic, reliable, and interoperable archival packages (AIPs) for storage in your preferred repository.<br />
<br />
==='''Open source'''===<br />
<br />
All Archivematica code is released under a GNU Affero General Public License ([http://www.gnu.org/licenses/agpl.html AGPL 3.0]) – giving you the freedom to study, modify, improve, and distribute it. We believe that an important part of preservation is transparency, and that memory institutions should be able to demonstrate at every stage what happens when they process cultural heritage materials for preservation. Archivematica [https://github.com/artefactual code] is always freely available, and our documentation is also released under a Creative Commons Share-alike license.<br />
<br />
==='''Flexible and customizable'''===<br />
<br />
Archivematica provides several decision points that give the user control over choices about format identification tools, printing the original order of the directories ingested, examining contents for private and personal information, extracting contents of packages and forensic images, transcribing content, and more. Users may also preconfigure most of these options for seamless ingest to archival storage and access. Archivematica offers many ingest workflows: metadata and submission documentation import, zipped and unzipped Bag ingest, digital forensic image processing, SIP arrangement, manual normalization, and dataset management.<br />
<br />
==='''Compatible with hundreds of formats'''===<br />
<br />
In the Format Policy Registry (FPR), Archivematica implements its default [[media type preservation plans|format policies]] based on an analysis of the [[significant characteristics]] of file formats. The FPR also offers an editable, flexible framework for format identification, package extraction, transcription and normalization for preservation and access. Your institution can update tools, rules and commands in your local FPR from the Artefactual-managed FPR server. You can also add your own, local policies to your internal FPR. The FPR is integrated with PRONOM.<br />
<br />
==='''Advanced search and storage management'''===<br />
<br />
You can easily search your backlog and your archival storage from within your Archivematica web-based dashboard. This means you can download stored AIPs as complete packages, individual objects, or every package in an AIC. You can also manage your storage and processing locations using the Archivematica Storage Service, including a two-step deletion process that requires justification and approval to eliminate a stored AIP.<br />
<br />
==='''Integration with third-parties'''===<br />
<br />
Memory institutions have dedicated voluminous resources over the past couple of decades to implement various software platforms and tools to manage digital objects. For this reason, we believe in leveraging the strength of other tools and integrating with them wherever possible. Highlights include: [https://www.accesstomemory.org/en/ AtoM], [http://www.dspace.org/ DSpace], [http://www.contentdm.org/ CONTENTdm], [http://islandora.ca/ Islandora], [http://www.lockss.org/ LOCKSS], [http://www.duracloud.org/ DuraCloud], [http://arkivum.com/ Arkivum], [http://www.openstack.org/ OpenStack] and [http://www.archiviststoolkit.org/ Archivists' Toolkit]<br />
<br />
The software applications integrated into Archivematica are each released under their own open source license. These are checked for license compatibility before they are integrated into the project. A full list of applications with their respective license is available on the [[External tools|external software tools]] page.<br />
<br />
==='''Lead developers and partners'''===<br />
This project is managed by [http://artefactual.com/archivematica.html Artefactual Systems] in collaboration with the UNESCO Memory of the World's [http://portal.unesco.org/ci/en/ev.php-URL_ID=1720&URL_DO=DO_TOPIC&URL_SECTION=201.html Subcommittee on Technology], the [http://vancouver.ca/ctyclerk/archives/ City of Vancouver Archives], [http://www.library.hbs.edu/ Harvard Business School Baker Library], the [http://www.moma.org/ Museum of Modern Art (MoMA)], the [http://www.library.ualberta.ca/ University of Alberta Libraries], the [http://diginit.library.ubc.ca/ University of British Columbia Library], the [http://rockarch.org/ Rockefeller Archive Center], [http://www.sfu.ca/archives/ Simon Fraser University Archives and Records Management], [http://www.library.yale.edu/ Yale University Library], [http://www.zib.de/en/home.html Zuse-Institute Berlin], [http://www.coppul.ca/ Council of Prairie and Pacific University Libraries (COPPUL)], [http://bentley.umich.edu/ Bentley Historical Library, University of Michigan], [http://duraspace.org Duraspace], [http://libraries.mit.edu/ MIT Libraries], [http://www.ocul.on.ca/ Ontario Council of University Libraries], [https://www.llgc.org.uk/ National Library of Wales] and a number of other collaborators.<br />
</div><br />
<br />
[[File:Artefactual_Logo.png|240px|center|link=http://www.artefactual.com/]]<br />
</div><br />
[[File:Cva.gif|160px]] [[File:Ubcblue_full.png|80px]] [[File:RAC-logo.png|80px]] [[File:Logo_en.gif|140px]][[File:SFULogo.jpg|150px]] [[File:UofAlogo.png|180px]][[File:LOGO_ulib_4cp_under75_png_4f05de2698.png|200px]] [[File:MoMA.png|180px]] [[File:FinalULBlues_copy.png|300px]] [[File:ZIBlogo-mediumlines.png|75px]] [[File:HarvardBaker30_image.png|250px]] [[File:Coppullogo.jpg]] [[File:UM-BHL-logo.png|120px]] [[File:DuraSpace_logo_horiz_300.png|260px]][[File:Mit_logo.png]] [[File:ocul_logo.png|200 px]] [[File:york_logo.png|240px]] [[File:hull_logo.png|220px]] [[File:Logo_arkivum_blk.png|200px]] [[File:NLW_logo1.jpg|330px]]<br />
<br />
<br />
<br />
<br />
<br />
__NOTOC__</div>Mcantelonhttps://wiki.archivematica.org/index.php?title=Main_Page&diff=11503Main Page2016-12-19T08:39:14Z<p>Mcantelon: /* Twitter */</p>
<hr />
<div><div style="background: #fff; float: right; padding: 1em; width: 30%"><br />
<div class="download"><br />
<br />
== Free Demo and Download ==<br />
* [http://sandbox.archivematica.org Demo] - see [[Sandbox|Sandbox info]] for login<br />
* [[Release Notes|Release notes]]<br />
* [https://ww.archivematica.org/en/docs/latest/admin-manual/installation/installation/#installation Installation]<br />
* [http://www.artefactual.com/services/ Installation services]<br />
<br />
<br />
</div><br />
<br />
<div class="documentation"><br />
<br />
== [https://www.archivematica.org/ How to use Archivematica] ==<br />
* User and administrative manuals at [http://www.archivematica.org archivematica.org]<br />
* [https://www.artefactual.com/services/training/ Training services]<br />
<br />
</div><br />
<br />
<div class="development"><br />
<br />
== [[Development|Developer resources]] ==<br />
*[[Development roadmap: Archivematica|Development roadmap]]<br />
* Development [[Documentation|documentation]]<br />
*[https://projects.artefactual.com/projects/archivematica Issues list]<br />
*[https://www.artefactual.com/partners/ Become an innovation partner]<br />
<br />
<br />
</div><br />
<br />
<div class="community"><br />
<br />
== [[Community|Community]] ==<br />
*[https://groups.google.com/group/archivematica Discussion list]<br />
*[[Community|Free community resources]]<br />
*[http://www.artefactual.com/services/archivematica/maintenance/ Get support]<br />
*[[Contributors|Contributors]]<br />
<br />
</div><br />
<br />
<div class="twitter"><br />
<br />
== Twitter ==<br />
<br />
{{#widget:Twitter Search}}<br />
<br />
</div><br />
<br />
<div class="news"><br />
<br />
<br />
<br />
</div><br />
<br />
</div><div style="overflow: hidden;"><br />
<br />
== ''This is the Archivematica development wiki. For user and administrative manuals, as well as installation information, please visit [http://www.archivematica.org archivematica.org].'' ==<br />
<br />
='''What is Archivematica?'''=<br />
<br />
Archivematica is a free and open-source [[wikipedia:Digital preservation|digital preservation]] system that is designed to maintain long-term access to digital memory. Archivematica is packaged with the web-based content management system [https://www.accesstomemory.org/ AtoM] for access to your digital objects.<br />
<br />
The [[overview]] section provides a detailed description of Archivematica's functionality and technical architecture. This screencast gives a demo of the core features in the most current release of the system. <br />
<br />
{| width="100%" border="0" style="margin: 20px 0;" class="youtube"<br />
| align="center" | <youtube>EjStNDXK48U</youtube><br />
|}<br />
<br />
==='''Standards-based'''===<br />
<br />
Archivematica uses a [http://en.wikipedia.org/wiki/Microservices micro-services] design pattern to provide an integrated suite of software tools that allows users to process digital objects from ingest to access in compliance with the ISO-OAIS functional model. Users monitor and control the micro-services via a web-based dashboard. Archivematica uses METS, PREMIS (events, agents, rights and restrictions), Dublin Core, the Library of Congress BagIt specification and other best practice standards and practices to provide trustworthy, authentic, reliable, and interoperable archival packages (AIPs) for storage in your preferred repository.<br />
<br />
==='''Open source'''===<br />
<br />
All Archivematica code is released under a GNU Affero General Public License ([http://www.gnu.org/licenses/agpl.html AGPL 3.0]) – giving you the freedom to study, modify, improve, and distribute it. We believe that an important part of preservation is transparency, and that memory institutions should be able to demonstrate at every stage what happens when they process cultural heritage materials for preservation. Archivematica [https://github.com/artefactual code] is always freely available, and our documentation is also released under a Creative Commons Share-alike license.<br />
<br />
==='''Flexible and customizable'''===<br />
<br />
Archivematica provides several decision points that give the user control over choices about format identification tools, printing the original order of the directories ingested, examining contents for private and personal information, extracting contents of packages and forensic images, transcribing content, and more. Users may also preconfigure most of these options for seamless ingest to archival storage and access. Archivematica offers many ingest workflows: metadata and submission documentation import, zipped and unzipped Bag ingest, digital forensic image processing, SIP arrangement, manual normalization, and dataset management.<br />
<br />
==='''Compatible with hundreds of formats'''===<br />
<br />
In the Format Policy Registry (FPR), Archivematica implements its default [[media type preservation plans|format policies]] based on an analysis of the [[significant characteristics]] of file formats. The FPR also offers an editable, flexible framework for format identification, package extraction, transcription and normalization for preservation and access. Your institution can update tools, rules and commands in your local FPR from the Artefactual-managed FPR server. You can also add your own, local policies to your internal FPR. The FPR is integrated with PRONOM.<br />
<br />
==='''Advanced search and storage management'''===<br />
<br />
You can easily search your backlog and your archival storage from within your Archivematica web-based dashboard. This means you can download stored AIPs as complete packages, individual objects, or every package in an AIC. You can also manage your storage and processing locations using the Archivematica Storage Service, including a two-step deletion process that requires justification and approval to eliminate a stored AIP.<br />
<br />
==='''Integration with third-parties'''===<br />
<br />
Memory institutions have dedicated voluminous resources over the past couple of decades to implement various software platforms and tools to manage digital objects. For this reason, we believe in leveraging the strength of other tools and integrating with them wherever possible. Highlights include: [https://www.accesstomemory.org/en/ AtoM], [http://www.dspace.org/ DSpace], [http://www.contentdm.org/ CONTENTdm], [http://islandora.ca/ Islandora], [http://www.lockss.org/ LOCKSS], [http://www.duracloud.org/ DuraCloud], [http://arkivum.com/ Arkivum], [http://www.openstack.org/ OpenStack] and [http://www.archiviststoolkit.org/ Archivists' Toolkit]<br />
<br />
The software applications integrated into Archivematica are each released under their own open source license. These are checked for license compatibility before they are integrated into the project. A full list of applications with their respective license is available on the [[External tools|external software tools]] page.<br />
<br />
==='''Lead developers and partners'''===<br />
This project is managed by [http://artefactual.com/archivematica.html Artefactual Systems] in collaboration with the UNESCO Memory of the World's [http://portal.unesco.org/ci/en/ev.php-URL_ID=1720&URL_DO=DO_TOPIC&URL_SECTION=201.html Subcommittee on Technology], the [http://vancouver.ca/ctyclerk/archives/ City of Vancouver Archives], [http://www.library.hbs.edu/ Harvard Business School Baker Library], the [http://www.moma.org/ Museum of Modern Art (MoMA)], the [http://www.library.ualberta.ca/ University of Alberta Libraries], the [http://diginit.library.ubc.ca/ University of British Columbia Library], the [http://rockarch.org/ Rockefeller Archive Center], [http://www.sfu.ca/archives/ Simon Fraser University Archives and Records Management], [http://www.library.yale.edu/ Yale University Library], [http://www.zib.de/en/home.html Zuse-Institute Berlin], [http://www.coppul.ca/ Council of Prairie and Pacific University Libraries (COPPUL)], [http://bentley.umich.edu/ Bentley Historical Library, University of Michigan], [http://duraspace.org Duraspace], [http://libraries.mit.edu/ MIT Libraries], [http://www.ocul.on.ca/ Ontario Council of University Libraries], [https://www.llgc.org.uk/ National Library of Wales] and a number of other collaborators.<br />
</div><br />
<br />
[[File:Artefactual_Logo.png|240px|center|link=http://www.artefactual.com/]]<br />
</div><br />
[[File:Cva.gif|160px]] [[File:Ubcblue_full.png|80px]] [[File:RAC-logo.png|80px]] [[File:Logo_en.gif|140px]][[File:SFULogo.jpg|150px]] [[File:UofAlogo.png|180px]][[File:LOGO_ulib_4cp_under75_png_4f05de2698.png|200px]] [[File:MoMA.png|180px]] [[File:FinalULBlues_copy.png|300px]] [[File:ZIBlogo-mediumlines.png|75px]] [[File:HarvardBaker30_image.png|250px]] [[File:Coppullogo.jpg]] [[File:UM-BHL-logo.png|120px]] [[File:DuraSpace_logo_horiz_300.png|260px]][[File:Mit_logo.png]] [[File:ocul_logo.png|200 px]] [[File:york_logo.png|240px]] [[File:hull_logo.png|220px]] [[File:Logo_arkivum_blk.png|200px]] [[File:NLW_logo1.jpg|330px]]<br />
<br />
<br />
<br />
<br />
<br />
__NOTOC__</div>Mcantelonhttps://wiki.archivematica.org/index.php?title=Main_Page&diff=11502Main Page2016-12-19T08:38:58Z<p>Mcantelon: /* Twitter */</p>
<hr />
<div><div style="background: #fff; float: right; padding: 1em; width: 30%"><br />
<div class="download"><br />
<br />
== Free Demo and Download ==<br />
* [http://sandbox.archivematica.org Demo] - see [[Sandbox|Sandbox info]] for login<br />
* [[Release Notes|Release notes]]<br />
* [https://ww.archivematica.org/en/docs/latest/admin-manual/installation/installation/#installation Installation]<br />
* [http://www.artefactual.com/services/ Installation services]<br />
<br />
<br />
</div><br />
<br />
<div class="documentation"><br />
<br />
== [https://www.archivematica.org/ How to use Archivematica] ==<br />
* User and administrative manuals at [http://www.archivematica.org archivematica.org]<br />
* [https://www.artefactual.com/services/training/ Training services]<br />
<br />
</div><br />
<br />
<div class="development"><br />
<br />
== [[Development|Developer resources]] ==<br />
*[[Development roadmap: Archivematica|Development roadmap]]<br />
* Development [[Documentation|documentation]]<br />
*[https://projects.artefactual.com/projects/archivematica Issues list]<br />
*[https://www.artefactual.com/partners/ Become an innovation partner]<br />
<br />
<br />
</div><br />
<br />
<div class="community"><br />
<br />
== [[Community|Community]] ==<br />
*[https://groups.google.com/group/archivematica Discussion list]<br />
*[[Community|Free community resources]]<br />
*[http://www.artefactual.com/services/archivematica/maintenance/ Get support]<br />
*[[Contributors|Contributors]]<br />
<br />
</div><br />
<br />
<div class="twitter"><br />
<br />
== Twitter ==<br />
<br />
{{#widget:Twitter}}<br />
<br />
</div><br />
<br />
<div class="news"><br />
<br />
<br />
<br />
</div><br />
<br />
</div><div style="overflow: hidden;"><br />
<br />
== ''This is the Archivematica development wiki. For user and administrative manuals, as well as installation information, please visit [http://www.archivematica.org archivematica.org].'' ==<br />
<br />
='''What is Archivematica?'''=<br />
<br />
Archivematica is a free and open-source [[wikipedia:Digital preservation|digital preservation]] system that is designed to maintain long-term access to digital memory. Archivematica is packaged with the web-based content management system [https://www.accesstomemory.org/ AtoM] for access to your digital objects.<br />
<br />
The [[overview]] section provides a detailed description of Archivematica's functionality and technical architecture. This screencast gives a demo of the core features in the most current release of the system. <br />
<br />
{| width="100%" border="0" style="margin: 20px 0;" class="youtube"<br />
| align="center" | <youtube>EjStNDXK48U</youtube><br />
|}<br />
<br />
==='''Standards-based'''===<br />
<br />
Archivematica uses a [http://en.wikipedia.org/wiki/Microservices micro-services] design pattern to provide an integrated suite of software tools that allows users to process digital objects from ingest to access in compliance with the ISO-OAIS functional model. Users monitor and control the micro-services via a web-based dashboard. Archivematica uses METS, PREMIS (events, agents, rights and restrictions), Dublin Core, the Library of Congress BagIt specification and other best practice standards and practices to provide trustworthy, authentic, reliable, and interoperable archival packages (AIPs) for storage in your preferred repository.<br />
<br />
==='''Open source'''===<br />
<br />
All Archivematica code is released under a GNU Affero General Public License ([http://www.gnu.org/licenses/agpl.html AGPL 3.0]) – giving you the freedom to study, modify, improve, and distribute it. We believe that an important part of preservation is transparency, and that memory institutions should be able to demonstrate at every stage what happens when they process cultural heritage materials for preservation. Archivematica [https://github.com/artefactual code] is always freely available, and our documentation is also released under a Creative Commons Share-alike license.<br />
<br />
==='''Flexible and customizable'''===<br />
<br />
Archivematica provides several decision points that give the user control over choices about format identification tools, printing the original order of the directories ingested, examining contents for private and personal information, extracting contents of packages and forensic images, transcribing content, and more. Users may also preconfigure most of these options for seamless ingest to archival storage and access. Archivematica offers many ingest workflows: metadata and submission documentation import, zipped and unzipped Bag ingest, digital forensic image processing, SIP arrangement, manual normalization, and dataset management.<br />
<br />
==='''Compatible with hundreds of formats'''===<br />
<br />
In the Format Policy Registry (FPR), Archivematica implements its default [[media type preservation plans|format policies]] based on an analysis of the [[significant characteristics]] of file formats. The FPR also offers an editable, flexible framework for format identification, package extraction, transcription and normalization for preservation and access. Your institution can update tools, rules and commands in your local FPR from the Artefactual-managed FPR server. You can also add your own, local policies to your internal FPR. The FPR is integrated with PRONOM.<br />
<br />
==='''Advanced search and storage management'''===<br />
<br />
You can easily search your backlog and your archival storage from within your Archivematica web-based dashboard. This means you can download stored AIPs as complete packages, individual objects, or every package in an AIC. You can also manage your storage and processing locations using the Archivematica Storage Service, including a two-step deletion process that requires justification and approval to eliminate a stored AIP.<br />
<br />
==='''Integration with third-parties'''===<br />
<br />
Memory institutions have dedicated voluminous resources over the past couple of decades to implement various software platforms and tools to manage digital objects. For this reason, we believe in leveraging the strength of other tools and integrating with them wherever possible. Highlights include: [https://www.accesstomemory.org/en/ AtoM], [http://www.dspace.org/ DSpace], [http://www.contentdm.org/ CONTENTdm], [http://islandora.ca/ Islandora], [http://www.lockss.org/ LOCKSS], [http://www.duracloud.org/ DuraCloud], [http://arkivum.com/ Arkivum], [http://www.openstack.org/ OpenStack] and [http://www.archiviststoolkit.org/ Archivists' Toolkit]<br />
<br />
The software applications integrated into Archivematica are each released under their own open source license. These are checked for license compatibility before they are integrated into the project. A full list of applications with their respective license is available on the [[External tools|external software tools]] page.<br />
<br />
==='''Lead developers and partners'''===<br />
This project is managed by [http://artefactual.com/archivematica.html Artefactual Systems] in collaboration with the UNESCO Memory of the World's [http://portal.unesco.org/ci/en/ev.php-URL_ID=1720&URL_DO=DO_TOPIC&URL_SECTION=201.html Subcommittee on Technology], the [http://vancouver.ca/ctyclerk/archives/ City of Vancouver Archives], [http://www.library.hbs.edu/ Harvard Business School Baker Library], the [http://www.moma.org/ Museum of Modern Art (MoMA)], the [http://www.library.ualberta.ca/ University of Alberta Libraries], the [http://diginit.library.ubc.ca/ University of British Columbia Library], the [http://rockarch.org/ Rockefeller Archive Center], [http://www.sfu.ca/archives/ Simon Fraser University Archives and Records Management], [http://www.library.yale.edu/ Yale University Library], [http://www.zib.de/en/home.html Zuse-Institute Berlin], [http://www.coppul.ca/ Council of Prairie and Pacific University Libraries (COPPUL)], [http://bentley.umich.edu/ Bentley Historical Library, University of Michigan], [http://duraspace.org Duraspace], [http://libraries.mit.edu/ MIT Libraries], [http://www.ocul.on.ca/ Ontario Council of University Libraries], [https://www.llgc.org.uk/ National Library of Wales] and a number of other collaborators.<br />
</div><br />
<br />
[[File:Artefactual_Logo.png|240px|center|link=http://www.artefactual.com/]]<br />
</div><br />
[[File:Cva.gif|160px]] [[File:Ubcblue_full.png|80px]] [[File:RAC-logo.png|80px]] [[File:Logo_en.gif|140px]][[File:SFULogo.jpg|150px]] [[File:UofAlogo.png|180px]][[File:LOGO_ulib_4cp_under75_png_4f05de2698.png|200px]] [[File:MoMA.png|180px]] [[File:FinalULBlues_copy.png|300px]] [[File:ZIBlogo-mediumlines.png|75px]] [[File:HarvardBaker30_image.png|250px]] [[File:Coppullogo.jpg]] [[File:UM-BHL-logo.png|120px]] [[File:DuraSpace_logo_horiz_300.png|260px]][[File:Mit_logo.png]] [[File:ocul_logo.png|200 px]] [[File:york_logo.png|240px]] [[File:hull_logo.png|220px]] [[File:Logo_arkivum_blk.png|200px]] [[File:NLW_logo1.jpg|330px]]<br />
<br />
<br />
<br />
<br />
<br />
__NOTOC__</div>Mcantelonhttps://wiki.archivematica.org/index.php?title=Internal_audit_tool&diff=11068Internal audit tool2016-04-26T23:35:41Z<p>Mcantelon: </p>
<hr />
<div>[[Documentation]] > Internal audit tool<br />
<br />
===Drupal TRAC review tool===<br />
<br />
Developed by MIT in a project led by Nancy McGovern, Head of [http://libraries.mit.edu/preservation/ Curation and Preservation Services] at MIT Libraries. Artefactual has permission to host this tool for community use. The copy provided here contains data about the TRAC requirements that Archivematica fulfills for the repository.<br />
<br />
==Installation==<br />
* Download link: [https://www.archivematica.org/download/trac.tar.gz https://www.archivematica.org/download/trac.tar.gz] (GitHub: https://github.com/artefactual-labs/trac)<br />
* Instructions for installation:<br />
**Be sure to consult the README.txt and README_TRAC.txt files in the tarball prior to installation.<br />
<br />
==Summary==<br />
The following text is slightly edited from the home page of the Drupal TRAC Review site.<br />
<br />
The home page of the site provides an overview of an organization's efforts to document its evidence for meeting the requirements of the CCSDS Audit and Certification of Trustworthy Digital Repositories [http://public.ccsds.org/publications/archive/652x0m1.pdf checklist] that was a pproved as ISO 16363 and is based on Trustworthy Repositories Audit and Certification (TRAC): Criteria and Checklist that was released in January 2007. A TRAC review is a self-assessment method for an organization to demonstrate good practice and conformance as a trusted digital repository to its designated communities and prepare for a peer review or other external audit. In many organizations, responsibilities for TRAC compliance are distributed throughout the organization, with specific units and committees having certain responsibilities for each requirement.<br />
<br />
===Responsibilities===<br />
<br />
* Each entity is assigned a role for each requirement using the RACI responsibility assignment [http://en.wikipedia.org/wiki/Responsibility_assignment_matrix matrix]. The RACI Matrix describes participation by various organizational roles in completing tasks for a project. RACI is especially useful in clarifying roles in projects and processes requiring distributed responsibilities. See the Responsibilities for TRAC page of the Drupal site for more information on RACI responsibilities, and a listing of units and committees that have roles in TRAC conformance.<br />
* In each requirement where Archivematica provides all or part of the evidence, the Operations Group is identified as one of the Responsible parties. Other organizational roles indicated are simply suggestions.<br />
<br />
===Requirements===<br />
* In the site, each TRAC requirement has its own page. Sub- and Sub-sub requirements are referred to on the relevant high-level requirement page. Current compliance with TRAC requirements is assessed on a rating system from 0 to 4 (see example: [http://206.191.128.204/trac/sites/default/files/SGDS%202009-9421%20%28D.%20BOUCON%29.pdf SGDS report], page 14):<br />
4 = fully compliant - the repository can demonstrate that has comprehensively addressed the requirement<br />
3 = mostly compliant - the repository can demonstrate that it has mostly addressed the requirement and is on working on full compliance<br />
2 = half compliant - the repository has partially addressed the requirement and has significant work remaining to fully address the requirement<br />
1 = slightly compliant - the repository has something in place, but has a lot of work to do in addressing the requirement <br />
0 = non-compliant or not started - the repository has not yet addressed the requirement or has not started the review of the requirement<br />
* Any group in the organization that is involved in defining policy and practice should update the status of relevant requirements. When listing evidence, please include sufficient information for reviewers to get to the cited evidence (e.g., a document title, date, a link) and note the name of the group or department that is adding an entry to the evidence addressing the requirement along with the date of the annotations (e.g., [Right Management group, 2/13/2013]). (Note that for requirements where Archivematica provides all or part of the evidence, no date or group is specified as this evidence must be reviewed and assigned a responsible group per repository) For additional guidance, please see the Responsibilities for TRAC page of the site.<br />
<br />
===Status===<br />
*The site provides a sequence of status levels for each requirement:<br />
**Accepted – the evidence provided has been accepted as sufficient for this review round<br />
**Ready for review – the Responsible group has completed its work and the evidence is ready for review<br />
**In progress – the Responsible group is in the process of compiling or generating relevant evidence<br />
**Not started – no evidence or information has been provided yet<br />
*For requirements where Archivematica provides all or part of the evidence, the status is indicated as In Progress as it should still be reviewed, edited, and/or completed by the repository.<br />
<br />
==Support==<br />
*Artefactual will not be providing free support for this tool. However, we encourage users to discuss it using our public [https://groups.google.com/group/archivematica discussion list].<br />
*If you have questions about an internal review that are unrelated to this tool, contact the [http://www.digitalpreservation.gov/ndsa/working_groups/standards.html NDSA Standards and Practices Working Group]<br />
<br />
==Thanks==<br />
*Artefactual is grateful to Nancy McGovern and Matt Bernhardt of MIT for their work towards the development of this tool and for allowing us to host it for community consumption here on the Archivematica wiki.</div>Mcantelonhttps://wiki.archivematica.org/index.php?title=Sword_API&diff=9625Sword API2014-03-20T22:34:30Z<p>Mcantelon: /* Create a new transfer */</p>
<hr />
<div>[[Main Page]] > [[Documentation]] > [[Requirements]] > Sword API<br />
<br />
== Overview ==<br />
<br />
One of the 1.1 release features is a sponsored project to integrate Archivematica with Islandora. This integration will be accomplished by creating a [http://swordapp.org Sword] 2.0 API for the Archivematica [https://www.archivematica.org/wiki/Administrator_manual_1.0#Storage_service storage service]. Islandora development work will add functionality to Islandora to use this API to deposit digital objects into Archviematica.<br />
<br />
As described [[Overview|elsewhere]] on this wiki, ''"the primary function of Archivematica is to process digital transfers (accessioned digital objects), turn them into SIPs, apply format policies and create high-quality, repository-independent Archival Information Packages (AIP)"''.<br />
<br />
The Archivematica Sword API allows 3rd party applications to automate the process of creating Transfers. <br />
#Create Transfer - set the name and other metadata about a Transfer<br />
#Populate Transfer - add/edit/update digital objects in a Transfer, and associated metadata<br />
#Finalize Transfer - indicates that the Transfer is ready to start processing.<br />
<br />
After content has been deposited, if users have access to the deposit directory they can also manually manipulate the deposit directory aside from any manipulation using the API.<br />
<br />
Once a Transfer has been created, populated and finalized, Archivematica will begin processing that Transfer.<br />
<br />
== Configuration ==<br />
<br />
The SWORD API is part of the Archivematica storage service REST API. The storage service also talks to the Archivematica dashboard, however, to notify it that a, transfer created from a SWORD deposit, has been approved for processing.<br />
<br />
To use the SWORD API you must install the Archivematica dashboard 1.0 branch and the Archivematica storage service dev/issue-5980-islandora branch.<br />
<br />
Dashboard configuration:<br />
<br />
# In dashboard REST API administration, add the IP of the storage service server to IP whitelist<br />
# In dashboard user administration, take note of username and API key for a dashboard user (example: user "demo" and API key "4e5f32ab2aefd3543e1b19a2de554dd65f90108a")<br />
# In dashboard general admininstration, take note of the dashboard's UUID<br />
<br />
Storage service configuration:<br />
<br />
# In the storage service web interface's Pipelines tab, find the dashboard pipeline (using dashboard's UUID noted during dashboard configuration)<br />
# Enter the dashboard's IP address into the "Remote name" field and the user and API key noted earlier into the "Api username" and "Api key" fields. Click the button to submit these changes.<br />
<br />
After configuration you'll need to find the space UUID of the SWORD server. To do so, in the web interface's Spaces tab, click "View Details and Locations" for the SWORD server. The UUID will be shown at the top of the screen. The UUID is used to figure out the initial API URL to access (for example: "http://localhost:8000/api/v1/space/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/").<br />
<br />
== Example session ==<br />
<br />
Below is an example session using curl to manipulate the API. In the example a deposit is created, a file is added to it, and it is finalized.<br />
<br />
NOTE: The SWORD API is in the process of being moved to the storage service. These URLs may not work.<br />
<br />
<pre># create new deposit, providing a METS file specifying digital object URLs to download in the background<br />
curl -v -H "In-Progress: true" --data-binary @mets.xml --request POST http://localhost:8000/api/v1/space/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/<br />
# response XML includes endpoints for adding additional files, etc.<br />
<br />
# add a single file to the deposit<br />
curl -v -H "Content-Disposition: attachment; filename=cat.jpg" --request POST \<br />
--data-binary "@cat.jpg" \<br />
http://127.0.0.1:8000/api/v1/location/9c8b4ac0-0407-4360-a10d-af6c62a48b69/sword/media/<br />
<br />
# start another background download of resources specified in a METS<br />
curl -v -H "In-Progress: true" -H "Packaging: METS" --data-binary @mets.xml --request POST http://127.0.0.1:8000/api/v1/location/9c8b4ac0-0407-4360-a10d-af6c62a48b69/sword/media/<br />
<br />
# finalize transfer and approve processing<br />
curl -v -H "In-Progress: false" --request POST http://127.0.0.1:8000/api/v1/location/149cc29d-6472-4bcf-bee8-f8223bf60580/sword/<br />
</pre><br />
<br />
You might, at some point, want to list the transfers that have been started. The following curl command will do so.<br />
<br />
<pre>curl -v http://localhost:8000/api/v1/space/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/</pre><br />
<br />
If you're working on a transfer and want to list what files are included in it, the following curl command will list them.<br />
<br />
<pre># list files in transfer<br />
curl -v http://127.0.0.1:8000/api/v1/location/9c8b4ac0-0407-4360-a10d-af6c62a48b69/sword/media/</pre><br />
<br />
If you've started a deposit, but want to discard it, you can delete the deposit. The following curl command shows an example.<br />
<br />
<pre>curl -v -XDELETE http://127.0.0.1:8000/api/v1/location/149cc29d-6472-4bcf-bee8-f8223bf60580/sword/</pre><br />
<br />
== Single step deposit ==<br />
<br />
If you wanted to deposit a transfer then immediately finalize it, after background downloading is complete, you could use something like the following curl command.<br />
<br />
<pre>curl -v -H "In-Progress: false" --data-binary @mets.xml --request POST http://localhost:8000/api/v1/space/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/</pre><br />
<br />
== Endpoints ==<br />
<br />
=== Service document ===<br />
<br />
The SWORD service document provides information about the SWORD provider's capacities and lists SWORD collections. Archivematica currently includes one SWORD collection to which SWORD deposits can be made: transfers.<br />
<br />
The SWORD service document endpoint is located at /api/v1/sword/.<br />
<br />
Service document example:<br />
<pre><br />
<service xmlns:dcterms="http://purl.org/dc/terms/"<br />
xmlns:sword="http://purl.org/net/sword/terms/"<br />
xmlns:atom="http://www.w3.org/2005/Atom"<br />
xmlns="http://www.w3.org/2007/app"><br />
<br />
<sword:version>2.0</sword:version><br />
<br />
<workspace><br />
<atom:title>Archivematica storage service</atom:title><br />
<br />
<br />
<collection href="http://192.168.1.231:8000/api/v1/space/8f24ef5f-19d5-4b77-8a38-b30d034b11e7/sword/collection/"><br />
<atom:title>Collection</atom:title><br />
<accept>*/*</accept><br />
<accept alternate="multipart-related">*/*</accept><br />
<sword:mediation>false</sword:mediation><br />
</collection><br />
<br />
</workspace><br />
</service><br />
</pre><br />
<br />
=== List existing transfers ===<br />
* HTTP Get to the Collection IRI (defined by default as: /api/v1/space/[space UUID]/sword/collection/)<br />
* Transfers are listed as an Atom feed<br />
* Each Atom feed entry contains an "atom:link" element whose href attribute contains the URL needed to get details about the transfer<br />
* optional filters via get parameters (not yet implemented)<br />
<br />
Example response:<br />
<pre><br />
<atom:feed xmlns="http://www.w3.org/2005/Atom"><br />
<atom:id>http://192.168.1.231:8000/api/v1/space/8f24ef5f-19d5-4b77-8a38-b30d034b11e7/sword/collection/</atom:id><br />
<atom:title type="text">Deposits</atom:title><br />
<atom:link href="http://192.168.1.231:8000/api/v1/space/8f24ef5f-19d5-4b77-8a38-b30d034b11e7/sword/collection/" rel="self"><br />
</atom:link><br />
<atom:entry><br />
<atom:id>http://192.168.1.231:8000/api/v1/location/88e70cd2-9258-4a84-8938-16e74be032e6/sword/</atom:id><br />
<atom:title type="text">Cinderella</atom:title><br />
<atom:link href="http://192.168.1.231:8000/api/v1/location/88e70cd2-9258-4a84-8938-16e74be032e6/sword/" rel="self"><br />
</atom:link><br />
</atom:entry><br />
</atom:feed><br />
</pre><br />
<br />
=== Create a new transfer ===<br />
* used to start a new transfer in Archivematica<br />
* HTTP POST of an Atom Entry Document to the Collection IRI (defined by default as: /api/v1/space/[space UUID]/sword/collection/)<br />
<br />
'''Possible HTTP Response Codes'''<br />
* HTTP 200 OK - transfer already exists (not yet implemented)<br />
* HTTP 201 Created - transfer has been accepted<br />
* HTTP 412 Precondition Failed - required metadata missing or invalid<br />
<br />
Valid requests will receive a Sword Deposit Receipt in the body of the response.<br />
<br />
'''Required HTTP Headers'''<br />
The HTTP POST must include certain specific http headers. <br />
<br />
Required by http 1.1 specification:<br />
* Host: Must be set to archivematica host name.<br />
* Content-Length: Must be set to the length of the atom entry document.<br />
* Content-Type: Must be set to "application/atom+xml;type=entry".<br />
<br />
Required by Archivematica. <br />
* Authorization: Must include the api key and username assigned by Archivematica.<br />
<br />
Required by SWORD 2.0 protocol:<br />
* In-Progress: Must be set to "true"<br />
<br />
Optional in SWORD 2.0 protocol:<br />
* On-Behalf-Of: not implemented by Archivematica<br />
* Slug: not implemented by Archivematica<br />
<br />
'''Required in Body'''<br />
The Body of the request must be a valid METS Document. The required fields in an Atom Entry Document are:<br />
* LABEL: used as the transfer name<br />
* id: used as an accession id (not yet implemented)<br />
* author: used as the source of acquisition (not yet implemented)<br />
* summary: not implemented yet. Could be used in the future as a description for the Transfer<br />
* updated: should be set to the current timestamp. <br />
<br />
'''Example'''<br />
Example HTTP POST request:<br />
<pre><br />
POST /api/v1/space/96606387-cc70-4b09-b422-a7220606488d/sword/collection/ HTTP/1.1<br />
Host: localhost<br />
Authorization: Archivematica-API api_key="XXXXXXXXXXXXXXXXXXXX", username="timh"<br />
Content-Length: 213<br />
Content-Type: application/atom+xml;type=entry<br />
In-Progress: true<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<METS:mets EXT_VERSION="1.1" OBJID="islandora:72" LABEL="Cinderella"<br />
xmlns:METS="http://www.loc.gov/METS/"<br />
xmlns:xlink="http://www.w3.org/1999/xlink"<br />
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"<br />
xsi:schemaLocation="http://www.loc.gov/METS/ http://www.fedora.info/definitions/1/0/mets-fedora-ext1-1.xsd"><br />
<METS:fileSec><br />
<METS:fileGrp ID="DATASTREAMS"><br />
<METS:fileGrp ID="OBJ"><br />
<METS:file ID="OBJ.0"><br />
<METS:FLocat xlink:title="Cinderella_(1865).pdf" LOCTYPE="URL"<br />
CHECKSUM="fad0d2f982f317a15804d2e5c4b9efcc" CHECKSUMTYPE="MD5" <br />
xlink:href="http://localhost:8080/fedora/get/islandora:72/OBJ/2013-08-12T14:46:43.454Z" /><br />
</METS:file><br />
</METS:fileGrp><br />
</METS:fileGrp><br />
</METS:fileSec><br />
</METS:mets><br />
</pre><br />
<br />
Example Response:<br />
<pre><br />
201 Created<br />
Location: http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/<br />
<br />
<entry xmlns="http://www.w3.org/2005/Atom"<br />
xmlns:sword="http://purl.org/net/sword/"<br />
xmlns:dcterms="http://purl.org/dc/terms/"><br />
<br />
<title>Cinderella</title><br />
<id>91d4f258-0050-4914-9d0c-6a74815358d2</id><br />
<updated></updated><br />
<generator uri="https://www.archivematica.org" version="1.0"/><br />
<br />
<summary>A deposit was started.</summary><br />
<sword:treatment>A deposit directory was created and, optionally, asynchronous download of digital objects.</sword:treatment><br />
<br />
<link rel="alternate" href="http://www.swordserver.ac.uk/col1/mydeposit.html"/><br />
<link rel="edit-media" href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/media/"/><br />
<link rel="edit" href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/" /><br />
<link rel="http://purl.org/net/sword/terms/add" href="http://192.168.1.76:8000/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/" /><br />
<link rel="http://purl.org/net/sword/terms/statement" type="application/atom+xml;type=feed"<br />
href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/state/" /><br />
</entry><br />
</pre><br />
<br />
=== Add Files to a Transfer ===<br />
<br />
Post file data:<br />
* It is possible to also POST the actual file to a deposit location's EM-IRI (/api/v1/location/[location UUID]/sword/media/)<br />
* The file should be posted as the request body and the filename specified using the Content-Disposition header (as per RFC 6266): for example "Content-Disposition: Attachment; filename=dog.jpg"<br />
* An MD5 checksum for an uploaded file can be provided via the Content-MD5 header (as per RFC 1544): for example "Content-MD5: Q2hlY2sgSW50ZWdyaXR5IQ=="<br />
* If only an Atom Entry Document is POST'ed, Archivematica will look for uri's in the file StructMap section of the METS file, and attempt to GET each file listed, to include in the Transfer. (not yet implemented)<br />
<br />
=== Finalize a Transfer ===<br />
* POST with no body to the SE-IRI<br />
* set In-Progress HTTP header to : false<br />
* This will tell Archivematica that no further content will be added or removed from the Transfer. <br />
* Archivematica will finish fetching any files that were added previously, and once they have all been downloaded, the Transfer will start through the Archivematica pipeline.<br />
<br />
'''Example'''<br />
<pre><br />
POST http://localhost/api/v1/location/55ce8053-113a-4954-8aa3-fc9771da0bda/sword/ HTTP/1.1<br />
Host: localhost<br />
Authorization: Archivematica-API api_key="XXXXXXXXXXXXXXXXXXXX", username="timh"<br />
Content-Length: 0<br />
Content-Type: application/atom+xml;type=entry<br />
In-Progress: false<br />
</pre><br />
<br />
The response will be HTTP 200/OK or 400/Error (400 if the Transfer was already finalized). If the transfer doesn't exist the response will be HTTP 404.<br />
<br />
=== Get Status of Transfer ===<br />
To check Status:<br />
<br />
GET the State-IRI<br />
in this example:<br />
<br />
GET http://localhost/api/v1/location/09224ddb-4c7d-404c-9218-2f2e1b5a599e/sword/state/ HTTP/1.1<br />
<br />
response will include:<br />
<pre><atom:feed xmlns:sword="http://purl.org/net/sword/terms/" <br />
xmlns:atom="http://www.w3.org/2005/Atom"><br />
<br />
<atom:category scheme="http://purl.org/net/sword/terms/state"<br />
term="failed"<br />
label="State"><br />
Deposit initiation: Failed<br />
</atom:category><br />
<br />
</atom:feed></pre><br />
the list of possible descriptions is not finalized.<br />
<br />
The state term value will either be "processing" (asynchronous deposit still working), "complete" (ready to be finalized), or "failed" (asynchronous deposit encountered an error).<br />
<br />
== Additional Details == <br />
<br />
=== Transfer Details ===<br />
* redirect to Edit-IRI<br />
* used to get basic info about a Transfer with HTTP GET<br />
* can update basic info using HTTP PUT (not yet implemented)<br />
* can allow deletion with HTTP DELETE<br />
* follows the form: /api/v1/location/[deposit location UUID]/sword/<br />
* example: http://192.168.1.231:8000/api/v1/location/09224ddb-4c7d-404c-9218-2f2e1b5a599e/sword/<br />
<br />
=== EM-IRI ===<br />
* Edit-Media IRI <br />
* used to add new objects to an existing transfer<br />
* follows the form: [archivematica hostname]/api/v2/transfer/[uuid of transfer]/media<br />
* example: /api/v1/location/[deposit location UUID]/sword/media/<br />
<br />
An HTTP POST to the em-iri for a transfer should include a single file as the body. If the HTTP "Packaging" header is set to "METS" then METS XML can be sent as the body, specifying a list of digital object URLs to download in the background.<br />
<br />
An HTTP GET should return a list of files in the transfer<br />
<br />
An HTTP DELETE to the em-iri will remove all digital objects from the Transfer. This is a valid operation only while the Transfer is being assembled. Once the Transfer has been finalized, attempting to DELETE will return an error.<br />
<br />
=== Edit-IRI ===<br />
The client can replace the metadata of a resource by performing an HTTP PUT of a new Atom Entry on the Edit-IRI. (not yet implemented)<br />
<br />
This would be used to update metadata about a transfer, such as the transfer name.<br />
<br />
* example: http://localhost/api/v2/transfer/1225c695-cfb8-4ebb-aaaa-80da344efa6a/edit<br />
<br />
=== SE-IRI ===<br />
* example: http://localhost/api/v2/transfer/add/1225c695-cfb8-4ebb-aaaa-80da344efa6a (not yet implemented)<br />
<br />
=== State-IRI ===<br />
* used to retrieve status of transfer<br />
* implemented as Atom document<br />
* example: /api/v1/location/[deposit location UUID]/sword/state/<br />
* should be able to subscribe like RSS feed<br />
<br />
=== Service document ===</div>Mcantelonhttps://wiki.archivematica.org/index.php?title=Sword_API&diff=9419Sword API2014-01-27T23:04:06Z<p>Mcantelon: /* Synchronous Deposit Examples */</p>
<hr />
<div>[[Main Page]] > [[Documentation]] > [[Requirements]] > Sword API<br />
<br />
== Overview ==<br />
<br />
One of the 1.1 release features is a sponsored project to integrate Archivematica with Islandora. This integration will be accomplished by creating a [http://swordapp.org Sword] 2.0 API for the Archivematica [https://www.archivematica.org/wiki/Administrator_manual_1.0#Storage_service storage service]. Islandora development work will add functionality to Islandora to use this API to deposit digital objects into Archviematica.<br />
<br />
As described [[Overview|elsewhere]] on this wiki, ''"the primary function of Archivematica is to process digital transfers (accessioned digital objects), turn them into SIPs, apply format policies and create high-quality, repository-independent Archival Information Packages (AIP)"''.<br />
<br />
The Archivematica Sword API allows 3rd party applications to automate the process of creating Transfers. <br />
#Create Transfer - set the name and other metadata about a Transfer<br />
#Populate Transfer - add/edit/update digital objects in a Transfer, and associated metadata<br />
#Finalize Transfer - indicates that the Transfer is ready to start processing.<br />
<br />
After content has been deposited, if users have access to the deposit directory they can also manually manipulate the deposit directory aside from any manipulation using the API.<br />
<br />
Once a Transfer has been created, populated and finalized, Archivematica will begin processing that Transfer.<br />
<br />
== Configuration ==<br />
<br />
The SWORD API is part of the Archivematica storage service REST API. The storage service also talks to the Archivematica dashboard, however, to notify it that a, transfer created from a SWORD deposit, has been approved for processing.<br />
<br />
To use the SWORD API you must install the Archivematica dashboard 1.0 branch and the Archivematica storage service dev/issue-5980-islandora branch.<br />
<br />
Dashboard configuration:<br />
<br />
# In dashboard REST API administration, add the IP of the storage service server to IP whitelist<br />
# In dashboard user administration, take note of username and API key for a dashboard user (example: user "demo" and API key "4e5f32ab2aefd3543e1b19a2de554dd65f90108a")<br />
# In dashboard general admininstration, take note of the dashboard's UUID<br />
<br />
Storage service configuration:<br />
<br />
# In the storage service web interface's Pipelines tab, find the dashboard pipeline (using dashboard's UUID noted during dashboard configuration)<br />
# Enter the dashboard's IP address into the "Remote name" field and the user and API key noted earlier into the "Api username" and "Api key" fields. Click the button to submit these changes.<br />
<br />
After configuration you'll need to find the space UUID of the SWORD server. To do so, in the web interface's Spaces tab, click "View Details and Locations" for the SWORD server. The UUID will be shown at the top of the screen. The UUID is used to figure out the initial API URL to access (for example: "http://localhost:8000/api/v1/space/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/").<br />
<br />
== Example session ==<br />
<br />
Below is an example session using curl to manipulate the API. In the example a deposit is created, a file is added to it, and it is finalized.<br />
<br />
NOTE: The SWORD API is in the process of being moved to the storage service. These URLs may not work.<br />
<br />
<pre># create new deposit, providing a METS file specifying digital object URLs to download in the background<br />
curl -v -H "In-Progress: true" --data-binary @mets.xml --request POST http://localhost:8000/api/v1/space/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/<br />
# response XML includes endpoints for adding additional files, etc.<br />
<br />
# add a single file to the deposit<br />
curl -v -H "Content-Disposition: attachment; filename=cat.jpg" --request POST \<br />
--data-binary "@cat.jpg" \<br />
http://127.0.0.1:8000/api/v1/location/9c8b4ac0-0407-4360-a10d-af6c62a48b69/sword/media/<br />
<br />
# start another background download of resources specified in a METS<br />
curl -v -H "In-Progress: true" -H "Packaging: METS" --data-binary @mets.xml --request POST http://127.0.0.1:8000/api/v1/location/9c8b4ac0-0407-4360-a10d-af6c62a48b69/sword/media/<br />
<br />
# finalize transfer and approve processing<br />
curl -v -H "In-Progress: false" --request POST http://127.0.0.1:8000/api/v1/location/149cc29d-6472-4bcf-bee8-f8223bf60580/sword/<br />
</pre><br />
<br />
You might, at some point, want to list the transfers that have been started. The following curl command will do so.<br />
<br />
<pre>curl -v http://localhost:8000/api/v1/space/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/</pre><br />
<br />
If you're working on a transfer and want to list what files are included in it, the following curl command will list them.<br />
<br />
<pre># list files in transfer<br />
curl -v http://127.0.0.1:8000/api/v1/location/9c8b4ac0-0407-4360-a10d-af6c62a48b69/sword/media/</pre><br />
<br />
If you've started a deposit, but want to discard it, you can delete the deposit. The following curl command shows an example.<br />
<br />
<pre>curl -v -XDELETE http://127.0.0.1:8000/api/v1/location/149cc29d-6472-4bcf-bee8-f8223bf60580/sword/</pre><br />
<br />
== Single step deposit ==<br />
<br />
If you wanted to deposit a transfer then immediately finalize it, after background downloading is complete, you could use something like the following curl command.<br />
<br />
<pre>curl -v -H "In-Progress: false" --data-binary @mets.xml --request POST http://localhost:8000/api/v1/space/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/</pre><br />
<br />
== Endpoints ==<br />
<br />
=== Service document ===<br />
<br />
The SWORD service document provides information about the SWORD provider's capacities and lists SWORD collections. Archivematica currently includes one SWORD collection to which SWORD deposits can be made: transfers.<br />
<br />
The SWORD service document endpoint is located at /api/v1/sword/.<br />
<br />
Service document example:<br />
<pre><br />
<service xmlns:dcterms="http://purl.org/dc/terms/"<br />
xmlns:sword="http://purl.org/net/sword/terms/"<br />
xmlns:atom="http://www.w3.org/2005/Atom"<br />
xmlns="http://www.w3.org/2007/app"><br />
<br />
<sword:version>2.0</sword:version><br />
<br />
<workspace><br />
<atom:title>Archivematica storage service</atom:title><br />
<br />
<br />
<collection href="http://192.168.1.231:8000/api/v1/space/8f24ef5f-19d5-4b77-8a38-b30d034b11e7/sword/collection/"><br />
<atom:title>Collection</atom:title><br />
<accept>*/*</accept><br />
<accept alternate="multipart-related">*/*</accept><br />
<sword:mediation>false</sword:mediation><br />
</collection><br />
<br />
</workspace><br />
</service><br />
</pre><br />
<br />
=== List existing transfers ===<br />
* HTTP Get to the Collection IRI (defined by default as: /api/v1/space/[space UUID]/sword/collection/)<br />
* Transfers are listed as an Atom feed<br />
* Each Atom feed entry contains an "atom:link" element whose href attribute contains the URL needed to get details about the transfer<br />
* optional filters via get parameters (not yet implemented)<br />
<br />
Example response:<br />
<pre><br />
<atom:feed xmlns="http://www.w3.org/2005/Atom"><br />
<atom:id>http://192.168.1.231:8000/api/v1/space/8f24ef5f-19d5-4b77-8a38-b30d034b11e7/sword/collection/</atom:id><br />
<atom:title type="text">Deposits</atom:title><br />
<atom:link href="http://192.168.1.231:8000/api/v1/space/8f24ef5f-19d5-4b77-8a38-b30d034b11e7/sword/collection/" rel="self"><br />
</atom:link><br />
<atom:entry><br />
<atom:id>http://192.168.1.231:8000/api/v1/location/88e70cd2-9258-4a84-8938-16e74be032e6/sword/</atom:id><br />
<atom:title type="text">Cinderella</atom:title><br />
<atom:link href="http://192.168.1.231:8000/api/v1/location/88e70cd2-9258-4a84-8938-16e74be032e6/sword/" rel="self"><br />
</atom:link><br />
</atom:entry><br />
</atom:feed><br />
</pre><br />
<br />
=== Create a new transfer ===<br />
* used to start a new transfer in Archivematica<br />
* HTTP POST of an Atom Entry Document to the Collection IRI (defined by default as: /api/v1/space/[space UUID]/sword/collection/)<br />
<br />
'''Possible HTTP Response Codes'''<br />
* HTTP 200 OK - transfer already exists (not yet implemented)<br />
* HTTP 201 Created - transfer has been accepted<br />
* HTTP 412 Precondition Failed - required metadata missing or invalid<br />
<br />
Valid requests will receive a Sword Deposit Receipt in the body of the response.<br />
<br />
'''Required HTTP Headers'''<br />
The HTTP POST must include certain specific http headers. <br />
<br />
Required by http 1.1 specification:<br />
* Host: Must be set to archivematica host name.<br />
* Content-Length: Must be set to the length of the atom entry document.<br />
* Content-Type: Must be set to "application/atom+xml;type=entry".<br />
<br />
Required by Archivematica. <br />
* Authorization: Must include the api key and username assigned by Archivematica.<br />
<br />
Required by SWORD 2.0 protocol:<br />
* In-Progress: Must be set to "true"<br />
<br />
Optional in SWORD 2.0 protocol:<br />
* On-Behalf-Of: not implemented by Archivematica<br />
* Slug: not implemented by Archivematica<br />
<br />
'''Required in Body'''<br />
The Body of the request must be a valid METS Document. The required fields in an Atom Entry Document are:<br />
* LABEL: used as the transfer name<br />
* id: used as an accession id (not yet implemented)<br />
* author: used as the source of acquisition (not yet implemented)<br />
* summary: not implemented yet. Could be used in the future as a description for the Transfer<br />
* updated: should be set to the current timestamp. <br />
<br />
'''Example'''<br />
Example HTTP POST request:<br />
<pre><br />
POST /api/v1/space/96606387-cc70-4b09-b422-a7220606488d/sword/collection/ HTTP/1.1<br />
Host: localhost<br />
Authorization: Archivematica-API api_key="XXXXXXXXXXXXXXXXXXXX", username="timh"<br />
Content-Length: 213<br />
Content-Type: application/atom+xml;type=entry<br />
In-Progress: true<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<METS:mets EXT_VERSION="1.1" OBJID="islandora:72" LABEL="Cinderella"<br />
xmlns:METS="http://www.loc.gov/METS/"<br />
xmlns:xlink="http://www.w3.org/1999/xlink"<br />
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"<br />
xsi:schemaLocation="http://www.loc.gov/METS/ http://www.fedora.info/definitions/1/0/mets-fedora-ext1-1.xsd"><br />
<METS:fileSec><br />
<METS:fileGrp ID="DATASTREAMS"><br />
<METS:fileGrp ID="OBJ"><br />
<METS:file ID="OBJ.0"><br />
<METS:FLocat xlink:title="Cinderella_(1865).pdf" LOCTYPE="URL"<br />
xlink:href="http://localhost:8080/fedora/get/islandora:72/OBJ/2013-08-12T14:46:43.454Z" /><br />
</METS:file><br />
</METS:fileGrp><br />
</METS:fileGrp><br />
</METS:fileSec><br />
</METS:mets><br />
</pre><br />
<br />
Example Response:<br />
<pre><br />
201 Created<br />
Location: http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/<br />
<br />
<entry xmlns="http://www.w3.org/2005/Atom"<br />
xmlns:sword="http://purl.org/net/sword/"<br />
xmlns:dcterms="http://purl.org/dc/terms/"><br />
<br />
<title>Cinderella</title><br />
<id>91d4f258-0050-4914-9d0c-6a74815358d2</id><br />
<updated></updated><br />
<generator uri="https://www.archivematica.org" version="1.0"/><br />
<br />
<summary>A deposit was started.</summary><br />
<sword:treatment>A deposit directory was created and, optionally, asynchronous download of digital objects.</sword:treatment><br />
<br />
<link rel="alternate" href="http://www.swordserver.ac.uk/col1/mydeposit.html"/><br />
<link rel="edit-media" href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/media/"/><br />
<link rel="edit" href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/" /><br />
<link rel="http://purl.org/net/sword/terms/add" href="http://192.168.1.76:8000/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/" /><br />
<link rel="http://purl.org/net/sword/terms/statement" type="application/atom+xml;type=feed"<br />
href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/state/" /><br />
</entry><br />
</pre><br />
<br />
=== Add Files to a Transfer ===<br />
<br />
Post file data:<br />
* It is possible to also POST the actual file to a deposit location's EM-IRI (/api/v1/location/[location UUID]/sword/media/)<br />
* The file should be posted as the request body and the filename specified using the Content-Disposition header (as per RFC 6266): for example "Content-Disposition: Attachment; filename=dog.jpg"<br />
* An MD5 checksum for an uploaded file can be provided via the Content-MD5 header (as per RFC 1544): for example "Content-MD5: Q2hlY2sgSW50ZWdyaXR5IQ=="<br />
* If only an Atom Entry Document is POST'ed, Archivematica will look for uri's in the file StructMap section of the METS file, and attempt to GET each file listed, to include in the Transfer. (not yet implemented)<br />
<br />
=== Finalize a Transfer ===<br />
* POST with no body to the SE-IRI<br />
* set In-Progress HTTP header to : false<br />
* This will tell Archivematica that no further content will be added or removed from the Transfer. <br />
* Archivematica will finish fetching any files that were added previously, and once they have all been downloaded, the Transfer will start through the Archivematica pipeline.<br />
<br />
'''Example'''<br />
<pre><br />
POST http://localhost/api/v1/location/55ce8053-113a-4954-8aa3-fc9771da0bda/sword/ HTTP/1.1<br />
Host: localhost<br />
Authorization: Archivematica-API api_key="XXXXXXXXXXXXXXXXXXXX", username="timh"<br />
Content-Length: 0<br />
Content-Type: application/atom+xml;type=entry<br />
In-Progress: false<br />
</pre><br />
<br />
The response will be HTTP 200/OK or 400/Error (400 if the Transfer was already finalized). If the transfer doesn't exist the response will be HTTP 404.<br />
<br />
=== Get Status of Transfer ===<br />
To check Status:<br />
<br />
GET the State-IRI<br />
in this example:<br />
<br />
GET http://localhost/api/v1/location/09224ddb-4c7d-404c-9218-2f2e1b5a599e/sword/state/ HTTP/1.1<br />
<br />
response will include:<br />
<pre><atom:feed xmlns:sword="http://purl.org/net/sword/terms/" <br />
xmlns:atom="http://www.w3.org/2005/Atom"><br />
<br />
<atom:category scheme="http://purl.org/net/sword/terms/state"<br />
term="failed"<br />
label="State"><br />
Deposit initiation: Failed<br />
</atom:category><br />
<br />
</atom:feed></pre><br />
the list of possible descriptions is not finalized.<br />
<br />
The state term value will either be "processing" (asynchronous deposit still working), "complete" (ready to be finalized), or "failed" (asynchronous deposit encountered an error).<br />
<br />
== Additional Details == <br />
<br />
=== Transfer Details ===<br />
* redirect to Edit-IRI<br />
* used to get basic info about a Transfer with HTTP GET<br />
* can update basic info using HTTP PUT (not yet implemented)<br />
* can allow deletion with HTTP DELETE<br />
* follows the form: /api/v1/location/[deposit location UUID]/sword/<br />
* example: http://192.168.1.231:8000/api/v1/location/09224ddb-4c7d-404c-9218-2f2e1b5a599e/sword/<br />
<br />
=== EM-IRI ===<br />
* Edit-Media IRI <br />
* used to add new objects to an existing transfer<br />
* follows the form: [archivematica hostname]/api/v2/transfer/[uuid of transfer]/media<br />
* example: /api/v1/location/[deposit location UUID]/sword/media/<br />
<br />
An HTTP POST to the em-iri for a transfer should include a single file as the body. If the HTTP "Packaging" header is set to "METS" then METS XML can be sent as the body, specifying a list of digital object URLs to download in the background.<br />
<br />
An HTTP GET should return a list of files in the transfer<br />
<br />
An HTTP DELETE to the em-iri will remove all digital objects from the Transfer. This is a valid operation only while the Transfer is being assembled. Once the Transfer has been finalized, attempting to DELETE will return an error.<br />
<br />
=== Edit-IRI ===<br />
The client can replace the metadata of a resource by performing an HTTP PUT of a new Atom Entry on the Edit-IRI. (not yet implemented)<br />
<br />
This would be used to update metadata about a transfer, such as the transfer name.<br />
<br />
* example: http://localhost/api/v2/transfer/1225c695-cfb8-4ebb-aaaa-80da344efa6a/edit<br />
<br />
=== SE-IRI ===<br />
* example: http://localhost/api/v2/transfer/add/1225c695-cfb8-4ebb-aaaa-80da344efa6a (not yet implemented)<br />
<br />
=== State-IRI ===<br />
* used to retrieve status of transfer<br />
* implemented as Atom document<br />
* example: /api/v1/location/[deposit location UUID]/sword/state/<br />
* should be able to subscribe like RSS feed<br />
<br />
=== Service document ===</div>Mcantelonhttps://wiki.archivematica.org/index.php?title=Sword_API&diff=9418Sword API2014-01-27T23:02:53Z<p>Mcantelon: /* EM-IRI */</p>
<hr />
<div>[[Main Page]] > [[Documentation]] > [[Requirements]] > Sword API<br />
<br />
== Overview ==<br />
<br />
One of the 1.1 release features is a sponsored project to integrate Archivematica with Islandora. This integration will be accomplished by creating a [http://swordapp.org Sword] 2.0 API for the Archivematica [https://www.archivematica.org/wiki/Administrator_manual_1.0#Storage_service storage service]. Islandora development work will add functionality to Islandora to use this API to deposit digital objects into Archviematica.<br />
<br />
As described [[Overview|elsewhere]] on this wiki, ''"the primary function of Archivematica is to process digital transfers (accessioned digital objects), turn them into SIPs, apply format policies and create high-quality, repository-independent Archival Information Packages (AIP)"''.<br />
<br />
The Archivematica Sword API allows 3rd party applications to automate the process of creating Transfers. <br />
#Create Transfer - set the name and other metadata about a Transfer<br />
#Populate Transfer - add/edit/update digital objects in a Transfer, and associated metadata<br />
#Finalize Transfer - indicates that the Transfer is ready to start processing.<br />
<br />
After content has been deposited, if users have access to the deposit directory they can also manually manipulate the deposit directory aside from any manipulation using the API.<br />
<br />
Once a Transfer has been created, populated and finalized, Archivematica will begin processing that Transfer.<br />
<br />
== Configuration ==<br />
<br />
The SWORD API is part of the Archivematica storage service REST API. The storage service also talks to the Archivematica dashboard, however, to notify it that a, transfer created from a SWORD deposit, has been approved for processing.<br />
<br />
To use the SWORD API you must install the Archivematica dashboard 1.0 branch and the Archivematica storage service dev/issue-5980-islandora branch.<br />
<br />
Dashboard configuration:<br />
<br />
# In dashboard REST API administration, add the IP of the storage service server to IP whitelist<br />
# In dashboard user administration, take note of username and API key for a dashboard user (example: user "demo" and API key "4e5f32ab2aefd3543e1b19a2de554dd65f90108a")<br />
# In dashboard general admininstration, take note of the dashboard's UUID<br />
<br />
Storage service configuration:<br />
<br />
# In the storage service web interface's Pipelines tab, find the dashboard pipeline (using dashboard's UUID noted during dashboard configuration)<br />
# Enter the dashboard's IP address into the "Remote name" field and the user and API key noted earlier into the "Api username" and "Api key" fields. Click the button to submit these changes.<br />
<br />
After configuration you'll need to find the space UUID of the SWORD server. To do so, in the web interface's Spaces tab, click "View Details and Locations" for the SWORD server. The UUID will be shown at the top of the screen. The UUID is used to figure out the initial API URL to access (for example: "http://localhost:8000/api/v1/space/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/").<br />
<br />
== Example session ==<br />
<br />
Below is an example session using curl to manipulate the API. In the example a deposit is created, a file is added to it, and it is finalized.<br />
<br />
NOTE: The SWORD API is in the process of being moved to the storage service. These URLs may not work.<br />
<br />
<pre># create new deposit, providing a METS file specifying digital object URLs to download in the background<br />
curl -v -H "In-Progress: true" --data-binary @mets.xml --request POST http://localhost:8000/api/v1/space/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/<br />
# response XML includes endpoints for adding additional files, etc.<br />
<br />
# add a single file to the deposit<br />
curl -v -H "Content-Disposition: attachment; filename=cat.jpg" --request POST \<br />
--data-binary "@cat.jpg" \<br />
http://127.0.0.1:8000/api/v1/location/9c8b4ac0-0407-4360-a10d-af6c62a48b69/sword/media/<br />
<br />
# start another background download of resources specified in a METS<br />
curl -v -H "In-Progress: true" -H "Packaging: METS" --data-binary @mets.xml --request POST http://127.0.0.1:8000/api/v1/location/9c8b4ac0-0407-4360-a10d-af6c62a48b69/sword/media/<br />
<br />
# finalize transfer and approve processing<br />
curl -v -H "In-Progress: false" --request POST http://127.0.0.1:8000/api/v1/location/149cc29d-6472-4bcf-bee8-f8223bf60580/sword/<br />
</pre><br />
<br />
You might, at some point, want to list the transfers that have been started. The following curl command will do so.<br />
<br />
<pre>curl -v http://localhost:8000/api/v1/space/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/</pre><br />
<br />
If you're working on a transfer and want to list what files are included in it, the following curl command will list them.<br />
<br />
<pre># list files in transfer<br />
curl -v http://127.0.0.1:8000/api/v1/location/9c8b4ac0-0407-4360-a10d-af6c62a48b69/sword/media/</pre><br />
<br />
If you've started a deposit, but want to discard it, you can delete the deposit. The following curl command shows an example.<br />
<br />
<pre>curl -v -XDELETE http://127.0.0.1:8000/api/v1/location/149cc29d-6472-4bcf-bee8-f8223bf60580/sword/</pre><br />
<br />
== Synchronous Deposit Examples ==<br />
<br />
If you wanted to deposit a transfer then immediately finalize it you could use something like the following curl command.<br />
<br />
<pre>curl -v -H "In-Progress: false" --data-binary @mets.xml --request POST http://localhost:8000/api/v1/space/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/</pre><br />
<br />
<br />
== Endpoints ==<br />
<br />
=== Service document ===<br />
<br />
The SWORD service document provides information about the SWORD provider's capacities and lists SWORD collections. Archivematica currently includes one SWORD collection to which SWORD deposits can be made: transfers.<br />
<br />
The SWORD service document endpoint is located at /api/v1/sword/.<br />
<br />
Service document example:<br />
<pre><br />
<service xmlns:dcterms="http://purl.org/dc/terms/"<br />
xmlns:sword="http://purl.org/net/sword/terms/"<br />
xmlns:atom="http://www.w3.org/2005/Atom"<br />
xmlns="http://www.w3.org/2007/app"><br />
<br />
<sword:version>2.0</sword:version><br />
<br />
<workspace><br />
<atom:title>Archivematica storage service</atom:title><br />
<br />
<br />
<collection href="http://192.168.1.231:8000/api/v1/space/8f24ef5f-19d5-4b77-8a38-b30d034b11e7/sword/collection/"><br />
<atom:title>Collection</atom:title><br />
<accept>*/*</accept><br />
<accept alternate="multipart-related">*/*</accept><br />
<sword:mediation>false</sword:mediation><br />
</collection><br />
<br />
</workspace><br />
</service><br />
</pre><br />
<br />
=== List existing transfers ===<br />
* HTTP Get to the Collection IRI (defined by default as: /api/v1/space/[space UUID]/sword/collection/)<br />
* Transfers are listed as an Atom feed<br />
* Each Atom feed entry contains an "atom:link" element whose href attribute contains the URL needed to get details about the transfer<br />
* optional filters via get parameters (not yet implemented)<br />
<br />
Example response:<br />
<pre><br />
<atom:feed xmlns="http://www.w3.org/2005/Atom"><br />
<atom:id>http://192.168.1.231:8000/api/v1/space/8f24ef5f-19d5-4b77-8a38-b30d034b11e7/sword/collection/</atom:id><br />
<atom:title type="text">Deposits</atom:title><br />
<atom:link href="http://192.168.1.231:8000/api/v1/space/8f24ef5f-19d5-4b77-8a38-b30d034b11e7/sword/collection/" rel="self"><br />
</atom:link><br />
<atom:entry><br />
<atom:id>http://192.168.1.231:8000/api/v1/location/88e70cd2-9258-4a84-8938-16e74be032e6/sword/</atom:id><br />
<atom:title type="text">Cinderella</atom:title><br />
<atom:link href="http://192.168.1.231:8000/api/v1/location/88e70cd2-9258-4a84-8938-16e74be032e6/sword/" rel="self"><br />
</atom:link><br />
</atom:entry><br />
</atom:feed><br />
</pre><br />
<br />
=== Create a new transfer ===<br />
* used to start a new transfer in Archivematica<br />
* HTTP POST of an Atom Entry Document to the Collection IRI (defined by default as: /api/v1/space/[space UUID]/sword/collection/)<br />
<br />
'''Possible HTTP Response Codes'''<br />
* HTTP 200 OK - transfer already exists (not yet implemented)<br />
* HTTP 201 Created - transfer has been accepted<br />
* HTTP 412 Precondition Failed - required metadata missing or invalid<br />
<br />
Valid requests will receive a Sword Deposit Receipt in the body of the response.<br />
<br />
'''Required HTTP Headers'''<br />
The HTTP POST must include certain specific http headers. <br />
<br />
Required by http 1.1 specification:<br />
* Host: Must be set to archivematica host name.<br />
* Content-Length: Must be set to the length of the atom entry document.<br />
* Content-Type: Must be set to "application/atom+xml;type=entry".<br />
<br />
Required by Archivematica. <br />
* Authorization: Must include the api key and username assigned by Archivematica.<br />
<br />
Required by SWORD 2.0 protocol:<br />
* In-Progress: Must be set to "true"<br />
<br />
Optional in SWORD 2.0 protocol:<br />
* On-Behalf-Of: not implemented by Archivematica<br />
* Slug: not implemented by Archivematica<br />
<br />
'''Required in Body'''<br />
The Body of the request must be a valid METS Document. The required fields in an Atom Entry Document are:<br />
* LABEL: used as the transfer name<br />
* id: used as an accession id (not yet implemented)<br />
* author: used as the source of acquisition (not yet implemented)<br />
* summary: not implemented yet. Could be used in the future as a description for the Transfer<br />
* updated: should be set to the current timestamp. <br />
<br />
'''Example'''<br />
Example HTTP POST request:<br />
<pre><br />
POST /api/v1/space/96606387-cc70-4b09-b422-a7220606488d/sword/collection/ HTTP/1.1<br />
Host: localhost<br />
Authorization: Archivematica-API api_key="XXXXXXXXXXXXXXXXXXXX", username="timh"<br />
Content-Length: 213<br />
Content-Type: application/atom+xml;type=entry<br />
In-Progress: true<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<METS:mets EXT_VERSION="1.1" OBJID="islandora:72" LABEL="Cinderella"<br />
xmlns:METS="http://www.loc.gov/METS/"<br />
xmlns:xlink="http://www.w3.org/1999/xlink"<br />
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"<br />
xsi:schemaLocation="http://www.loc.gov/METS/ http://www.fedora.info/definitions/1/0/mets-fedora-ext1-1.xsd"><br />
<METS:fileSec><br />
<METS:fileGrp ID="DATASTREAMS"><br />
<METS:fileGrp ID="OBJ"><br />
<METS:file ID="OBJ.0"><br />
<METS:FLocat xlink:title="Cinderella_(1865).pdf" LOCTYPE="URL"<br />
xlink:href="http://localhost:8080/fedora/get/islandora:72/OBJ/2013-08-12T14:46:43.454Z" /><br />
</METS:file><br />
</METS:fileGrp><br />
</METS:fileGrp><br />
</METS:fileSec><br />
</METS:mets><br />
</pre><br />
<br />
Example Response:<br />
<pre><br />
201 Created<br />
Location: http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/<br />
<br />
<entry xmlns="http://www.w3.org/2005/Atom"<br />
xmlns:sword="http://purl.org/net/sword/"<br />
xmlns:dcterms="http://purl.org/dc/terms/"><br />
<br />
<title>Cinderella</title><br />
<id>91d4f258-0050-4914-9d0c-6a74815358d2</id><br />
<updated></updated><br />
<generator uri="https://www.archivematica.org" version="1.0"/><br />
<br />
<summary>A deposit was started.</summary><br />
<sword:treatment>A deposit directory was created and, optionally, asynchronous download of digital objects.</sword:treatment><br />
<br />
<link rel="alternate" href="http://www.swordserver.ac.uk/col1/mydeposit.html"/><br />
<link rel="edit-media" href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/media/"/><br />
<link rel="edit" href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/" /><br />
<link rel="http://purl.org/net/sword/terms/add" href="http://192.168.1.76:8000/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/" /><br />
<link rel="http://purl.org/net/sword/terms/statement" type="application/atom+xml;type=feed"<br />
href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/state/" /><br />
</entry><br />
</pre><br />
<br />
=== Add Files to a Transfer ===<br />
<br />
Post file data:<br />
* It is possible to also POST the actual file to a deposit location's EM-IRI (/api/v1/location/[location UUID]/sword/media/)<br />
* The file should be posted as the request body and the filename specified using the Content-Disposition header (as per RFC 6266): for example "Content-Disposition: Attachment; filename=dog.jpg"<br />
* An MD5 checksum for an uploaded file can be provided via the Content-MD5 header (as per RFC 1544): for example "Content-MD5: Q2hlY2sgSW50ZWdyaXR5IQ=="<br />
* If only an Atom Entry Document is POST'ed, Archivematica will look for uri's in the file StructMap section of the METS file, and attempt to GET each file listed, to include in the Transfer. (not yet implemented)<br />
<br />
=== Finalize a Transfer ===<br />
* POST with no body to the SE-IRI<br />
* set In-Progress HTTP header to : false<br />
* This will tell Archivematica that no further content will be added or removed from the Transfer. <br />
* Archivematica will finish fetching any files that were added previously, and once they have all been downloaded, the Transfer will start through the Archivematica pipeline.<br />
<br />
'''Example'''<br />
<pre><br />
POST http://localhost/api/v1/location/55ce8053-113a-4954-8aa3-fc9771da0bda/sword/ HTTP/1.1<br />
Host: localhost<br />
Authorization: Archivematica-API api_key="XXXXXXXXXXXXXXXXXXXX", username="timh"<br />
Content-Length: 0<br />
Content-Type: application/atom+xml;type=entry<br />
In-Progress: false<br />
</pre><br />
<br />
The response will be HTTP 200/OK or 400/Error (400 if the Transfer was already finalized). If the transfer doesn't exist the response will be HTTP 404.<br />
<br />
=== Get Status of Transfer ===<br />
To check Status:<br />
<br />
GET the State-IRI<br />
in this example:<br />
<br />
GET http://localhost/api/v1/location/09224ddb-4c7d-404c-9218-2f2e1b5a599e/sword/state/ HTTP/1.1<br />
<br />
response will include:<br />
<pre><atom:feed xmlns:sword="http://purl.org/net/sword/terms/" <br />
xmlns:atom="http://www.w3.org/2005/Atom"><br />
<br />
<atom:category scheme="http://purl.org/net/sword/terms/state"<br />
term="failed"<br />
label="State"><br />
Deposit initiation: Failed<br />
</atom:category><br />
<br />
</atom:feed></pre><br />
the list of possible descriptions is not finalized.<br />
<br />
The state term value will either be "processing" (asynchronous deposit still working), "complete" (ready to be finalized), or "failed" (asynchronous deposit encountered an error).<br />
<br />
== Additional Details == <br />
<br />
=== Transfer Details ===<br />
* redirect to Edit-IRI<br />
* used to get basic info about a Transfer with HTTP GET<br />
* can update basic info using HTTP PUT (not yet implemented)<br />
* can allow deletion with HTTP DELETE<br />
* follows the form: /api/v1/location/[deposit location UUID]/sword/<br />
* example: http://192.168.1.231:8000/api/v1/location/09224ddb-4c7d-404c-9218-2f2e1b5a599e/sword/<br />
<br />
=== EM-IRI ===<br />
* Edit-Media IRI <br />
* used to add new objects to an existing transfer<br />
* follows the form: [archivematica hostname]/api/v2/transfer/[uuid of transfer]/media<br />
* example: /api/v1/location/[deposit location UUID]/sword/media/<br />
<br />
An HTTP POST to the em-iri for a transfer should include a single file as the body. If the HTTP "Packaging" header is set to "METS" then METS XML can be sent as the body, specifying a list of digital object URLs to download in the background.<br />
<br />
An HTTP GET should return a list of files in the transfer<br />
<br />
An HTTP DELETE to the em-iri will remove all digital objects from the Transfer. This is a valid operation only while the Transfer is being assembled. Once the Transfer has been finalized, attempting to DELETE will return an error.<br />
<br />
=== Edit-IRI ===<br />
The client can replace the metadata of a resource by performing an HTTP PUT of a new Atom Entry on the Edit-IRI. (not yet implemented)<br />
<br />
This would be used to update metadata about a transfer, such as the transfer name.<br />
<br />
* example: http://localhost/api/v2/transfer/1225c695-cfb8-4ebb-aaaa-80da344efa6a/edit<br />
<br />
=== SE-IRI ===<br />
* example: http://localhost/api/v2/transfer/add/1225c695-cfb8-4ebb-aaaa-80da344efa6a (not yet implemented)<br />
<br />
=== State-IRI ===<br />
* used to retrieve status of transfer<br />
* implemented as Atom document<br />
* example: /api/v1/location/[deposit location UUID]/sword/state/<br />
* should be able to subscribe like RSS feed<br />
<br />
=== Service document ===</div>Mcantelonhttps://wiki.archivematica.org/index.php?title=Sword_API&diff=9417Sword API2014-01-27T23:00:12Z<p>Mcantelon: /* Example session */</p>
<hr />
<div>[[Main Page]] > [[Documentation]] > [[Requirements]] > Sword API<br />
<br />
== Overview ==<br />
<br />
One of the 1.1 release features is a sponsored project to integrate Archivematica with Islandora. This integration will be accomplished by creating a [http://swordapp.org Sword] 2.0 API for the Archivematica [https://www.archivematica.org/wiki/Administrator_manual_1.0#Storage_service storage service]. Islandora development work will add functionality to Islandora to use this API to deposit digital objects into Archviematica.<br />
<br />
As described [[Overview|elsewhere]] on this wiki, ''"the primary function of Archivematica is to process digital transfers (accessioned digital objects), turn them into SIPs, apply format policies and create high-quality, repository-independent Archival Information Packages (AIP)"''.<br />
<br />
The Archivematica Sword API allows 3rd party applications to automate the process of creating Transfers. <br />
#Create Transfer - set the name and other metadata about a Transfer<br />
#Populate Transfer - add/edit/update digital objects in a Transfer, and associated metadata<br />
#Finalize Transfer - indicates that the Transfer is ready to start processing.<br />
<br />
After content has been deposited, if users have access to the deposit directory they can also manually manipulate the deposit directory aside from any manipulation using the API.<br />
<br />
Once a Transfer has been created, populated and finalized, Archivematica will begin processing that Transfer.<br />
<br />
== Configuration ==<br />
<br />
The SWORD API is part of the Archivematica storage service REST API. The storage service also talks to the Archivematica dashboard, however, to notify it that a, transfer created from a SWORD deposit, has been approved for processing.<br />
<br />
To use the SWORD API you must install the Archivematica dashboard 1.0 branch and the Archivematica storage service dev/issue-5980-islandora branch.<br />
<br />
Dashboard configuration:<br />
<br />
# In dashboard REST API administration, add the IP of the storage service server to IP whitelist<br />
# In dashboard user administration, take note of username and API key for a dashboard user (example: user "demo" and API key "4e5f32ab2aefd3543e1b19a2de554dd65f90108a")<br />
# In dashboard general admininstration, take note of the dashboard's UUID<br />
<br />
Storage service configuration:<br />
<br />
# In the storage service web interface's Pipelines tab, find the dashboard pipeline (using dashboard's UUID noted during dashboard configuration)<br />
# Enter the dashboard's IP address into the "Remote name" field and the user and API key noted earlier into the "Api username" and "Api key" fields. Click the button to submit these changes.<br />
<br />
After configuration you'll need to find the space UUID of the SWORD server. To do so, in the web interface's Spaces tab, click "View Details and Locations" for the SWORD server. The UUID will be shown at the top of the screen. The UUID is used to figure out the initial API URL to access (for example: "http://localhost:8000/api/v1/space/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/").<br />
<br />
== Example session ==<br />
<br />
Below is an example session using curl to manipulate the API. In the example a deposit is created, a file is added to it, and it is finalized.<br />
<br />
NOTE: The SWORD API is in the process of being moved to the storage service. These URLs may not work.<br />
<br />
<pre># create new deposit, providing a METS file specifying digital object URLs to download in the background<br />
curl -v -H "In-Progress: true" --data-binary @mets.xml --request POST http://localhost:8000/api/v1/space/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/<br />
# response XML includes endpoints for adding additional files, etc.<br />
<br />
# add a single file to the deposit<br />
curl -v -H "Content-Disposition: attachment; filename=cat.jpg" --request POST \<br />
--data-binary "@cat.jpg" \<br />
http://127.0.0.1:8000/api/v1/location/9c8b4ac0-0407-4360-a10d-af6c62a48b69/sword/media/<br />
<br />
# start another background download of resources specified in a METS<br />
curl -v -H "In-Progress: true" -H "Packaging: METS" --data-binary @mets.xml --request POST http://127.0.0.1:8000/api/v1/location/9c8b4ac0-0407-4360-a10d-af6c62a48b69/sword/media/<br />
<br />
# finalize transfer and approve processing<br />
curl -v -H "In-Progress: false" --request POST http://127.0.0.1:8000/api/v1/location/149cc29d-6472-4bcf-bee8-f8223bf60580/sword/<br />
</pre><br />
<br />
You might, at some point, want to list the transfers that have been started. The following curl command will do so.<br />
<br />
<pre>curl -v http://localhost:8000/api/v1/space/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/</pre><br />
<br />
If you're working on a transfer and want to list what files are included in it, the following curl command will list them.<br />
<br />
<pre># list files in transfer<br />
curl -v http://127.0.0.1:8000/api/v1/location/9c8b4ac0-0407-4360-a10d-af6c62a48b69/sword/media/</pre><br />
<br />
If you've started a deposit, but want to discard it, you can delete the deposit. The following curl command shows an example.<br />
<br />
<pre>curl -v -XDELETE http://127.0.0.1:8000/api/v1/location/149cc29d-6472-4bcf-bee8-f8223bf60580/sword/</pre><br />
<br />
== Synchronous Deposit Examples ==<br />
<br />
If you wanted to deposit a transfer then immediately finalize it you could use something like the following curl command.<br />
<br />
<pre>curl -v -H "In-Progress: false" --data-binary @mets.xml --request POST http://localhost:8000/api/v1/space/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/</pre><br />
<br />
<br />
== Endpoints ==<br />
<br />
=== Service document ===<br />
<br />
The SWORD service document provides information about the SWORD provider's capacities and lists SWORD collections. Archivematica currently includes one SWORD collection to which SWORD deposits can be made: transfers.<br />
<br />
The SWORD service document endpoint is located at /api/v1/sword/.<br />
<br />
Service document example:<br />
<pre><br />
<service xmlns:dcterms="http://purl.org/dc/terms/"<br />
xmlns:sword="http://purl.org/net/sword/terms/"<br />
xmlns:atom="http://www.w3.org/2005/Atom"<br />
xmlns="http://www.w3.org/2007/app"><br />
<br />
<sword:version>2.0</sword:version><br />
<br />
<workspace><br />
<atom:title>Archivematica storage service</atom:title><br />
<br />
<br />
<collection href="http://192.168.1.231:8000/api/v1/space/8f24ef5f-19d5-4b77-8a38-b30d034b11e7/sword/collection/"><br />
<atom:title>Collection</atom:title><br />
<accept>*/*</accept><br />
<accept alternate="multipart-related">*/*</accept><br />
<sword:mediation>false</sword:mediation><br />
</collection><br />
<br />
</workspace><br />
</service><br />
</pre><br />
<br />
=== List existing transfers ===<br />
* HTTP Get to the Collection IRI (defined by default as: /api/v1/space/[space UUID]/sword/collection/)<br />
* Transfers are listed as an Atom feed<br />
* Each Atom feed entry contains an "atom:link" element whose href attribute contains the URL needed to get details about the transfer<br />
* optional filters via get parameters (not yet implemented)<br />
<br />
Example response:<br />
<pre><br />
<atom:feed xmlns="http://www.w3.org/2005/Atom"><br />
<atom:id>http://192.168.1.231:8000/api/v1/space/8f24ef5f-19d5-4b77-8a38-b30d034b11e7/sword/collection/</atom:id><br />
<atom:title type="text">Deposits</atom:title><br />
<atom:link href="http://192.168.1.231:8000/api/v1/space/8f24ef5f-19d5-4b77-8a38-b30d034b11e7/sword/collection/" rel="self"><br />
</atom:link><br />
<atom:entry><br />
<atom:id>http://192.168.1.231:8000/api/v1/location/88e70cd2-9258-4a84-8938-16e74be032e6/sword/</atom:id><br />
<atom:title type="text">Cinderella</atom:title><br />
<atom:link href="http://192.168.1.231:8000/api/v1/location/88e70cd2-9258-4a84-8938-16e74be032e6/sword/" rel="self"><br />
</atom:link><br />
</atom:entry><br />
</atom:feed><br />
</pre><br />
<br />
=== Create a new transfer ===<br />
* used to start a new transfer in Archivematica<br />
* HTTP POST of an Atom Entry Document to the Collection IRI (defined by default as: /api/v1/space/[space UUID]/sword/collection/)<br />
<br />
'''Possible HTTP Response Codes'''<br />
* HTTP 200 OK - transfer already exists (not yet implemented)<br />
* HTTP 201 Created - transfer has been accepted<br />
* HTTP 412 Precondition Failed - required metadata missing or invalid<br />
<br />
Valid requests will receive a Sword Deposit Receipt in the body of the response.<br />
<br />
'''Required HTTP Headers'''<br />
The HTTP POST must include certain specific http headers. <br />
<br />
Required by http 1.1 specification:<br />
* Host: Must be set to archivematica host name.<br />
* Content-Length: Must be set to the length of the atom entry document.<br />
* Content-Type: Must be set to "application/atom+xml;type=entry".<br />
<br />
Required by Archivematica. <br />
* Authorization: Must include the api key and username assigned by Archivematica.<br />
<br />
Required by SWORD 2.0 protocol:<br />
* In-Progress: Must be set to "true"<br />
<br />
Optional in SWORD 2.0 protocol:<br />
* On-Behalf-Of: not implemented by Archivematica<br />
* Slug: not implemented by Archivematica<br />
<br />
'''Required in Body'''<br />
The Body of the request must be a valid METS Document. The required fields in an Atom Entry Document are:<br />
* LABEL: used as the transfer name<br />
* id: used as an accession id (not yet implemented)<br />
* author: used as the source of acquisition (not yet implemented)<br />
* summary: not implemented yet. Could be used in the future as a description for the Transfer<br />
* updated: should be set to the current timestamp. <br />
<br />
'''Example'''<br />
Example HTTP POST request:<br />
<pre><br />
POST /api/v1/space/96606387-cc70-4b09-b422-a7220606488d/sword/collection/ HTTP/1.1<br />
Host: localhost<br />
Authorization: Archivematica-API api_key="XXXXXXXXXXXXXXXXXXXX", username="timh"<br />
Content-Length: 213<br />
Content-Type: application/atom+xml;type=entry<br />
In-Progress: true<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<METS:mets EXT_VERSION="1.1" OBJID="islandora:72" LABEL="Cinderella"<br />
xmlns:METS="http://www.loc.gov/METS/"<br />
xmlns:xlink="http://www.w3.org/1999/xlink"<br />
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"<br />
xsi:schemaLocation="http://www.loc.gov/METS/ http://www.fedora.info/definitions/1/0/mets-fedora-ext1-1.xsd"><br />
<METS:fileSec><br />
<METS:fileGrp ID="DATASTREAMS"><br />
<METS:fileGrp ID="OBJ"><br />
<METS:file ID="OBJ.0"><br />
<METS:FLocat xlink:title="Cinderella_(1865).pdf" LOCTYPE="URL"<br />
xlink:href="http://localhost:8080/fedora/get/islandora:72/OBJ/2013-08-12T14:46:43.454Z" /><br />
</METS:file><br />
</METS:fileGrp><br />
</METS:fileGrp><br />
</METS:fileSec><br />
</METS:mets><br />
</pre><br />
<br />
Example Response:<br />
<pre><br />
201 Created<br />
Location: http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/<br />
<br />
<entry xmlns="http://www.w3.org/2005/Atom"<br />
xmlns:sword="http://purl.org/net/sword/"<br />
xmlns:dcterms="http://purl.org/dc/terms/"><br />
<br />
<title>Cinderella</title><br />
<id>91d4f258-0050-4914-9d0c-6a74815358d2</id><br />
<updated></updated><br />
<generator uri="https://www.archivematica.org" version="1.0"/><br />
<br />
<summary>A deposit was started.</summary><br />
<sword:treatment>A deposit directory was created and, optionally, asynchronous download of digital objects.</sword:treatment><br />
<br />
<link rel="alternate" href="http://www.swordserver.ac.uk/col1/mydeposit.html"/><br />
<link rel="edit-media" href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/media/"/><br />
<link rel="edit" href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/" /><br />
<link rel="http://purl.org/net/sword/terms/add" href="http://192.168.1.76:8000/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/" /><br />
<link rel="http://purl.org/net/sword/terms/statement" type="application/atom+xml;type=feed"<br />
href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/state/" /><br />
</entry><br />
</pre><br />
<br />
=== Add Files to a Transfer ===<br />
<br />
Post file data:<br />
* It is possible to also POST the actual file to a deposit location's EM-IRI (/api/v1/location/[location UUID]/sword/media/)<br />
* The file should be posted as the request body and the filename specified using the Content-Disposition header (as per RFC 6266): for example "Content-Disposition: Attachment; filename=dog.jpg"<br />
* An MD5 checksum for an uploaded file can be provided via the Content-MD5 header (as per RFC 1544): for example "Content-MD5: Q2hlY2sgSW50ZWdyaXR5IQ=="<br />
* If only an Atom Entry Document is POST'ed, Archivematica will look for uri's in the file StructMap section of the METS file, and attempt to GET each file listed, to include in the Transfer. (not yet implemented)<br />
<br />
=== Finalize a Transfer ===<br />
* POST with no body to the SE-IRI<br />
* set In-Progress HTTP header to : false<br />
* This will tell Archivematica that no further content will be added or removed from the Transfer. <br />
* Archivematica will finish fetching any files that were added previously, and once they have all been downloaded, the Transfer will start through the Archivematica pipeline.<br />
<br />
'''Example'''<br />
<pre><br />
POST http://localhost/api/v1/location/55ce8053-113a-4954-8aa3-fc9771da0bda/sword/ HTTP/1.1<br />
Host: localhost<br />
Authorization: Archivematica-API api_key="XXXXXXXXXXXXXXXXXXXX", username="timh"<br />
Content-Length: 0<br />
Content-Type: application/atom+xml;type=entry<br />
In-Progress: false<br />
</pre><br />
<br />
The response will be HTTP 200/OK or 400/Error (400 if the Transfer was already finalized). If the transfer doesn't exist the response will be HTTP 404.<br />
<br />
=== Get Status of Transfer ===<br />
To check Status:<br />
<br />
GET the State-IRI<br />
in this example:<br />
<br />
GET http://localhost/api/v1/location/09224ddb-4c7d-404c-9218-2f2e1b5a599e/sword/state/ HTTP/1.1<br />
<br />
response will include:<br />
<pre><atom:feed xmlns:sword="http://purl.org/net/sword/terms/" <br />
xmlns:atom="http://www.w3.org/2005/Atom"><br />
<br />
<atom:category scheme="http://purl.org/net/sword/terms/state"<br />
term="failed"<br />
label="State"><br />
Deposit initiation: Failed<br />
</atom:category><br />
<br />
</atom:feed></pre><br />
the list of possible descriptions is not finalized.<br />
<br />
The state term value will either be "processing" (asynchronous deposit still working), "complete" (ready to be finalized), or "failed" (asynchronous deposit encountered an error).<br />
<br />
== Additional Details == <br />
<br />
=== Transfer Details ===<br />
* redirect to Edit-IRI<br />
* used to get basic info about a Transfer with HTTP GET<br />
* can update basic info using HTTP PUT (not yet implemented)<br />
* can allow deletion with HTTP DELETE<br />
* follows the form: /api/v1/location/[deposit location UUID]/sword/<br />
* example: http://192.168.1.231:8000/api/v1/location/09224ddb-4c7d-404c-9218-2f2e1b5a599e/sword/<br />
<br />
=== EM-IRI ===<br />
* Edit-Media IRI <br />
* used to add new objects to an existing transfer<br />
* follows the form: [archivematica hostname]/api/v2/transfer/[uuid of transfer]/media<br />
* example: /api/v1/location/[deposit location UUID]/sword/media/<br />
<br />
An HTTP POST to the em-iri for a transfer should include a file as the body<br />
<br />
An HTTP GET should return a list of files in the transfer<br />
<br />
An HTTP DELETE to the em-iri will remove all digital objects from the Transfer. This is a valid operation only while the Transfer is being assembled. Once the Transfer has been finalized, attempting to DELETE will return an error.<br />
<br />
=== Edit-IRI ===<br />
The client can replace the metadata of a resource by performing an HTTP PUT of a new Atom Entry on the Edit-IRI. (not yet implemented)<br />
<br />
This would be used to update metadata about a transfer, such as the transfer name.<br />
<br />
* example: http://localhost/api/v2/transfer/1225c695-cfb8-4ebb-aaaa-80da344efa6a/edit<br />
<br />
=== SE-IRI ===<br />
* example: http://localhost/api/v2/transfer/add/1225c695-cfb8-4ebb-aaaa-80da344efa6a (not yet implemented)<br />
<br />
=== State-IRI ===<br />
* used to retrieve status of transfer<br />
* implemented as Atom document<br />
* example: /api/v1/location/[deposit location UUID]/sword/state/<br />
* should be able to subscribe like RSS feed<br />
<br />
=== Service document ===</div>Mcantelonhttps://wiki.archivematica.org/index.php?title=Sword_API&diff=9341Sword API2014-01-11T00:18:22Z<p>Mcantelon: /* Add Files to a Transfer */</p>
<hr />
<div><br />
== Overview ==<br />
<br />
One of the 1.1 release features is a sponsored project to integrate Archivematica with Islandora. This integration will be accomplished by creating a [http://swordapp.org Sword] 2.0 API for the Archivematica [https://www.archivematica.org/wiki/Administrator_manual_1.0#Storage_service storage service]. Islandora development work will add functionality to Islandora to use this API to deposit digital objects into Archviematica.<br />
<br />
As described [[Overview|elsewhere]] on this wiki, ''"the primary function of Archivematica is to process digital transfers (accessioned digital objects), turn them into SIPs, apply format policies and create high-quality, repository-independent Archival Information Packages (AIP)"''.<br />
<br />
The Archivematica Sword API allows 3rd party applications to automate the process of creating Transfers. <br />
#Create Transfer - set the name and other metadata about a Transfer<br />
#Populate Transfer - add/edit/update digital objects in a Transfer, and associated metadata<br />
#Finalize Transfer - indicates that the Transfer is ready to start processing.<br />
<br />
After content has been deposited, if users have access to the deposit directory they can also manually manipulate the deposit directory aside from any manipulation using the API.<br />
<br />
Once a Transfer has been created, populated and finalized, Archivematica will begin processing that Transfer.<br />
<br />
== Configuration ==<br />
<br />
The SWORD API is part of the Archivematica storage service REST API. The storage service also talks to the Archivematica dashboard, however, to notify it that a, transfer created from a SWORD deposit, has been approved for processing.<br />
<br />
To use the SWORD API you must install the Archivematica dashboard 1.0 branch and the Archivematica storage service dev/issue-5980-islandora branch.<br />
<br />
Dashboard configuration:<br />
<br />
# In dashboard REST API administration, add the IP of the storage service server to IP whitelist<br />
# In dashboard user administration, take note of username and API key for a dashboard user (example: user "demo" and API key "4e5f32ab2aefd3543e1b19a2de554dd65f90108a")<br />
# In dashboard general admininstration, take note of the dashboard's UUID<br />
<br />
Storage service configuration:<br />
<br />
# In the storage service web interface's Pipelines tab, find the dashboard pipeline (using dashboard's UUID noted during dashboard configuration)<br />
# Enter the dashboard's IP address into the "Remote name" field and the user and API key noted earlier into the "Api username" and "Api key" fields. Click the button to submit these changes.<br />
<br />
After configuration you'll need to find the space UUID of the SWORD server. To do so, in the web interface's Spaces tab, click "View Details and Locations" for the SWORD server. The UUID will be shown at the top of the screen. The UUID is used to figure out the initial API URL to access (for example: "http://localhost:8000/api/v1/space/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/").<br />
<br />
== Example session ==<br />
<br />
Below is an example session using curl to manipulate the API. In the example a deposit is created, a file is added to it, and it is finalized.<br />
<br />
NOTE: The SWORD API is in the process of being moved to the storage service. These URLs may not work.<br />
<br />
<pre># create new deposit<br />
curl -v -H "In-Progress: true" --data-binary @mets.xml --request POST http://localhost:8000/api/v1/space/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/<br />
# response XML includes endpoints for adding additional files, etc.<br />
<br />
# add a file to the deposit<br />
curl -v -H "Content-Disposition: attachment; filename=mets.xml" --request POST \<br />
--data-binary "@mets.xml" \<br />
http://127.0.0.1:8000/api/v1/location/9c8b4ac0-0407-4360-a10d-af6c62a48b69/sword/media/<br />
<br />
# finalize transfer and approve processing<br />
curl -v -H "In-Progress: false" --request POST http://127.0.0.1:8000/api/v1/location/149cc29d-6472-4bcf-bee8-f8223bf60580/sword/<br />
</pre><br />
<br />
You might, at some point, want to list the transfers that have been started. The following curl command will do so.<br />
<br />
<pre>curl -v http://localhost:8000/api/v1/space/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/</pre><br />
<br />
If you're working on a transfer and want to list what files are included in it, the following curl command will list them.<br />
<br />
<pre># list files in transfer<br />
curl -v http://127.0.0.1:8000/api/v1/location/9c8b4ac0-0407-4360-a10d-af6c62a48b69/sword/media/</pre><br />
<br />
If you've started a deposit, but want to discard it, you can delete the deposit. The following curl command shows an example.<br />
<br />
<pre>curl -v -XDELETE http://127.0.0.1:8000/api/v1/location/149cc29d-6472-4bcf-bee8-f8223bf60580/sword/</pre><br />
<br />
== Synchronous Deposit Examples ==<br />
<br />
If you wanted to deposit a transfer then immediately finalize it you could use something like the following curl command.<br />
<br />
<pre>curl -v -H "In-Progress: false" --data-binary @mets.xml --request POST http://localhost:8000/api/v1/space/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/</pre><br />
<br />
<br />
== Endpoints ==<br />
<br />
=== Service document ===<br />
<br />
The SWORD service document provides information about the SWORD provider's capacities and lists SWORD collections. Archivematica currently includes one SWORD collection to which SWORD deposits can be made: transfers.<br />
<br />
The SWORD service document endpoint is located at /api/v1/sword/.<br />
<br />
Service document example:<br />
<pre><br />
<service xmlns:dcterms="http://purl.org/dc/terms/"<br />
xmlns:sword="http://purl.org/net/sword/terms/"<br />
xmlns:atom="http://www.w3.org/2005/Atom"<br />
xmlns="http://www.w3.org/2007/app"><br />
<br />
<sword:version>2.0</sword:version><br />
<br />
<workspace><br />
<atom:title>Archivematica storage service</atom:title><br />
<br />
<br />
<collection href="http://192.168.1.231:8000/api/v1/space/8f24ef5f-19d5-4b77-8a38-b30d034b11e7/sword/collection/"><br />
<atom:title>Collection</atom:title><br />
<accept>*/*</accept><br />
<accept alternate="multipart-related">*/*</accept><br />
<sword:mediation>false</sword:mediation><br />
</collection><br />
<br />
</workspace><br />
</service><br />
</pre><br />
<br />
=== List existing transfers ===<br />
* HTTP Get to the Collection IRI (defined by default as: /api/v1/space/[space UUID]/sword/collection/)<br />
* Transfers are listed as an Atom feed<br />
* Each Atom feed entry contains an "atom:link" element whose href attribute contains the URL needed to get details about the transfer<br />
* optional filters via get parameters (not yet implemented)<br />
<br />
Example response:<br />
<pre><br />
<atom:feed xmlns="http://www.w3.org/2005/Atom"><br />
<atom:id>http://192.168.1.231:8000/api/v1/space/8f24ef5f-19d5-4b77-8a38-b30d034b11e7/sword/collection/</atom:id><br />
<atom:title type="text">Deposits</atom:title><br />
<atom:link href="http://192.168.1.231:8000/api/v1/space/8f24ef5f-19d5-4b77-8a38-b30d034b11e7/sword/collection/" rel="self"><br />
</atom:link><br />
<atom:entry><br />
<atom:id>http://192.168.1.231:8000/api/v1/location/88e70cd2-9258-4a84-8938-16e74be032e6/sword/</atom:id><br />
<atom:title type="text">Cinderella</atom:title><br />
<atom:link href="http://192.168.1.231:8000/api/v1/location/88e70cd2-9258-4a84-8938-16e74be032e6/sword/" rel="self"><br />
</atom:link><br />
</atom:entry><br />
</atom:feed><br />
</pre><br />
<br />
=== Create a new transfer ===<br />
* used to start a new transfer in Archivematica<br />
* HTTP POST of an Atom Entry Document to the Collection IRI (defined by default as: /api/v1/space/[space UUID]/sword/collection/)<br />
<br />
'''Possible HTTP Response Codes'''<br />
* HTTP 200 OK - transfer already exists (not yet implemented)<br />
* HTTP 201 Created - transfer has been accepted<br />
* HTTP 412 Precondition Failed - required metadata missing or invalid<br />
<br />
Valid requests will receive a Sword Deposit Receipt in the body of the response.<br />
<br />
'''Required HTTP Headers'''<br />
The HTTP POST must include certain specific http headers. <br />
<br />
Required by http 1.1 specification:<br />
* Host: Must be set to archivematica host name.<br />
* Content-Length: Must be set to the length of the atom entry document.<br />
* Content-Type: Must be set to "application/atom+xml;type=entry".<br />
<br />
Required by Archivematica. <br />
* Authorization: Must include the api key and username assigned by Archivematica.<br />
<br />
Required by SWORD 2.0 protocol:<br />
* In-Progress: Must be set to "true"<br />
<br />
Optional in SWORD 2.0 protocol:<br />
* On-Behalf-Of: not implemented by Archivematica<br />
* Slug: not implemented by Archivematica<br />
<br />
'''Required in Body'''<br />
The Body of the request must be a valid METS Document. The required fields in an Atom Entry Document are:<br />
* LABEL: used as the transfer name<br />
* id: used as an accession id (not yet implemented)<br />
* author: used as the source of acquisition (not yet implemented)<br />
* summary: not implemented yet. Could be used in the future as a description for the Transfer<br />
* updated: should be set to the current timestamp. <br />
<br />
'''Example'''<br />
Example HTTP POST request:<br />
<pre><br />
POST /api/v1/space/96606387-cc70-4b09-b422-a7220606488d/sword/collection/ HTTP/1.1<br />
Host: localhost<br />
Authorization: Archivematica-API api_key="XXXXXXXXXXXXXXXXXXXX", username="timh"<br />
Content-Length: 213<br />
Content-Type: application/atom+xml;type=entry<br />
In-Progress: true<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<METS:mets EXT_VERSION="1.1" OBJID="islandora:72" LABEL="Cinderella"<br />
xmlns:METS="http://www.loc.gov/METS/"<br />
xmlns:xlink="http://www.w3.org/1999/xlink"<br />
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"<br />
xsi:schemaLocation="http://www.loc.gov/METS/ http://www.fedora.info/definitions/1/0/mets-fedora-ext1-1.xsd"><br />
<METS:fileSec><br />
<METS:fileGrp ID="DATASTREAMS"><br />
<METS:fileGrp ID="OBJ"><br />
<METS:file ID="OBJ.0"><br />
<METS:FLocat xlink:title="Cinderella_(1865).pdf" LOCTYPE="URL"<br />
xlink:href="http://localhost:8080/fedora/get/islandora:72/OBJ/2013-08-12T14:46:43.454Z" /><br />
</METS:file><br />
</METS:fileGrp><br />
</METS:fileGrp><br />
</METS:fileSec><br />
</METS:mets><br />
</pre><br />
<br />
Example Response:<br />
<pre><br />
201 Created<br />
Location: http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/<br />
<br />
<entry xmlns="http://www.w3.org/2005/Atom"<br />
xmlns:sword="http://purl.org/net/sword/"<br />
xmlns:dcterms="http://purl.org/dc/terms/"><br />
<br />
<title>Cinderella</title><br />
<id>91d4f258-0050-4914-9d0c-6a74815358d2</id><br />
<updated></updated><br />
<generator uri="https://www.archivematica.org" version="1.0"/><br />
<br />
<summary>A deposit was started.</summary><br />
<sword:treatment>A deposit directory was created and, optionally, asynchronous download of digital objects.</sword:treatment><br />
<br />
<link rel="alternate" href="http://www.swordserver.ac.uk/col1/mydeposit.html"/><br />
<link rel="edit-media" href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/media/"/><br />
<link rel="edit" href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/" /><br />
<link rel="http://purl.org/net/sword/terms/add" href="http://192.168.1.76:8000/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/" /><br />
<link rel="http://purl.org/net/sword/terms/statement" type="application/atom+xml;type=feed"<br />
href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/state/" /><br />
</entry><br />
</pre><br />
<br />
=== Add Files to a Transfer ===<br />
<br />
Post file data:<br />
* It is possible to also POST the actual file to a deposit location's EM-IRI (/api/v1/location/[location UUID]/sword/media/)<br />
* The file should be posted as the request body and the filename specified using the Content-Disposition header (as per RFC 6266): for example "Content-Disposition: Attachment; filename=dog.jpg"<br />
* An MD5 checksum for an uploaded file can be provided via the Content-MD5 header (as per RFC 1544): for example "Content-MD5: Q2hlY2sgSW50ZWdyaXR5IQ=="<br />
* If only an Atom Entry Document is POST'ed, Archivematica will look for uri's in the file StructMap section of the METS file, and attempt to GET each file listed, to include in the Transfer. (not yet implemented)<br />
<br />
=== Finalize a Transfer ===<br />
* POST with no body to the SE-IRI<br />
* set In-Progress HTTP header to : false<br />
* This will tell Archivematica that no further content will be added or removed from the Transfer. <br />
* Archivematica will finish fetching any files that were added previously, and once they have all been downloaded, the Transfer will start through the Archivematica pipeline.<br />
<br />
'''Example'''<br />
<pre><br />
POST http://localhost/api/v1/location/55ce8053-113a-4954-8aa3-fc9771da0bda/sword/ HTTP/1.1<br />
Host: localhost<br />
Authorization: Archivematica-API api_key="XXXXXXXXXXXXXXXXXXXX", username="timh"<br />
Content-Length: 0<br />
Content-Type: application/atom+xml;type=entry<br />
In-Progress: false<br />
</pre><br />
<br />
The response will be HTTP 200/OK or 400/Error (400 if the Transfer was already finalized). If the transfer doesn't exist the response will be HTTP 404.<br />
<br />
=== Get Status of Transfer ===<br />
To check Status:<br />
<br />
GET the State-IRI<br />
in this example:<br />
<br />
GET http://localhost/api/v1/location/09224ddb-4c7d-404c-9218-2f2e1b5a599e/sword/state/ HTTP/1.1<br />
<br />
response will include:<br />
<pre><atom:feed xmlns:sword="http://purl.org/net/sword/terms/" <br />
xmlns:atom="http://www.w3.org/2005/Atom"><br />
<br />
<atom:category scheme="http://purl.org/net/sword/terms/state"<br />
term="failed"<br />
label="State"><br />
Deposit initiation: Failed<br />
</atom:category><br />
<br />
</atom:feed></pre><br />
the list of possible descriptions is not finalized.<br />
<br />
The state term value will either be "processing" (asynchronous deposit still working), "complete" (ready to be finalized), or "failed" (asynchronous deposit encountered an error).<br />
<br />
== Additional Details == <br />
<br />
=== Transfer Details ===<br />
* redirect to Edit-IRI<br />
* used to get basic info about a Transfer with HTTP GET<br />
* can update basic info using HTTP PUT (not yet implemented)<br />
* can allow deletion with HTTP DELETE<br />
* follows the form: /api/v1/location/[deposit location UUID]/sword/<br />
* example: http://192.168.1.231:8000/api/v1/location/09224ddb-4c7d-404c-9218-2f2e1b5a599e/sword/<br />
<br />
=== EM-IRI ===<br />
* Edit-Media IRI <br />
* used to add new objects to an existing transfer<br />
* follows the form: [archivematica hostname]/api/v2/transfer/[uuid of transfer]/media<br />
* example: /api/v1/location/[deposit location UUID]/sword/media/<br />
<br />
An HTTP POST to the em-iri for a transfer should include a file as the body<br />
<br />
An HTTP GET should return a list of files in the transfer<br />
<br />
An HTTP DELETE to the em-iri will remove all digital objects from the Transfer. This is a valid operation only while the Transfer is being assembled. Once the Transfer has been finalized, attempting to DELETE will return an error.<br />
<br />
=== Edit-IRI ===<br />
The client can replace the metadata of a resource by performing an HTTP PUT of a new Atom Entry on the Edit-IRI. (not yet implemented)<br />
<br />
This would be used to update metadata about a transfer, such as the transfer name.<br />
<br />
* example: http://localhost/api/v2/transfer/1225c695-cfb8-4ebb-aaaa-80da344efa6a/edit<br />
<br />
=== SE-IRI ===<br />
* example: http://localhost/api/v2/transfer/add/1225c695-cfb8-4ebb-aaaa-80da344efa6a (not yet implemented)<br />
<br />
=== State-IRI ===<br />
* used to retrieve status of transfer<br />
* implemented as Atom document<br />
* example: /api/v1/location/[deposit location UUID]/sword/state/<br />
* should be able to subscribe like RSS feed<br />
<br />
=== Service document ===</div>Mcantelonhttps://wiki.archivematica.org/index.php?title=Sword_API&diff=9339Sword API2014-01-11T00:10:12Z<p>Mcantelon: /* List existing transfers */</p>
<hr />
<div><br />
== Overview ==<br />
<br />
One of the 1.1 release features is a sponsored project to integrate Archivematica with Islandora. This integration will be accomplished by creating a [http://swordapp.org Sword] 2.0 API for the Archivematica [https://www.archivematica.org/wiki/Administrator_manual_1.0#Storage_service storage service]. Islandora development work will add functionality to Islandora to use this API to deposit digital objects into Archviematica.<br />
<br />
As described [[Overview|elsewhere]] on this wiki, ''"the primary function of Archivematica is to process digital transfers (accessioned digital objects), turn them into SIPs, apply format policies and create high-quality, repository-independent Archival Information Packages (AIP)"''.<br />
<br />
The Archivematica Sword API allows 3rd party applications to automate the process of creating Transfers. <br />
#Create Transfer - set the name and other metadata about a Transfer<br />
#Populate Transfer - add/edit/update digital objects in a Transfer, and associated metadata<br />
#Finalize Transfer - indicates that the Transfer is ready to start processing.<br />
<br />
After content has been deposited, if users have access to the deposit directory they can also manually manipulate the deposit directory aside from any manipulation using the API.<br />
<br />
Once a Transfer has been created, populated and finalized, Archivematica will begin processing that Transfer.<br />
<br />
== Configuration ==<br />
<br />
The SWORD API is part of the Archivematica storage service REST API. The storage service also talks to the Archivematica dashboard, however, to notify it that a, transfer created from a SWORD deposit, has been approved for processing.<br />
<br />
To use the SWORD API you must install the Archivematica dashboard 1.0 branch and the Archivematica storage service dev/issue-5980-islandora branch.<br />
<br />
Dashboard configuration:<br />
<br />
# In dashboard REST API administration, add the IP of the storage service server to IP whitelist<br />
# In dashboard user administration, take note of username and API key for a dashboard user (example: user "demo" and API key "4e5f32ab2aefd3543e1b19a2de554dd65f90108a")<br />
# In dashboard general admininstration, take note of the dashboard's UUID<br />
<br />
Storage service configuration:<br />
<br />
# In the storage service web interface's Pipelines tab, find the dashboard pipeline (using dashboard's UUID noted during dashboard configuration)<br />
# Enter the dashboard's IP address into the "Remote name" field and the user and API key noted earlier into the "Api username" and "Api key" fields. Click the button to submit these changes.<br />
<br />
After configuration you'll need to find the space UUID of the SWORD server. To do so, in the web interface's Spaces tab, click "View Details and Locations" for the SWORD server. The UUID will be shown at the top of the screen. The UUID is used to figure out the initial API URL to access (for example: "http://localhost:8000/api/v1/space/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/").<br />
<br />
== Example session ==<br />
<br />
Below is an example session using curl to manipulate the API. In the example a deposit is created, a file is added to it, and it is finalized.<br />
<br />
NOTE: The SWORD API is in the process of being moved to the storage service. These URLs may not work.<br />
<br />
<pre># create new deposit<br />
curl -v -H "In-Progress: true" --data-binary @mets.xml --request POST http://localhost:8000/api/v1/space/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/<br />
# response XML includes endpoints for adding additional files, etc.<br />
<br />
# add a file to the deposit<br />
curl -v -H "Content-Disposition: attachment; filename=mets.xml" --request POST \<br />
--data-binary "@mets.xml" \<br />
http://127.0.0.1:8000/api/v1/location/9c8b4ac0-0407-4360-a10d-af6c62a48b69/sword/media/<br />
<br />
# finalize transfer and approve processing<br />
curl -v -H "In-Progress: false" --request POST http://127.0.0.1:8000/api/v1/location/149cc29d-6472-4bcf-bee8-f8223bf60580/sword/<br />
</pre><br />
<br />
You might, at some point, want to list the transfers that have been started. The following curl command will do so.<br />
<br />
<pre>curl -v http://localhost:8000/api/v1/space/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/</pre><br />
<br />
If you're working on a transfer and want to list what files are included in it, the following curl command will list them.<br />
<br />
<pre># list files in transfer<br />
curl -v http://127.0.0.1:8000/api/v1/location/9c8b4ac0-0407-4360-a10d-af6c62a48b69/sword/media/</pre><br />
<br />
If you've started a deposit, but want to discard it, you can delete the deposit. The following curl command shows an example.<br />
<br />
<pre>curl -v -XDELETE http://127.0.0.1:8000/api/v1/location/149cc29d-6472-4bcf-bee8-f8223bf60580/sword/</pre><br />
<br />
== Synchronous Deposit Examples ==<br />
<br />
If you wanted to deposit a transfer then immediately finalize it you could use something like the following curl command.<br />
<br />
<pre>curl -v -H "In-Progress: false" --data-binary @mets.xml --request POST http://localhost:8000/api/v1/space/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/</pre><br />
<br />
<br />
== Endpoints ==<br />
<br />
=== Service document ===<br />
<br />
The SWORD service document provides information about the SWORD provider's capacities and lists SWORD collections. Archivematica currently includes one SWORD collection to which SWORD deposits can be made: transfers.<br />
<br />
The SWORD service document endpoint is located at /api/v1/sword/.<br />
<br />
Service document example:<br />
<pre><br />
<service xmlns:dcterms="http://purl.org/dc/terms/"<br />
xmlns:sword="http://purl.org/net/sword/terms/"<br />
xmlns:atom="http://www.w3.org/2005/Atom"<br />
xmlns="http://www.w3.org/2007/app"><br />
<br />
<sword:version>2.0</sword:version><br />
<br />
<workspace><br />
<atom:title>Archivematica storage service</atom:title><br />
<br />
<br />
<collection href="http://192.168.1.231:8000/api/v1/space/8f24ef5f-19d5-4b77-8a38-b30d034b11e7/sword/collection/"><br />
<atom:title>Collection</atom:title><br />
<accept>*/*</accept><br />
<accept alternate="multipart-related">*/*</accept><br />
<sword:mediation>false</sword:mediation><br />
</collection><br />
<br />
</workspace><br />
</service><br />
</pre><br />
<br />
=== List existing transfers ===<br />
* HTTP Get to the Collection IRI (defined by default as: /api/v1/space/[space UUID]/sword/collection/)<br />
* Transfers are listed as an Atom feed<br />
* Each Atom feed entry contains an "atom:link" element whose href attribute contains the URL needed to get details about the transfer<br />
* optional filters via get parameters (not yet implemented)<br />
<br />
Example response:<br />
<pre><br />
<atom:feed xmlns="http://www.w3.org/2005/Atom"><br />
<atom:id>http://192.168.1.231:8000/api/v1/space/8f24ef5f-19d5-4b77-8a38-b30d034b11e7/sword/collection/</atom:id><br />
<atom:title type="text">Deposits</atom:title><br />
<atom:link href="http://192.168.1.231:8000/api/v1/space/8f24ef5f-19d5-4b77-8a38-b30d034b11e7/sword/collection/" rel="self"><br />
</atom:link><br />
<atom:entry><br />
<atom:id>http://192.168.1.231:8000/api/v1/location/88e70cd2-9258-4a84-8938-16e74be032e6/sword/</atom:id><br />
<atom:title type="text">Cinderella</atom:title><br />
<atom:link href="http://192.168.1.231:8000/api/v1/location/88e70cd2-9258-4a84-8938-16e74be032e6/sword/" rel="self"><br />
</atom:link><br />
</atom:entry><br />
</atom:feed><br />
</pre><br />
<br />
=== Create a new transfer ===<br />
* used to start a new transfer in Archivematica<br />
* HTTP POST of an Atom Entry Document to the Collection IRI (defined by default as: /api/v1/space/[space UUID]/sword/collection/)<br />
<br />
'''Possible HTTP Response Codes'''<br />
* HTTP 200 OK - transfer already exists (not yet implemented)<br />
* HTTP 201 Created - transfer has been accepted<br />
* HTTP 412 Precondition Failed - required metadata missing or invalid<br />
<br />
Valid requests will receive a Sword Deposit Receipt in the body of the response.<br />
<br />
'''Required HTTP Headers'''<br />
The HTTP POST must include certain specific http headers. <br />
<br />
Required by http 1.1 specification:<br />
* Host: Must be set to archivematica host name.<br />
* Content-Length: Must be set to the length of the atom entry document.<br />
* Content-Type: Must be set to "application/atom+xml;type=entry".<br />
<br />
Required by Archivematica. <br />
* Authorization: Must include the api key and username assigned by Archivematica.<br />
<br />
Required by SWORD 2.0 protocol:<br />
* In-Progress: Must be set to "true"<br />
<br />
Optional in SWORD 2.0 protocol:<br />
* On-Behalf-Of: not implemented by Archivematica<br />
* Slug: not implemented by Archivematica<br />
<br />
'''Required in Body'''<br />
The Body of the request must be a valid METS Document. The required fields in an Atom Entry Document are:<br />
* LABEL: used as the transfer name<br />
* id: used as an accession id (not yet implemented)<br />
* author: used as the source of acquisition (not yet implemented)<br />
* summary: not implemented yet. Could be used in the future as a description for the Transfer<br />
* updated: should be set to the current timestamp. <br />
<br />
'''Example'''<br />
Example HTTP POST request:<br />
<pre><br />
POST /api/v1/space/96606387-cc70-4b09-b422-a7220606488d/sword/collection/ HTTP/1.1<br />
Host: localhost<br />
Authorization: Archivematica-API api_key="XXXXXXXXXXXXXXXXXXXX", username="timh"<br />
Content-Length: 213<br />
Content-Type: application/atom+xml;type=entry<br />
In-Progress: true<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<METS:mets EXT_VERSION="1.1" OBJID="islandora:72" LABEL="Cinderella"<br />
xmlns:METS="http://www.loc.gov/METS/"<br />
xmlns:xlink="http://www.w3.org/1999/xlink"<br />
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"<br />
xsi:schemaLocation="http://www.loc.gov/METS/ http://www.fedora.info/definitions/1/0/mets-fedora-ext1-1.xsd"><br />
<METS:fileSec><br />
<METS:fileGrp ID="DATASTREAMS"><br />
<METS:fileGrp ID="OBJ"><br />
<METS:file ID="OBJ.0"><br />
<METS:FLocat xlink:title="Cinderella_(1865).pdf" LOCTYPE="URL"<br />
xlink:href="http://localhost:8080/fedora/get/islandora:72/OBJ/2013-08-12T14:46:43.454Z" /><br />
</METS:file><br />
</METS:fileGrp><br />
</METS:fileGrp><br />
</METS:fileSec><br />
</METS:mets><br />
</pre><br />
<br />
Example Response:<br />
<pre><br />
201 Created<br />
Location: http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/<br />
<br />
<entry xmlns="http://www.w3.org/2005/Atom"<br />
xmlns:sword="http://purl.org/net/sword/"<br />
xmlns:dcterms="http://purl.org/dc/terms/"><br />
<br />
<title>Cinderella</title><br />
<id>91d4f258-0050-4914-9d0c-6a74815358d2</id><br />
<updated></updated><br />
<generator uri="https://www.archivematica.org" version="1.0"/><br />
<br />
<summary>A deposit was started.</summary><br />
<sword:treatment>A deposit directory was created and, optionally, asynchronous download of digital objects.</sword:treatment><br />
<br />
<link rel="alternate" href="http://www.swordserver.ac.uk/col1/mydeposit.html"/><br />
<link rel="edit-media" href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/media/"/><br />
<link rel="edit" href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/" /><br />
<link rel="http://purl.org/net/sword/terms/add" href="http://192.168.1.76:8000/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/" /><br />
<link rel="http://purl.org/net/sword/terms/statement" type="application/atom+xml;type=feed"<br />
href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/state/" /><br />
</entry><br />
</pre><br />
<br />
=== Add Files to a Transfer ===<br />
<br />
Posting file metadata (not yet implemented):<br />
* POST a METS file to the SE-IRI, listed below.<br />
* HTTP headers are required similar to Create Transfer call (above).<br />
* Body must include a valid Atom Entry document, that has METS embedded inside it.<br />
<br />
Posts file data:<br />
* It is possible to also POST the actual file to a deposit location's EM-IRI (/api/v1/location/[location UUID]/sword/media/)<br />
* The file should be posted as the request body and the filename specified using the Content-Disposition header (as per RFC 6266): for example "Content-Disposition: Attachment; filename=dog.jpg"<br />
* An MD5 checksum for an uploaded file can be provided via the Content-MD5 header (as per RFC 1544): for example "Content-MD5: Q2hlY2sgSW50ZWdyaXR5IQ=="<br />
* If only an Atom Entry Document is POST'ed, Archivematica will look for uri's in the file StructMap section of the METS file, and attempt to GET each file listed, to include in the Transfer. (not yet implemented)<br />
<br />
=== Finalize a Transfer ===<br />
* POST with no body to the SE-IRI<br />
* set In-Progress HTTP header to : false<br />
* This will tell Archivematica that no further content will be added or removed from the Transfer. <br />
* Archivematica will finish fetching any files that were added previously, and once they have all been downloaded, the Transfer will start through the Archivematica pipeline.<br />
<br />
'''Example'''<br />
<pre><br />
POST http://localhost/api/v1/location/55ce8053-113a-4954-8aa3-fc9771da0bda/sword/ HTTP/1.1<br />
Host: localhost<br />
Authorization: Archivematica-API api_key="XXXXXXXXXXXXXXXXXXXX", username="timh"<br />
Content-Length: 0<br />
Content-Type: application/atom+xml;type=entry<br />
In-Progress: false<br />
</pre><br />
<br />
The response will be HTTP 200/OK or 400/Error (400 if the Transfer was already finalized). If the transfer doesn't exist the response will be HTTP 404.<br />
<br />
=== Get Status of Transfer ===<br />
To check Status:<br />
<br />
GET the State-IRI<br />
in this example:<br />
<br />
GET http://localhost/api/v1/location/09224ddb-4c7d-404c-9218-2f2e1b5a599e/sword/state/ HTTP/1.1<br />
<br />
response will include:<br />
<pre><atom:feed xmlns:sword="http://purl.org/net/sword/terms/" <br />
xmlns:atom="http://www.w3.org/2005/Atom"><br />
<br />
<atom:category scheme="http://purl.org/net/sword/terms/state"<br />
term="failed"<br />
label="State"><br />
Deposit initiation: Failed<br />
</atom:category><br />
<br />
</atom:feed></pre><br />
the list of possible descriptions is not finalized.<br />
<br />
The state term value will either be "processing" (asynchronous deposit still working), "complete" (ready to be finalized), or "failed" (asynchronous deposit encountered an error).<br />
<br />
== Additional Details == <br />
<br />
=== Transfer Details ===<br />
* redirect to Edit-IRI<br />
* used to get basic info about a Transfer with HTTP GET<br />
* can update basic info using HTTP PUT (not yet implemented)<br />
* can allow deletion with HTTP DELETE<br />
* follows the form: /api/v1/location/[deposit location UUID]/sword/<br />
* example: http://192.168.1.231:8000/api/v1/location/09224ddb-4c7d-404c-9218-2f2e1b5a599e/sword/<br />
<br />
=== EM-IRI ===<br />
* Edit-Media IRI <br />
* used to add new objects to an existing transfer<br />
* follows the form: [archivematica hostname]/api/v2/transfer/[uuid of transfer]/media<br />
* example: /api/v1/location/[deposit location UUID]/sword/media/<br />
<br />
An HTTP POST to the em-iri for a transfer should include a file as the body<br />
<br />
An HTTP GET should return a list of files in the transfer<br />
<br />
An HTTP DELETE to the em-iri will remove all digital objects from the Transfer. This is a valid operation only while the Transfer is being assembled. Once the Transfer has been finalized, attempting to DELETE will return an error.<br />
<br />
=== Edit-IRI ===<br />
The client can replace the metadata of a resource by performing an HTTP PUT of a new Atom Entry on the Edit-IRI. (not yet implemented)<br />
<br />
This would be used to update metadata about a transfer, such as the transfer name.<br />
<br />
* example: http://localhost/api/v2/transfer/1225c695-cfb8-4ebb-aaaa-80da344efa6a/edit<br />
<br />
=== SE-IRI ===<br />
* example: http://localhost/api/v2/transfer/add/1225c695-cfb8-4ebb-aaaa-80da344efa6a (not yet implemented)<br />
<br />
=== State-IRI ===<br />
* used to retrieve status of transfer<br />
* implemented as Atom document<br />
* example: /api/v1/location/[deposit location UUID]/sword/state/<br />
* should be able to subscribe like RSS feed<br />
<br />
=== Service document ===</div>Mcantelonhttps://wiki.archivematica.org/index.php?title=Sword_API&diff=9337Sword API2014-01-11T00:09:55Z<p>Mcantelon: /* List existing transfers */</p>
<hr />
<div><br />
== Overview ==<br />
<br />
One of the 1.1 release features is a sponsored project to integrate Archivematica with Islandora. This integration will be accomplished by creating a [http://swordapp.org Sword] 2.0 API for the Archivematica [https://www.archivematica.org/wiki/Administrator_manual_1.0#Storage_service storage service]. Islandora development work will add functionality to Islandora to use this API to deposit digital objects into Archviematica.<br />
<br />
As described [[Overview|elsewhere]] on this wiki, ''"the primary function of Archivematica is to process digital transfers (accessioned digital objects), turn them into SIPs, apply format policies and create high-quality, repository-independent Archival Information Packages (AIP)"''.<br />
<br />
The Archivematica Sword API allows 3rd party applications to automate the process of creating Transfers. <br />
#Create Transfer - set the name and other metadata about a Transfer<br />
#Populate Transfer - add/edit/update digital objects in a Transfer, and associated metadata<br />
#Finalize Transfer - indicates that the Transfer is ready to start processing.<br />
<br />
After content has been deposited, if users have access to the deposit directory they can also manually manipulate the deposit directory aside from any manipulation using the API.<br />
<br />
Once a Transfer has been created, populated and finalized, Archivematica will begin processing that Transfer.<br />
<br />
== Configuration ==<br />
<br />
The SWORD API is part of the Archivematica storage service REST API. The storage service also talks to the Archivematica dashboard, however, to notify it that a, transfer created from a SWORD deposit, has been approved for processing.<br />
<br />
To use the SWORD API you must install the Archivematica dashboard 1.0 branch and the Archivematica storage service dev/issue-5980-islandora branch.<br />
<br />
Dashboard configuration:<br />
<br />
# In dashboard REST API administration, add the IP of the storage service server to IP whitelist<br />
# In dashboard user administration, take note of username and API key for a dashboard user (example: user "demo" and API key "4e5f32ab2aefd3543e1b19a2de554dd65f90108a")<br />
# In dashboard general admininstration, take note of the dashboard's UUID<br />
<br />
Storage service configuration:<br />
<br />
# In the storage service web interface's Pipelines tab, find the dashboard pipeline (using dashboard's UUID noted during dashboard configuration)<br />
# Enter the dashboard's IP address into the "Remote name" field and the user and API key noted earlier into the "Api username" and "Api key" fields. Click the button to submit these changes.<br />
<br />
After configuration you'll need to find the space UUID of the SWORD server. To do so, in the web interface's Spaces tab, click "View Details and Locations" for the SWORD server. The UUID will be shown at the top of the screen. The UUID is used to figure out the initial API URL to access (for example: "http://localhost:8000/api/v1/space/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/").<br />
<br />
== Example session ==<br />
<br />
Below is an example session using curl to manipulate the API. In the example a deposit is created, a file is added to it, and it is finalized.<br />
<br />
NOTE: The SWORD API is in the process of being moved to the storage service. These URLs may not work.<br />
<br />
<pre># create new deposit<br />
curl -v -H "In-Progress: true" --data-binary @mets.xml --request POST http://localhost:8000/api/v1/space/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/<br />
# response XML includes endpoints for adding additional files, etc.<br />
<br />
# add a file to the deposit<br />
curl -v -H "Content-Disposition: attachment; filename=mets.xml" --request POST \<br />
--data-binary "@mets.xml" \<br />
http://127.0.0.1:8000/api/v1/location/9c8b4ac0-0407-4360-a10d-af6c62a48b69/sword/media/<br />
<br />
# finalize transfer and approve processing<br />
curl -v -H "In-Progress: false" --request POST http://127.0.0.1:8000/api/v1/location/149cc29d-6472-4bcf-bee8-f8223bf60580/sword/<br />
</pre><br />
<br />
You might, at some point, want to list the transfers that have been started. The following curl command will do so.<br />
<br />
<pre>curl -v http://localhost:8000/api/v1/space/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/</pre><br />
<br />
If you're working on a transfer and want to list what files are included in it, the following curl command will list them.<br />
<br />
<pre># list files in transfer<br />
curl -v http://127.0.0.1:8000/api/v1/location/9c8b4ac0-0407-4360-a10d-af6c62a48b69/sword/media/</pre><br />
<br />
If you've started a deposit, but want to discard it, you can delete the deposit. The following curl command shows an example.<br />
<br />
<pre>curl -v -XDELETE http://127.0.0.1:8000/api/v1/location/149cc29d-6472-4bcf-bee8-f8223bf60580/sword/</pre><br />
<br />
== Synchronous Deposit Examples ==<br />
<br />
If you wanted to deposit a transfer then immediately finalize it you could use something like the following curl command.<br />
<br />
<pre>curl -v -H "In-Progress: false" --data-binary @mets.xml --request POST http://localhost:8000/api/v1/space/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/</pre><br />
<br />
<br />
== Endpoints ==<br />
<br />
=== Service document ===<br />
<br />
The SWORD service document provides information about the SWORD provider's capacities and lists SWORD collections. Archivematica currently includes one SWORD collection to which SWORD deposits can be made: transfers.<br />
<br />
The SWORD service document endpoint is located at /api/v1/sword/.<br />
<br />
Service document example:<br />
<pre><br />
<service xmlns:dcterms="http://purl.org/dc/terms/"<br />
xmlns:sword="http://purl.org/net/sword/terms/"<br />
xmlns:atom="http://www.w3.org/2005/Atom"<br />
xmlns="http://www.w3.org/2007/app"><br />
<br />
<sword:version>2.0</sword:version><br />
<br />
<workspace><br />
<atom:title>Archivematica storage service</atom:title><br />
<br />
<br />
<collection href="http://192.168.1.231:8000/api/v1/space/8f24ef5f-19d5-4b77-8a38-b30d034b11e7/sword/collection/"><br />
<atom:title>Collection</atom:title><br />
<accept>*/*</accept><br />
<accept alternate="multipart-related">*/*</accept><br />
<sword:mediation>false</sword:mediation><br />
</collection><br />
<br />
</workspace><br />
</service><br />
</pre><br />
<br />
=== List existing transfers ===<br />
* HTTP Get to the Collection IRI (defined by default as: /api/v1/space/[space UUID]/sword/collection/)<br />
* Transfers are listed as an Atom feed<br />
* Each Atom feed entry contains an "atom:link" element whose href attribute contains the URL needed to get details about the transfer<br />
* optional filters via get parameters (not yet implemented)<br />
<br />
Example: response<br />
<pre><br />
<atom:feed xmlns="http://www.w3.org/2005/Atom"><br />
<atom:id>http://192.168.1.231:8000/api/v1/space/8f24ef5f-19d5-4b77-8a38-b30d034b11e7/sword/collection/</atom:id><br />
<atom:title type="text">Deposits</atom:title><br />
<atom:link href="http://192.168.1.231:8000/api/v1/space/8f24ef5f-19d5-4b77-8a38-b30d034b11e7/sword/collection/" rel="self"><br />
</atom:link><br />
<atom:entry><br />
<atom:id>http://192.168.1.231:8000/api/v1/location/88e70cd2-9258-4a84-8938-16e74be032e6/sword/</atom:id><br />
<atom:title type="text">Cinderella</atom:title><br />
<atom:link href="http://192.168.1.231:8000/api/v1/location/88e70cd2-9258-4a84-8938-16e74be032e6/sword/" rel="self"><br />
</atom:link><br />
</atom:entry><br />
</atom:feed><br />
</pre><br />
<br />
=== Create a new transfer ===<br />
* used to start a new transfer in Archivematica<br />
* HTTP POST of an Atom Entry Document to the Collection IRI (defined by default as: /api/v1/space/[space UUID]/sword/collection/)<br />
<br />
'''Possible HTTP Response Codes'''<br />
* HTTP 200 OK - transfer already exists (not yet implemented)<br />
* HTTP 201 Created - transfer has been accepted<br />
* HTTP 412 Precondition Failed - required metadata missing or invalid<br />
<br />
Valid requests will receive a Sword Deposit Receipt in the body of the response.<br />
<br />
'''Required HTTP Headers'''<br />
The HTTP POST must include certain specific http headers. <br />
<br />
Required by http 1.1 specification:<br />
* Host: Must be set to archivematica host name.<br />
* Content-Length: Must be set to the length of the atom entry document.<br />
* Content-Type: Must be set to "application/atom+xml;type=entry".<br />
<br />
Required by Archivematica. <br />
* Authorization: Must include the api key and username assigned by Archivematica.<br />
<br />
Required by SWORD 2.0 protocol:<br />
* In-Progress: Must be set to "true"<br />
<br />
Optional in SWORD 2.0 protocol:<br />
* On-Behalf-Of: not implemented by Archivematica<br />
* Slug: not implemented by Archivematica<br />
<br />
'''Required in Body'''<br />
The Body of the request must be a valid METS Document. The required fields in an Atom Entry Document are:<br />
* LABEL: used as the transfer name<br />
* id: used as an accession id (not yet implemented)<br />
* author: used as the source of acquisition (not yet implemented)<br />
* summary: not implemented yet. Could be used in the future as a description for the Transfer<br />
* updated: should be set to the current timestamp. <br />
<br />
'''Example'''<br />
Example HTTP POST request:<br />
<pre><br />
POST /api/v1/space/96606387-cc70-4b09-b422-a7220606488d/sword/collection/ HTTP/1.1<br />
Host: localhost<br />
Authorization: Archivematica-API api_key="XXXXXXXXXXXXXXXXXXXX", username="timh"<br />
Content-Length: 213<br />
Content-Type: application/atom+xml;type=entry<br />
In-Progress: true<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<METS:mets EXT_VERSION="1.1" OBJID="islandora:72" LABEL="Cinderella"<br />
xmlns:METS="http://www.loc.gov/METS/"<br />
xmlns:xlink="http://www.w3.org/1999/xlink"<br />
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"<br />
xsi:schemaLocation="http://www.loc.gov/METS/ http://www.fedora.info/definitions/1/0/mets-fedora-ext1-1.xsd"><br />
<METS:fileSec><br />
<METS:fileGrp ID="DATASTREAMS"><br />
<METS:fileGrp ID="OBJ"><br />
<METS:file ID="OBJ.0"><br />
<METS:FLocat xlink:title="Cinderella_(1865).pdf" LOCTYPE="URL"<br />
xlink:href="http://localhost:8080/fedora/get/islandora:72/OBJ/2013-08-12T14:46:43.454Z" /><br />
</METS:file><br />
</METS:fileGrp><br />
</METS:fileGrp><br />
</METS:fileSec><br />
</METS:mets><br />
</pre><br />
<br />
Example Response:<br />
<pre><br />
201 Created<br />
Location: http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/<br />
<br />
<entry xmlns="http://www.w3.org/2005/Atom"<br />
xmlns:sword="http://purl.org/net/sword/"<br />
xmlns:dcterms="http://purl.org/dc/terms/"><br />
<br />
<title>Cinderella</title><br />
<id>91d4f258-0050-4914-9d0c-6a74815358d2</id><br />
<updated></updated><br />
<generator uri="https://www.archivematica.org" version="1.0"/><br />
<br />
<summary>A deposit was started.</summary><br />
<sword:treatment>A deposit directory was created and, optionally, asynchronous download of digital objects.</sword:treatment><br />
<br />
<link rel="alternate" href="http://www.swordserver.ac.uk/col1/mydeposit.html"/><br />
<link rel="edit-media" href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/media/"/><br />
<link rel="edit" href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/" /><br />
<link rel="http://purl.org/net/sword/terms/add" href="http://192.168.1.76:8000/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/" /><br />
<link rel="http://purl.org/net/sword/terms/statement" type="application/atom+xml;type=feed"<br />
href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/state/" /><br />
</entry><br />
</pre><br />
<br />
=== Add Files to a Transfer ===<br />
<br />
Posting file metadata (not yet implemented):<br />
* POST a METS file to the SE-IRI, listed below.<br />
* HTTP headers are required similar to Create Transfer call (above).<br />
* Body must include a valid Atom Entry document, that has METS embedded inside it.<br />
<br />
Posts file data:<br />
* It is possible to also POST the actual file to a deposit location's EM-IRI (/api/v1/location/[location UUID]/sword/media/)<br />
* The file should be posted as the request body and the filename specified using the Content-Disposition header (as per RFC 6266): for example "Content-Disposition: Attachment; filename=dog.jpg"<br />
* An MD5 checksum for an uploaded file can be provided via the Content-MD5 header (as per RFC 1544): for example "Content-MD5: Q2hlY2sgSW50ZWdyaXR5IQ=="<br />
* If only an Atom Entry Document is POST'ed, Archivematica will look for uri's in the file StructMap section of the METS file, and attempt to GET each file listed, to include in the Transfer. (not yet implemented)<br />
<br />
=== Finalize a Transfer ===<br />
* POST with no body to the SE-IRI<br />
* set In-Progress HTTP header to : false<br />
* This will tell Archivematica that no further content will be added or removed from the Transfer. <br />
* Archivematica will finish fetching any files that were added previously, and once they have all been downloaded, the Transfer will start through the Archivematica pipeline.<br />
<br />
'''Example'''<br />
<pre><br />
POST http://localhost/api/v1/location/55ce8053-113a-4954-8aa3-fc9771da0bda/sword/ HTTP/1.1<br />
Host: localhost<br />
Authorization: Archivematica-API api_key="XXXXXXXXXXXXXXXXXXXX", username="timh"<br />
Content-Length: 0<br />
Content-Type: application/atom+xml;type=entry<br />
In-Progress: false<br />
</pre><br />
<br />
The response will be HTTP 200/OK or 400/Error (400 if the Transfer was already finalized). If the transfer doesn't exist the response will be HTTP 404.<br />
<br />
=== Get Status of Transfer ===<br />
To check Status:<br />
<br />
GET the State-IRI<br />
in this example:<br />
<br />
GET http://localhost/api/v1/location/09224ddb-4c7d-404c-9218-2f2e1b5a599e/sword/state/ HTTP/1.1<br />
<br />
response will include:<br />
<pre><atom:feed xmlns:sword="http://purl.org/net/sword/terms/" <br />
xmlns:atom="http://www.w3.org/2005/Atom"><br />
<br />
<atom:category scheme="http://purl.org/net/sword/terms/state"<br />
term="failed"<br />
label="State"><br />
Deposit initiation: Failed<br />
</atom:category><br />
<br />
</atom:feed></pre><br />
the list of possible descriptions is not finalized.<br />
<br />
The state term value will either be "processing" (asynchronous deposit still working), "complete" (ready to be finalized), or "failed" (asynchronous deposit encountered an error).<br />
<br />
== Additional Details == <br />
<br />
=== Transfer Details ===<br />
* redirect to Edit-IRI<br />
* used to get basic info about a Transfer with HTTP GET<br />
* can update basic info using HTTP PUT (not yet implemented)<br />
* can allow deletion with HTTP DELETE<br />
* follows the form: /api/v1/location/[deposit location UUID]/sword/<br />
* example: http://192.168.1.231:8000/api/v1/location/09224ddb-4c7d-404c-9218-2f2e1b5a599e/sword/<br />
<br />
=== EM-IRI ===<br />
* Edit-Media IRI <br />
* used to add new objects to an existing transfer<br />
* follows the form: [archivematica hostname]/api/v2/transfer/[uuid of transfer]/media<br />
* example: /api/v1/location/[deposit location UUID]/sword/media/<br />
<br />
An HTTP POST to the em-iri for a transfer should include a file as the body<br />
<br />
An HTTP GET should return a list of files in the transfer<br />
<br />
An HTTP DELETE to the em-iri will remove all digital objects from the Transfer. This is a valid operation only while the Transfer is being assembled. Once the Transfer has been finalized, attempting to DELETE will return an error.<br />
<br />
=== Edit-IRI ===<br />
The client can replace the metadata of a resource by performing an HTTP PUT of a new Atom Entry on the Edit-IRI. (not yet implemented)<br />
<br />
This would be used to update metadata about a transfer, such as the transfer name.<br />
<br />
* example: http://localhost/api/v2/transfer/1225c695-cfb8-4ebb-aaaa-80da344efa6a/edit<br />
<br />
=== SE-IRI ===<br />
* example: http://localhost/api/v2/transfer/add/1225c695-cfb8-4ebb-aaaa-80da344efa6a (not yet implemented)<br />
<br />
=== State-IRI ===<br />
* used to retrieve status of transfer<br />
* implemented as Atom document<br />
* example: /api/v1/location/[deposit location UUID]/sword/state/<br />
* should be able to subscribe like RSS feed<br />
<br />
=== Service document ===</div>Mcantelonhttps://wiki.archivematica.org/index.php?title=Sword_API&diff=9336Sword API2014-01-11T00:09:11Z<p>Mcantelon: /* List existing transfers */</p>
<hr />
<div><br />
== Overview ==<br />
<br />
One of the 1.1 release features is a sponsored project to integrate Archivematica with Islandora. This integration will be accomplished by creating a [http://swordapp.org Sword] 2.0 API for the Archivematica [https://www.archivematica.org/wiki/Administrator_manual_1.0#Storage_service storage service]. Islandora development work will add functionality to Islandora to use this API to deposit digital objects into Archviematica.<br />
<br />
As described [[Overview|elsewhere]] on this wiki, ''"the primary function of Archivematica is to process digital transfers (accessioned digital objects), turn them into SIPs, apply format policies and create high-quality, repository-independent Archival Information Packages (AIP)"''.<br />
<br />
The Archivematica Sword API allows 3rd party applications to automate the process of creating Transfers. <br />
#Create Transfer - set the name and other metadata about a Transfer<br />
#Populate Transfer - add/edit/update digital objects in a Transfer, and associated metadata<br />
#Finalize Transfer - indicates that the Transfer is ready to start processing.<br />
<br />
After content has been deposited, if users have access to the deposit directory they can also manually manipulate the deposit directory aside from any manipulation using the API.<br />
<br />
Once a Transfer has been created, populated and finalized, Archivematica will begin processing that Transfer.<br />
<br />
== Configuration ==<br />
<br />
The SWORD API is part of the Archivematica storage service REST API. The storage service also talks to the Archivematica dashboard, however, to notify it that a, transfer created from a SWORD deposit, has been approved for processing.<br />
<br />
To use the SWORD API you must install the Archivematica dashboard 1.0 branch and the Archivematica storage service dev/issue-5980-islandora branch.<br />
<br />
Dashboard configuration:<br />
<br />
# In dashboard REST API administration, add the IP of the storage service server to IP whitelist<br />
# In dashboard user administration, take note of username and API key for a dashboard user (example: user "demo" and API key "4e5f32ab2aefd3543e1b19a2de554dd65f90108a")<br />
# In dashboard general admininstration, take note of the dashboard's UUID<br />
<br />
Storage service configuration:<br />
<br />
# In the storage service web interface's Pipelines tab, find the dashboard pipeline (using dashboard's UUID noted during dashboard configuration)<br />
# Enter the dashboard's IP address into the "Remote name" field and the user and API key noted earlier into the "Api username" and "Api key" fields. Click the button to submit these changes.<br />
<br />
After configuration you'll need to find the space UUID of the SWORD server. To do so, in the web interface's Spaces tab, click "View Details and Locations" for the SWORD server. The UUID will be shown at the top of the screen. The UUID is used to figure out the initial API URL to access (for example: "http://localhost:8000/api/v1/space/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/").<br />
<br />
== Example session ==<br />
<br />
Below is an example session using curl to manipulate the API. In the example a deposit is created, a file is added to it, and it is finalized.<br />
<br />
NOTE: The SWORD API is in the process of being moved to the storage service. These URLs may not work.<br />
<br />
<pre># create new deposit<br />
curl -v -H "In-Progress: true" --data-binary @mets.xml --request POST http://localhost:8000/api/v1/space/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/<br />
# response XML includes endpoints for adding additional files, etc.<br />
<br />
# add a file to the deposit<br />
curl -v -H "Content-Disposition: attachment; filename=mets.xml" --request POST \<br />
--data-binary "@mets.xml" \<br />
http://127.0.0.1:8000/api/v1/location/9c8b4ac0-0407-4360-a10d-af6c62a48b69/sword/media/<br />
<br />
# finalize transfer and approve processing<br />
curl -v -H "In-Progress: false" --request POST http://127.0.0.1:8000/api/v1/location/149cc29d-6472-4bcf-bee8-f8223bf60580/sword/<br />
</pre><br />
<br />
You might, at some point, want to list the transfers that have been started. The following curl command will do so.<br />
<br />
<pre>curl -v http://localhost:8000/api/v1/space/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/</pre><br />
<br />
If you're working on a transfer and want to list what files are included in it, the following curl command will list them.<br />
<br />
<pre># list files in transfer<br />
curl -v http://127.0.0.1:8000/api/v1/location/9c8b4ac0-0407-4360-a10d-af6c62a48b69/sword/media/</pre><br />
<br />
If you've started a deposit, but want to discard it, you can delete the deposit. The following curl command shows an example.<br />
<br />
<pre>curl -v -XDELETE http://127.0.0.1:8000/api/v1/location/149cc29d-6472-4bcf-bee8-f8223bf60580/sword/</pre><br />
<br />
== Synchronous Deposit Examples ==<br />
<br />
If you wanted to deposit a transfer then immediately finalize it you could use something like the following curl command.<br />
<br />
<pre>curl -v -H "In-Progress: false" --data-binary @mets.xml --request POST http://localhost:8000/api/v1/space/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/</pre><br />
<br />
<br />
== Endpoints ==<br />
<br />
=== Service document ===<br />
<br />
The SWORD service document provides information about the SWORD provider's capacities and lists SWORD collections. Archivematica currently includes one SWORD collection to which SWORD deposits can be made: transfers.<br />
<br />
The SWORD service document endpoint is located at /api/v1/sword/.<br />
<br />
Service document example:<br />
<pre><br />
<service xmlns:dcterms="http://purl.org/dc/terms/"<br />
xmlns:sword="http://purl.org/net/sword/terms/"<br />
xmlns:atom="http://www.w3.org/2005/Atom"<br />
xmlns="http://www.w3.org/2007/app"><br />
<br />
<sword:version>2.0</sword:version><br />
<br />
<workspace><br />
<atom:title>Archivematica storage service</atom:title><br />
<br />
<br />
<collection href="http://192.168.1.231:8000/api/v1/space/8f24ef5f-19d5-4b77-8a38-b30d034b11e7/sword/collection/"><br />
<atom:title>Collection</atom:title><br />
<accept>*/*</accept><br />
<accept alternate="multipart-related">*/*</accept><br />
<sword:mediation>false</sword:mediation><br />
</collection><br />
<br />
</workspace><br />
</service><br />
</pre><br />
<br />
=== List existing transfers ===<br />
* HTTP Get to the Collection IRI (defined by default as: /api/v1/space/[space UUID]/sword/collection/)<br />
* Transfers are listed as an Atom feed<br />
* Each Atom feed entry contains an "atom:link" element whose href attribute contains the URL needed to get details about the transfer<br />
* optional filters via get parameters (not yet implemented)<br />
<br />
Example: response<br />
<atom:feed xmlns="http://www.w3.org/2005/Atom"><br />
<atom:id>http://192.168.1.231:8000/api/v1/space/8f24ef5f-19d5-4b77-8a38-b30d034b11e7/sword/collection/</atom:id><br />
<atom:title type="text">Deposits</atom:title><br />
<atom:link href="http://192.168.1.231:8000/api/v1/space/8f24ef5f-19d5-4b77-8a38-b30d034b11e7/sword/collection/" rel="self"><br />
</atom:link><br />
<atom:entry><br />
<atom:id>http://192.168.1.231:8000/api/v1/location/88e70cd2-9258-4a84-8938-16e74be032e6/sword/</atom:id><br />
<atom:title type="text">Cinderella</atom:title><br />
<atom:link href="http://192.168.1.231:8000/api/v1/location/88e70cd2-9258-4a84-8938-16e74be032e6/sword/" rel="self"><br />
</atom:link><br />
</atom:entry><br />
</atom:feed><br />
</pre><br />
<br />
=== Create a new transfer ===<br />
* used to start a new transfer in Archivematica<br />
* HTTP POST of an Atom Entry Document to the Collection IRI (defined by default as: /api/v1/space/[space UUID]/sword/collection/)<br />
<br />
'''Possible HTTP Response Codes'''<br />
* HTTP 200 OK - transfer already exists (not yet implemented)<br />
* HTTP 201 Created - transfer has been accepted<br />
* HTTP 412 Precondition Failed - required metadata missing or invalid<br />
<br />
Valid requests will receive a Sword Deposit Receipt in the body of the response.<br />
<br />
'''Required HTTP Headers'''<br />
The HTTP POST must include certain specific http headers. <br />
<br />
Required by http 1.1 specification:<br />
* Host: Must be set to archivematica host name.<br />
* Content-Length: Must be set to the length of the atom entry document.<br />
* Content-Type: Must be set to "application/atom+xml;type=entry".<br />
<br />
Required by Archivematica. <br />
* Authorization: Must include the api key and username assigned by Archivematica.<br />
<br />
Required by SWORD 2.0 protocol:<br />
* In-Progress: Must be set to "true"<br />
<br />
Optional in SWORD 2.0 protocol:<br />
* On-Behalf-Of: not implemented by Archivematica<br />
* Slug: not implemented by Archivematica<br />
<br />
'''Required in Body'''<br />
The Body of the request must be a valid METS Document. The required fields in an Atom Entry Document are:<br />
* LABEL: used as the transfer name<br />
* id: used as an accession id (not yet implemented)<br />
* author: used as the source of acquisition (not yet implemented)<br />
* summary: not implemented yet. Could be used in the future as a description for the Transfer<br />
* updated: should be set to the current timestamp. <br />
<br />
'''Example'''<br />
Example HTTP POST request:<br />
<pre><br />
POST /api/v1/space/96606387-cc70-4b09-b422-a7220606488d/sword/collection/ HTTP/1.1<br />
Host: localhost<br />
Authorization: Archivematica-API api_key="XXXXXXXXXXXXXXXXXXXX", username="timh"<br />
Content-Length: 213<br />
Content-Type: application/atom+xml;type=entry<br />
In-Progress: true<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<METS:mets EXT_VERSION="1.1" OBJID="islandora:72" LABEL="Cinderella"<br />
xmlns:METS="http://www.loc.gov/METS/"<br />
xmlns:xlink="http://www.w3.org/1999/xlink"<br />
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"<br />
xsi:schemaLocation="http://www.loc.gov/METS/ http://www.fedora.info/definitions/1/0/mets-fedora-ext1-1.xsd"><br />
<METS:fileSec><br />
<METS:fileGrp ID="DATASTREAMS"><br />
<METS:fileGrp ID="OBJ"><br />
<METS:file ID="OBJ.0"><br />
<METS:FLocat xlink:title="Cinderella_(1865).pdf" LOCTYPE="URL"<br />
xlink:href="http://localhost:8080/fedora/get/islandora:72/OBJ/2013-08-12T14:46:43.454Z" /><br />
</METS:file><br />
</METS:fileGrp><br />
</METS:fileGrp><br />
</METS:fileSec><br />
</METS:mets><br />
</pre><br />
<br />
Example Response:<br />
<pre><br />
201 Created<br />
Location: http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/<br />
<br />
<entry xmlns="http://www.w3.org/2005/Atom"<br />
xmlns:sword="http://purl.org/net/sword/"<br />
xmlns:dcterms="http://purl.org/dc/terms/"><br />
<br />
<title>Cinderella</title><br />
<id>91d4f258-0050-4914-9d0c-6a74815358d2</id><br />
<updated></updated><br />
<generator uri="https://www.archivematica.org" version="1.0"/><br />
<br />
<summary>A deposit was started.</summary><br />
<sword:treatment>A deposit directory was created and, optionally, asynchronous download of digital objects.</sword:treatment><br />
<br />
<link rel="alternate" href="http://www.swordserver.ac.uk/col1/mydeposit.html"/><br />
<link rel="edit-media" href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/media/"/><br />
<link rel="edit" href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/" /><br />
<link rel="http://purl.org/net/sword/terms/add" href="http://192.168.1.76:8000/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/" /><br />
<link rel="http://purl.org/net/sword/terms/statement" type="application/atom+xml;type=feed"<br />
href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/state/" /><br />
</entry><br />
</pre><br />
<br />
=== Add Files to a Transfer ===<br />
<br />
Posting file metadata (not yet implemented):<br />
* POST a METS file to the SE-IRI, listed below.<br />
* HTTP headers are required similar to Create Transfer call (above).<br />
* Body must include a valid Atom Entry document, that has METS embedded inside it.<br />
<br />
Posts file data:<br />
* It is possible to also POST the actual file to a deposit location's EM-IRI (/api/v1/location/[location UUID]/sword/media/)<br />
* The file should be posted as the request body and the filename specified using the Content-Disposition header (as per RFC 6266): for example "Content-Disposition: Attachment; filename=dog.jpg"<br />
* An MD5 checksum for an uploaded file can be provided via the Content-MD5 header (as per RFC 1544): for example "Content-MD5: Q2hlY2sgSW50ZWdyaXR5IQ=="<br />
* If only an Atom Entry Document is POST'ed, Archivematica will look for uri's in the file StructMap section of the METS file, and attempt to GET each file listed, to include in the Transfer. (not yet implemented)<br />
<br />
=== Finalize a Transfer ===<br />
* POST with no body to the SE-IRI<br />
* set In-Progress HTTP header to : false<br />
* This will tell Archivematica that no further content will be added or removed from the Transfer. <br />
* Archivematica will finish fetching any files that were added previously, and once they have all been downloaded, the Transfer will start through the Archivematica pipeline.<br />
<br />
'''Example'''<br />
<pre><br />
POST http://localhost/api/v1/location/55ce8053-113a-4954-8aa3-fc9771da0bda/sword/ HTTP/1.1<br />
Host: localhost<br />
Authorization: Archivematica-API api_key="XXXXXXXXXXXXXXXXXXXX", username="timh"<br />
Content-Length: 0<br />
Content-Type: application/atom+xml;type=entry<br />
In-Progress: false<br />
</pre><br />
<br />
The response will be HTTP 200/OK or 400/Error (400 if the Transfer was already finalized). If the transfer doesn't exist the response will be HTTP 404.<br />
<br />
=== Get Status of Transfer ===<br />
To check Status:<br />
<br />
GET the State-IRI<br />
in this example:<br />
<br />
GET http://localhost/api/v1/location/09224ddb-4c7d-404c-9218-2f2e1b5a599e/sword/state/ HTTP/1.1<br />
<br />
response will include:<br />
<pre><atom:feed xmlns:sword="http://purl.org/net/sword/terms/" <br />
xmlns:atom="http://www.w3.org/2005/Atom"><br />
<br />
<atom:category scheme="http://purl.org/net/sword/terms/state"<br />
term="failed"<br />
label="State"><br />
Deposit initiation: Failed<br />
</atom:category><br />
<br />
</atom:feed></pre><br />
the list of possible descriptions is not finalized.<br />
<br />
The state term value will either be "processing" (asynchronous deposit still working), "complete" (ready to be finalized), or "failed" (asynchronous deposit encountered an error).<br />
<br />
== Additional Details == <br />
<br />
=== Transfer Details ===<br />
* redirect to Edit-IRI<br />
* used to get basic info about a Transfer with HTTP GET<br />
* can update basic info using HTTP PUT (not yet implemented)<br />
* can allow deletion with HTTP DELETE<br />
* follows the form: /api/v1/location/[deposit location UUID]/sword/<br />
* example: http://192.168.1.231:8000/api/v1/location/09224ddb-4c7d-404c-9218-2f2e1b5a599e/sword/<br />
<br />
=== EM-IRI ===<br />
* Edit-Media IRI <br />
* used to add new objects to an existing transfer<br />
* follows the form: [archivematica hostname]/api/v2/transfer/[uuid of transfer]/media<br />
* example: /api/v1/location/[deposit location UUID]/sword/media/<br />
<br />
An HTTP POST to the em-iri for a transfer should include a file as the body<br />
<br />
An HTTP GET should return a list of files in the transfer<br />
<br />
An HTTP DELETE to the em-iri will remove all digital objects from the Transfer. This is a valid operation only while the Transfer is being assembled. Once the Transfer has been finalized, attempting to DELETE will return an error.<br />
<br />
=== Edit-IRI ===<br />
The client can replace the metadata of a resource by performing an HTTP PUT of a new Atom Entry on the Edit-IRI. (not yet implemented)<br />
<br />
This would be used to update metadata about a transfer, such as the transfer name.<br />
<br />
* example: http://localhost/api/v2/transfer/1225c695-cfb8-4ebb-aaaa-80da344efa6a/edit<br />
<br />
=== SE-IRI ===<br />
* example: http://localhost/api/v2/transfer/add/1225c695-cfb8-4ebb-aaaa-80da344efa6a (not yet implemented)<br />
<br />
=== State-IRI ===<br />
* used to retrieve status of transfer<br />
* implemented as Atom document<br />
* example: /api/v1/location/[deposit location UUID]/sword/state/<br />
* should be able to subscribe like RSS feed<br />
<br />
=== Service document ===</div>Mcantelonhttps://wiki.archivematica.org/index.php?title=Sword_API&diff=9334Sword API2014-01-11T00:02:45Z<p>Mcantelon: /* Service document */</p>
<hr />
<div><br />
== Overview ==<br />
<br />
One of the 1.1 release features is a sponsored project to integrate Archivematica with Islandora. This integration will be accomplished by creating a [http://swordapp.org Sword] 2.0 API for the Archivematica [https://www.archivematica.org/wiki/Administrator_manual_1.0#Storage_service storage service]. Islandora development work will add functionality to Islandora to use this API to deposit digital objects into Archviematica.<br />
<br />
As described [[Overview|elsewhere]] on this wiki, ''"the primary function of Archivematica is to process digital transfers (accessioned digital objects), turn them into SIPs, apply format policies and create high-quality, repository-independent Archival Information Packages (AIP)"''.<br />
<br />
The Archivematica Sword API allows 3rd party applications to automate the process of creating Transfers. <br />
#Create Transfer - set the name and other metadata about a Transfer<br />
#Populate Transfer - add/edit/update digital objects in a Transfer, and associated metadata<br />
#Finalize Transfer - indicates that the Transfer is ready to start processing.<br />
<br />
After content has been deposited, if users have access to the deposit directory they can also manually manipulate the deposit directory aside from any manipulation using the API.<br />
<br />
Once a Transfer has been created, populated and finalized, Archivematica will begin processing that Transfer.<br />
<br />
== Configuration ==<br />
<br />
The SWORD API is part of the Archivematica storage service REST API. The storage service also talks to the Archivematica dashboard, however, to notify it that a, transfer created from a SWORD deposit, has been approved for processing.<br />
<br />
To use the SWORD API you must install the Archivematica dashboard 1.0 branch and the Archivematica storage service dev/issue-5980-islandora branch.<br />
<br />
Dashboard configuration:<br />
<br />
# In dashboard REST API administration, add the IP of the storage service server to IP whitelist<br />
# In dashboard user administration, take note of username and API key for a dashboard user (example: user "demo" and API key "4e5f32ab2aefd3543e1b19a2de554dd65f90108a")<br />
# In dashboard general admininstration, take note of the dashboard's UUID<br />
<br />
Storage service configuration:<br />
<br />
# In the storage service web interface's Pipelines tab, find the dashboard pipeline (using dashboard's UUID noted during dashboard configuration)<br />
# Enter the dashboard's IP address into the "Remote name" field and the user and API key noted earlier into the "Api username" and "Api key" fields. Click the button to submit these changes.<br />
<br />
After configuration you'll need to find the space UUID of the SWORD server. To do so, in the web interface's Spaces tab, click "View Details and Locations" for the SWORD server. The UUID will be shown at the top of the screen. The UUID is used to figure out the initial API URL to access (for example: "http://localhost:8000/api/v1/space/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/").<br />
<br />
== Example session ==<br />
<br />
Below is an example session using curl to manipulate the API. In the example a deposit is created, a file is added to it, and it is finalized.<br />
<br />
NOTE: The SWORD API is in the process of being moved to the storage service. These URLs may not work.<br />
<br />
<pre># create new deposit<br />
curl -v -H "In-Progress: true" --data-binary @mets.xml --request POST http://localhost:8000/api/v1/space/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/<br />
# response XML includes endpoints for adding additional files, etc.<br />
<br />
# add a file to the deposit<br />
curl -v -H "Content-Disposition: attachment; filename=mets.xml" --request POST \<br />
--data-binary "@mets.xml" \<br />
http://127.0.0.1:8000/api/v1/location/9c8b4ac0-0407-4360-a10d-af6c62a48b69/sword/media/<br />
<br />
# finalize transfer and approve processing<br />
curl -v -H "In-Progress: false" --request POST http://127.0.0.1:8000/api/v1/location/149cc29d-6472-4bcf-bee8-f8223bf60580/sword/<br />
</pre><br />
<br />
You might, at some point, want to list the transfers that have been started. The following curl command will do so.<br />
<br />
<pre>curl -v http://localhost:8000/api/v1/space/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/</pre><br />
<br />
If you're working on a transfer and want to list what files are included in it, the following curl command will list them.<br />
<br />
<pre># list files in transfer<br />
curl -v http://127.0.0.1:8000/api/v1/location/9c8b4ac0-0407-4360-a10d-af6c62a48b69/sword/media/</pre><br />
<br />
If you've started a deposit, but want to discard it, you can delete the deposit. The following curl command shows an example.<br />
<br />
<pre>curl -v -XDELETE http://127.0.0.1:8000/api/v1/location/149cc29d-6472-4bcf-bee8-f8223bf60580/sword/</pre><br />
<br />
== Synchronous Deposit Examples ==<br />
<br />
If you wanted to deposit a transfer then immediately finalize it you could use something like the following curl command.<br />
<br />
<pre>curl -v -H "In-Progress: false" --data-binary @mets.xml --request POST http://localhost:8000/api/v1/space/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/</pre><br />
<br />
<br />
== Endpoints ==<br />
<br />
=== Service document ===<br />
<br />
The SWORD service document provides information about the SWORD provider's capacities and lists SWORD collections. Archivematica currently includes one SWORD collection to which SWORD deposits can be made: transfers.<br />
<br />
The SWORD service document endpoint is located at /api/v1/sword/.<br />
<br />
Service document example:<br />
<pre><br />
<service xmlns:dcterms="http://purl.org/dc/terms/"<br />
xmlns:sword="http://purl.org/net/sword/terms/"<br />
xmlns:atom="http://www.w3.org/2005/Atom"<br />
xmlns="http://www.w3.org/2007/app"><br />
<br />
<sword:version>2.0</sword:version><br />
<br />
<workspace><br />
<atom:title>Archivematica storage service</atom:title><br />
<br />
<br />
<collection href="http://192.168.1.231:8000/api/v1/space/8f24ef5f-19d5-4b77-8a38-b30d034b11e7/sword/collection/"><br />
<atom:title>Collection</atom:title><br />
<accept>*/*</accept><br />
<accept alternate="multipart-related">*/*</accept><br />
<sword:mediation>false</sword:mediation><br />
</collection><br />
<br />
</workspace><br />
</service><br />
</pre><br />
<br />
=== List existing transfers ===<br />
* HTTP Get to the Collection IRI (defined by default as: /api/v1/space/[space UUID]/sword/collection/)<br />
* Transfers are listed as an Atom feed<br />
* Each Atom feed entry contains an "atom:link" element whose href attribute contains the URL needed to get details about the transfer<br />
* optional filters via get parameters (not yet implemented)<br />
<br />
=== Create a new transfer ===<br />
* used to start a new transfer in Archivematica<br />
* HTTP POST of an Atom Entry Document to the Collection IRI (defined by default as: /api/v1/space/[space UUID]/sword/collection/)<br />
<br />
'''Possible HTTP Response Codes'''<br />
* HTTP 200 OK - transfer already exists (not yet implemented)<br />
* HTTP 201 Created - transfer has been accepted<br />
* HTTP 412 Precondition Failed - required metadata missing or invalid<br />
<br />
Valid requests will receive a Sword Deposit Receipt in the body of the response.<br />
<br />
'''Required HTTP Headers'''<br />
The HTTP POST must include certain specific http headers. <br />
<br />
Required by http 1.1 specification:<br />
* Host: Must be set to archivematica host name.<br />
* Content-Length: Must be set to the length of the atom entry document.<br />
* Content-Type: Must be set to "application/atom+xml;type=entry".<br />
<br />
Required by Archivematica. <br />
* Authorization: Must include the api key and username assigned by Archivematica.<br />
<br />
Required by SWORD 2.0 protocol:<br />
* In-Progress: Must be set to "true"<br />
<br />
Optional in SWORD 2.0 protocol:<br />
* On-Behalf-Of: not implemented by Archivematica<br />
* Slug: not implemented by Archivematica<br />
<br />
'''Required in Body'''<br />
The Body of the request must be a valid METS Document. The required fields in an Atom Entry Document are:<br />
* LABEL: used as the transfer name<br />
* id: used as an accession id (not yet implemented)<br />
* author: used as the source of acquisition (not yet implemented)<br />
* summary: not implemented yet. Could be used in the future as a description for the Transfer<br />
* updated: should be set to the current timestamp. <br />
<br />
'''Example'''<br />
Example HTTP POST request:<br />
<pre><br />
POST /api/v1/space/96606387-cc70-4b09-b422-a7220606488d/sword/collection/ HTTP/1.1<br />
Host: localhost<br />
Authorization: Archivematica-API api_key="XXXXXXXXXXXXXXXXXXXX", username="timh"<br />
Content-Length: 213<br />
Content-Type: application/atom+xml;type=entry<br />
In-Progress: true<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<METS:mets EXT_VERSION="1.1" OBJID="islandora:72" LABEL="Cinderella"<br />
xmlns:METS="http://www.loc.gov/METS/"<br />
xmlns:xlink="http://www.w3.org/1999/xlink"<br />
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"<br />
xsi:schemaLocation="http://www.loc.gov/METS/ http://www.fedora.info/definitions/1/0/mets-fedora-ext1-1.xsd"><br />
<METS:fileSec><br />
<METS:fileGrp ID="DATASTREAMS"><br />
<METS:fileGrp ID="OBJ"><br />
<METS:file ID="OBJ.0"><br />
<METS:FLocat xlink:title="Cinderella_(1865).pdf" LOCTYPE="URL"<br />
xlink:href="http://localhost:8080/fedora/get/islandora:72/OBJ/2013-08-12T14:46:43.454Z" /><br />
</METS:file><br />
</METS:fileGrp><br />
</METS:fileGrp><br />
</METS:fileSec><br />
</METS:mets><br />
</pre><br />
<br />
Example Response:<br />
<pre><br />
201 Created<br />
Location: http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/<br />
<br />
<entry xmlns="http://www.w3.org/2005/Atom"<br />
xmlns:sword="http://purl.org/net/sword/"<br />
xmlns:dcterms="http://purl.org/dc/terms/"><br />
<br />
<title>Cinderella</title><br />
<id>91d4f258-0050-4914-9d0c-6a74815358d2</id><br />
<updated></updated><br />
<generator uri="https://www.archivematica.org" version="1.0"/><br />
<br />
<summary>A deposit was started.</summary><br />
<sword:treatment>A deposit directory was created and, optionally, asynchronous download of digital objects.</sword:treatment><br />
<br />
<link rel="alternate" href="http://www.swordserver.ac.uk/col1/mydeposit.html"/><br />
<link rel="edit-media" href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/media/"/><br />
<link rel="edit" href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/" /><br />
<link rel="http://purl.org/net/sword/terms/add" href="http://192.168.1.76:8000/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/" /><br />
<link rel="http://purl.org/net/sword/terms/statement" type="application/atom+xml;type=feed"<br />
href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/state/" /><br />
</entry><br />
</pre><br />
<br />
=== Add Files to a Transfer ===<br />
<br />
Posting file metadata (not yet implemented):<br />
* POST a METS file to the SE-IRI, listed below.<br />
* HTTP headers are required similar to Create Transfer call (above).<br />
* Body must include a valid Atom Entry document, that has METS embedded inside it.<br />
<br />
Posts file data:<br />
* It is possible to also POST the actual file to a deposit location's EM-IRI (/api/v1/location/[location UUID]/sword/media/)<br />
* The file should be posted as the request body and the filename specified using the Content-Disposition header (as per RFC 6266): for example "Content-Disposition: Attachment; filename=dog.jpg"<br />
* An MD5 checksum for an uploaded file can be provided via the Content-MD5 header (as per RFC 1544): for example "Content-MD5: Q2hlY2sgSW50ZWdyaXR5IQ=="<br />
* If only an Atom Entry Document is POST'ed, Archivematica will look for uri's in the file StructMap section of the METS file, and attempt to GET each file listed, to include in the Transfer. (not yet implemented)<br />
<br />
=== Finalize a Transfer ===<br />
* POST with no body to the SE-IRI<br />
* set In-Progress HTTP header to : false<br />
* This will tell Archivematica that no further content will be added or removed from the Transfer. <br />
* Archivematica will finish fetching any files that were added previously, and once they have all been downloaded, the Transfer will start through the Archivematica pipeline.<br />
<br />
'''Example'''<br />
<pre><br />
POST http://localhost/api/v1/location/55ce8053-113a-4954-8aa3-fc9771da0bda/sword/ HTTP/1.1<br />
Host: localhost<br />
Authorization: Archivematica-API api_key="XXXXXXXXXXXXXXXXXXXX", username="timh"<br />
Content-Length: 0<br />
Content-Type: application/atom+xml;type=entry<br />
In-Progress: false<br />
</pre><br />
<br />
The response will be HTTP 200/OK or 400/Error (400 if the Transfer was already finalized). If the transfer doesn't exist the response will be HTTP 404.<br />
<br />
=== Get Status of Transfer ===<br />
To check Status:<br />
<br />
GET the State-IRI<br />
in this example:<br />
<br />
GET http://localhost/api/v1/location/09224ddb-4c7d-404c-9218-2f2e1b5a599e/sword/state/ HTTP/1.1<br />
<br />
response will include:<br />
<pre><atom:feed xmlns:sword="http://purl.org/net/sword/terms/" <br />
xmlns:atom="http://www.w3.org/2005/Atom"><br />
<br />
<atom:category scheme="http://purl.org/net/sword/terms/state"<br />
term="failed"<br />
label="State"><br />
Deposit initiation: Failed<br />
</atom:category><br />
<br />
</atom:feed></pre><br />
the list of possible descriptions is not finalized.<br />
<br />
The state term value will either be "processing" (asynchronous deposit still working), "complete" (ready to be finalized), or "failed" (asynchronous deposit encountered an error).<br />
<br />
== Additional Details == <br />
<br />
=== Transfer Details ===<br />
* redirect to Edit-IRI<br />
* used to get basic info about a Transfer with HTTP GET<br />
* can update basic info using HTTP PUT (not yet implemented)<br />
* can allow deletion with HTTP DELETE<br />
* follows the form: /api/v1/location/[deposit location UUID]/sword/<br />
* example: http://192.168.1.231:8000/api/v1/location/09224ddb-4c7d-404c-9218-2f2e1b5a599e/sword/<br />
<br />
=== EM-IRI ===<br />
* Edit-Media IRI <br />
* used to add new objects to an existing transfer<br />
* follows the form: [archivematica hostname]/api/v2/transfer/[uuid of transfer]/media<br />
* example: /api/v1/location/[deposit location UUID]/sword/media/<br />
<br />
An HTTP POST to the em-iri for a transfer should include a file as the body<br />
<br />
An HTTP GET should return a list of files in the transfer<br />
<br />
An HTTP DELETE to the em-iri will remove all digital objects from the Transfer. This is a valid operation only while the Transfer is being assembled. Once the Transfer has been finalized, attempting to DELETE will return an error.<br />
<br />
=== Edit-IRI ===<br />
The client can replace the metadata of a resource by performing an HTTP PUT of a new Atom Entry on the Edit-IRI. (not yet implemented)<br />
<br />
This would be used to update metadata about a transfer, such as the transfer name.<br />
<br />
* example: http://localhost/api/v2/transfer/1225c695-cfb8-4ebb-aaaa-80da344efa6a/edit<br />
<br />
=== SE-IRI ===<br />
* example: http://localhost/api/v2/transfer/add/1225c695-cfb8-4ebb-aaaa-80da344efa6a (not yet implemented)<br />
<br />
=== State-IRI ===<br />
* used to retrieve status of transfer<br />
* implemented as Atom document<br />
* example: /api/v1/location/[deposit location UUID]/sword/state/<br />
* should be able to subscribe like RSS feed<br />
<br />
=== Service document ===</div>Mcantelonhttps://wiki.archivematica.org/index.php?title=Sword_API&diff=9333Sword API2014-01-11T00:02:13Z<p>Mcantelon: /* Service document */</p>
<hr />
<div><br />
== Overview ==<br />
<br />
One of the 1.1 release features is a sponsored project to integrate Archivematica with Islandora. This integration will be accomplished by creating a [http://swordapp.org Sword] 2.0 API for the Archivematica [https://www.archivematica.org/wiki/Administrator_manual_1.0#Storage_service storage service]. Islandora development work will add functionality to Islandora to use this API to deposit digital objects into Archviematica.<br />
<br />
As described [[Overview|elsewhere]] on this wiki, ''"the primary function of Archivematica is to process digital transfers (accessioned digital objects), turn them into SIPs, apply format policies and create high-quality, repository-independent Archival Information Packages (AIP)"''.<br />
<br />
The Archivematica Sword API allows 3rd party applications to automate the process of creating Transfers. <br />
#Create Transfer - set the name and other metadata about a Transfer<br />
#Populate Transfer - add/edit/update digital objects in a Transfer, and associated metadata<br />
#Finalize Transfer - indicates that the Transfer is ready to start processing.<br />
<br />
After content has been deposited, if users have access to the deposit directory they can also manually manipulate the deposit directory aside from any manipulation using the API.<br />
<br />
Once a Transfer has been created, populated and finalized, Archivematica will begin processing that Transfer.<br />
<br />
== Configuration ==<br />
<br />
The SWORD API is part of the Archivematica storage service REST API. The storage service also talks to the Archivematica dashboard, however, to notify it that a, transfer created from a SWORD deposit, has been approved for processing.<br />
<br />
To use the SWORD API you must install the Archivematica dashboard 1.0 branch and the Archivematica storage service dev/issue-5980-islandora branch.<br />
<br />
Dashboard configuration:<br />
<br />
# In dashboard REST API administration, add the IP of the storage service server to IP whitelist<br />
# In dashboard user administration, take note of username and API key for a dashboard user (example: user "demo" and API key "4e5f32ab2aefd3543e1b19a2de554dd65f90108a")<br />
# In dashboard general admininstration, take note of the dashboard's UUID<br />
<br />
Storage service configuration:<br />
<br />
# In the storage service web interface's Pipelines tab, find the dashboard pipeline (using dashboard's UUID noted during dashboard configuration)<br />
# Enter the dashboard's IP address into the "Remote name" field and the user and API key noted earlier into the "Api username" and "Api key" fields. Click the button to submit these changes.<br />
<br />
After configuration you'll need to find the space UUID of the SWORD server. To do so, in the web interface's Spaces tab, click "View Details and Locations" for the SWORD server. The UUID will be shown at the top of the screen. The UUID is used to figure out the initial API URL to access (for example: "http://localhost:8000/api/v1/space/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/").<br />
<br />
== Example session ==<br />
<br />
Below is an example session using curl to manipulate the API. In the example a deposit is created, a file is added to it, and it is finalized.<br />
<br />
NOTE: The SWORD API is in the process of being moved to the storage service. These URLs may not work.<br />
<br />
<pre># create new deposit<br />
curl -v -H "In-Progress: true" --data-binary @mets.xml --request POST http://localhost:8000/api/v1/space/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/<br />
# response XML includes endpoints for adding additional files, etc.<br />
<br />
# add a file to the deposit<br />
curl -v -H "Content-Disposition: attachment; filename=mets.xml" --request POST \<br />
--data-binary "@mets.xml" \<br />
http://127.0.0.1:8000/api/v1/location/9c8b4ac0-0407-4360-a10d-af6c62a48b69/sword/media/<br />
<br />
# finalize transfer and approve processing<br />
curl -v -H "In-Progress: false" --request POST http://127.0.0.1:8000/api/v1/location/149cc29d-6472-4bcf-bee8-f8223bf60580/sword/<br />
</pre><br />
<br />
You might, at some point, want to list the transfers that have been started. The following curl command will do so.<br />
<br />
<pre>curl -v http://localhost:8000/api/v1/space/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/</pre><br />
<br />
If you're working on a transfer and want to list what files are included in it, the following curl command will list them.<br />
<br />
<pre># list files in transfer<br />
curl -v http://127.0.0.1:8000/api/v1/location/9c8b4ac0-0407-4360-a10d-af6c62a48b69/sword/media/</pre><br />
<br />
If you've started a deposit, but want to discard it, you can delete the deposit. The following curl command shows an example.<br />
<br />
<pre>curl -v -XDELETE http://127.0.0.1:8000/api/v1/location/149cc29d-6472-4bcf-bee8-f8223bf60580/sword/</pre><br />
<br />
== Synchronous Deposit Examples ==<br />
<br />
If you wanted to deposit a transfer then immediately finalize it you could use something like the following curl command.<br />
<br />
<pre>curl -v -H "In-Progress: false" --data-binary @mets.xml --request POST http://localhost:8000/api/v1/space/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/</pre><br />
<br />
<br />
== Endpoints ==<br />
<br />
=== Service document ===<br />
<br />
The SWORD service document provides information about the SWORD provider's capacities and lists SWORD collections. Archivematica currently includes one SWORD collection to which SWORD deposits can be made: transfers.<br />
<br />
The SWORD service document endpoint is located at /api/v1/sword.<br />
<br />
Service document example:<br />
<pre><br />
<service xmlns:dcterms="http://purl.org/dc/terms/"<br />
xmlns:sword="http://purl.org/net/sword/terms/"<br />
xmlns:atom="http://www.w3.org/2005/Atom"<br />
xmlns="http://www.w3.org/2007/app"><br />
<br />
<sword:version>2.0</sword:version><br />
<br />
<workspace><br />
<atom:title>Archivematica storage service</atom:title><br />
<br />
<br />
<collection href="http://192.168.1.231:8000/api/v1/space/8f24ef5f-19d5-4b77-8a38-b30d034b11e7/sword/collection/"><br />
<atom:title>Collection</atom:title><br />
<accept>*/*</accept><br />
<accept alternate="multipart-related">*/*</accept><br />
<sword:mediation>false</sword:mediation><br />
</collection><br />
<br />
</workspace><br />
</service><br />
</pre><br />
<br />
=== List existing transfers ===<br />
* HTTP Get to the Collection IRI (defined by default as: /api/v1/space/[space UUID]/sword/collection/)<br />
* Transfers are listed as an Atom feed<br />
* Each Atom feed entry contains an "atom:link" element whose href attribute contains the URL needed to get details about the transfer<br />
* optional filters via get parameters (not yet implemented)<br />
<br />
=== Create a new transfer ===<br />
* used to start a new transfer in Archivematica<br />
* HTTP POST of an Atom Entry Document to the Collection IRI (defined by default as: /api/v1/space/[space UUID]/sword/collection/)<br />
<br />
'''Possible HTTP Response Codes'''<br />
* HTTP 200 OK - transfer already exists (not yet implemented)<br />
* HTTP 201 Created - transfer has been accepted<br />
* HTTP 412 Precondition Failed - required metadata missing or invalid<br />
<br />
Valid requests will receive a Sword Deposit Receipt in the body of the response.<br />
<br />
'''Required HTTP Headers'''<br />
The HTTP POST must include certain specific http headers. <br />
<br />
Required by http 1.1 specification:<br />
* Host: Must be set to archivematica host name.<br />
* Content-Length: Must be set to the length of the atom entry document.<br />
* Content-Type: Must be set to "application/atom+xml;type=entry".<br />
<br />
Required by Archivematica. <br />
* Authorization: Must include the api key and username assigned by Archivematica.<br />
<br />
Required by SWORD 2.0 protocol:<br />
* In-Progress: Must be set to "true"<br />
<br />
Optional in SWORD 2.0 protocol:<br />
* On-Behalf-Of: not implemented by Archivematica<br />
* Slug: not implemented by Archivematica<br />
<br />
'''Required in Body'''<br />
The Body of the request must be a valid METS Document. The required fields in an Atom Entry Document are:<br />
* LABEL: used as the transfer name<br />
* id: used as an accession id (not yet implemented)<br />
* author: used as the source of acquisition (not yet implemented)<br />
* summary: not implemented yet. Could be used in the future as a description for the Transfer<br />
* updated: should be set to the current timestamp. <br />
<br />
'''Example'''<br />
Example HTTP POST request:<br />
<pre><br />
POST /api/v1/space/96606387-cc70-4b09-b422-a7220606488d/sword/collection/ HTTP/1.1<br />
Host: localhost<br />
Authorization: Archivematica-API api_key="XXXXXXXXXXXXXXXXXXXX", username="timh"<br />
Content-Length: 213<br />
Content-Type: application/atom+xml;type=entry<br />
In-Progress: true<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<METS:mets EXT_VERSION="1.1" OBJID="islandora:72" LABEL="Cinderella"<br />
xmlns:METS="http://www.loc.gov/METS/"<br />
xmlns:xlink="http://www.w3.org/1999/xlink"<br />
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"<br />
xsi:schemaLocation="http://www.loc.gov/METS/ http://www.fedora.info/definitions/1/0/mets-fedora-ext1-1.xsd"><br />
<METS:fileSec><br />
<METS:fileGrp ID="DATASTREAMS"><br />
<METS:fileGrp ID="OBJ"><br />
<METS:file ID="OBJ.0"><br />
<METS:FLocat xlink:title="Cinderella_(1865).pdf" LOCTYPE="URL"<br />
xlink:href="http://localhost:8080/fedora/get/islandora:72/OBJ/2013-08-12T14:46:43.454Z" /><br />
</METS:file><br />
</METS:fileGrp><br />
</METS:fileGrp><br />
</METS:fileSec><br />
</METS:mets><br />
</pre><br />
<br />
Example Response:<br />
<pre><br />
201 Created<br />
Location: http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/<br />
<br />
<entry xmlns="http://www.w3.org/2005/Atom"<br />
xmlns:sword="http://purl.org/net/sword/"<br />
xmlns:dcterms="http://purl.org/dc/terms/"><br />
<br />
<title>Cinderella</title><br />
<id>91d4f258-0050-4914-9d0c-6a74815358d2</id><br />
<updated></updated><br />
<generator uri="https://www.archivematica.org" version="1.0"/><br />
<br />
<summary>A deposit was started.</summary><br />
<sword:treatment>A deposit directory was created and, optionally, asynchronous download of digital objects.</sword:treatment><br />
<br />
<link rel="alternate" href="http://www.swordserver.ac.uk/col1/mydeposit.html"/><br />
<link rel="edit-media" href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/media/"/><br />
<link rel="edit" href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/" /><br />
<link rel="http://purl.org/net/sword/terms/add" href="http://192.168.1.76:8000/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/" /><br />
<link rel="http://purl.org/net/sword/terms/statement" type="application/atom+xml;type=feed"<br />
href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/state/" /><br />
</entry><br />
</pre><br />
<br />
=== Add Files to a Transfer ===<br />
<br />
Posting file metadata (not yet implemented):<br />
* POST a METS file to the SE-IRI, listed below.<br />
* HTTP headers are required similar to Create Transfer call (above).<br />
* Body must include a valid Atom Entry document, that has METS embedded inside it.<br />
<br />
Posts file data:<br />
* It is possible to also POST the actual file to a deposit location's EM-IRI (/api/v1/location/[location UUID]/sword/media/)<br />
* The file should be posted as the request body and the filename specified using the Content-Disposition header (as per RFC 6266): for example "Content-Disposition: Attachment; filename=dog.jpg"<br />
* An MD5 checksum for an uploaded file can be provided via the Content-MD5 header (as per RFC 1544): for example "Content-MD5: Q2hlY2sgSW50ZWdyaXR5IQ=="<br />
* If only an Atom Entry Document is POST'ed, Archivematica will look for uri's in the file StructMap section of the METS file, and attempt to GET each file listed, to include in the Transfer. (not yet implemented)<br />
<br />
=== Finalize a Transfer ===<br />
* POST with no body to the SE-IRI<br />
* set In-Progress HTTP header to : false<br />
* This will tell Archivematica that no further content will be added or removed from the Transfer. <br />
* Archivematica will finish fetching any files that were added previously, and once they have all been downloaded, the Transfer will start through the Archivematica pipeline.<br />
<br />
'''Example'''<br />
<pre><br />
POST http://localhost/api/v1/location/55ce8053-113a-4954-8aa3-fc9771da0bda/sword/ HTTP/1.1<br />
Host: localhost<br />
Authorization: Archivematica-API api_key="XXXXXXXXXXXXXXXXXXXX", username="timh"<br />
Content-Length: 0<br />
Content-Type: application/atom+xml;type=entry<br />
In-Progress: false<br />
</pre><br />
<br />
The response will be HTTP 200/OK or 400/Error (400 if the Transfer was already finalized). If the transfer doesn't exist the response will be HTTP 404.<br />
<br />
=== Get Status of Transfer ===<br />
To check Status:<br />
<br />
GET the State-IRI<br />
in this example:<br />
<br />
GET http://localhost/api/v1/location/09224ddb-4c7d-404c-9218-2f2e1b5a599e/sword/state/ HTTP/1.1<br />
<br />
response will include:<br />
<pre><atom:feed xmlns:sword="http://purl.org/net/sword/terms/" <br />
xmlns:atom="http://www.w3.org/2005/Atom"><br />
<br />
<atom:category scheme="http://purl.org/net/sword/terms/state"<br />
term="failed"<br />
label="State"><br />
Deposit initiation: Failed<br />
</atom:category><br />
<br />
</atom:feed></pre><br />
the list of possible descriptions is not finalized.<br />
<br />
The state term value will either be "processing" (asynchronous deposit still working), "complete" (ready to be finalized), or "failed" (asynchronous deposit encountered an error).<br />
<br />
== Additional Details == <br />
<br />
=== Transfer Details ===<br />
* redirect to Edit-IRI<br />
* used to get basic info about a Transfer with HTTP GET<br />
* can update basic info using HTTP PUT (not yet implemented)<br />
* can allow deletion with HTTP DELETE<br />
* follows the form: /api/v1/location/[deposit location UUID]/sword/<br />
* example: http://192.168.1.231:8000/api/v1/location/09224ddb-4c7d-404c-9218-2f2e1b5a599e/sword/<br />
<br />
=== EM-IRI ===<br />
* Edit-Media IRI <br />
* used to add new objects to an existing transfer<br />
* follows the form: [archivematica hostname]/api/v2/transfer/[uuid of transfer]/media<br />
* example: /api/v1/location/[deposit location UUID]/sword/media/<br />
<br />
An HTTP POST to the em-iri for a transfer should include a file as the body<br />
<br />
An HTTP GET should return a list of files in the transfer<br />
<br />
An HTTP DELETE to the em-iri will remove all digital objects from the Transfer. This is a valid operation only while the Transfer is being assembled. Once the Transfer has been finalized, attempting to DELETE will return an error.<br />
<br />
=== Edit-IRI ===<br />
The client can replace the metadata of a resource by performing an HTTP PUT of a new Atom Entry on the Edit-IRI. (not yet implemented)<br />
<br />
This would be used to update metadata about a transfer, such as the transfer name.<br />
<br />
* example: http://localhost/api/v2/transfer/1225c695-cfb8-4ebb-aaaa-80da344efa6a/edit<br />
<br />
=== SE-IRI ===<br />
* example: http://localhost/api/v2/transfer/add/1225c695-cfb8-4ebb-aaaa-80da344efa6a (not yet implemented)<br />
<br />
=== State-IRI ===<br />
* used to retrieve status of transfer<br />
* implemented as Atom document<br />
* example: /api/v1/location/[deposit location UUID]/sword/state/<br />
* should be able to subscribe like RSS feed<br />
<br />
=== Service document ===</div>Mcantelonhttps://wiki.archivematica.org/index.php?title=Sword_API&diff=9332Sword API2014-01-10T23:37:47Z<p>Mcantelon: /* Example session */</p>
<hr />
<div><br />
== Overview ==<br />
<br />
One of the 1.1 release features is a sponsored project to integrate Archivematica with Islandora. This integration will be accomplished by creating a [http://swordapp.org Sword] 2.0 API for the Archivematica [https://www.archivematica.org/wiki/Administrator_manual_1.0#Storage_service storage service]. Islandora development work will add functionality to Islandora to use this API to deposit digital objects into Archviematica.<br />
<br />
As described [[Overview|elsewhere]] on this wiki, ''"the primary function of Archivematica is to process digital transfers (accessioned digital objects), turn them into SIPs, apply format policies and create high-quality, repository-independent Archival Information Packages (AIP)"''.<br />
<br />
The Archivematica Sword API allows 3rd party applications to automate the process of creating Transfers. <br />
#Create Transfer - set the name and other metadata about a Transfer<br />
#Populate Transfer - add/edit/update digital objects in a Transfer, and associated metadata<br />
#Finalize Transfer - indicates that the Transfer is ready to start processing.<br />
<br />
After content has been deposited, if users have access to the deposit directory they can also manually manipulate the deposit directory aside from any manipulation using the API.<br />
<br />
Once a Transfer has been created, populated and finalized, Archivematica will begin processing that Transfer.<br />
<br />
== Configuration ==<br />
<br />
The SWORD API is part of the Archivematica storage service REST API. The storage service also talks to the Archivematica dashboard, however, to notify it that a, transfer created from a SWORD deposit, has been approved for processing.<br />
<br />
To use the SWORD API you must install the Archivematica dashboard 1.0 branch and the Archivematica storage service dev/issue-5980-islandora branch.<br />
<br />
Dashboard configuration:<br />
<br />
# In dashboard REST API administration, add the IP of the storage service server to IP whitelist<br />
# In dashboard user administration, take note of username and API key for a dashboard user (example: user "demo" and API key "4e5f32ab2aefd3543e1b19a2de554dd65f90108a")<br />
# In dashboard general admininstration, take note of the dashboard's UUID<br />
<br />
Storage service configuration:<br />
<br />
# In the storage service web interface's Pipelines tab, find the dashboard pipeline (using dashboard's UUID noted during dashboard configuration)<br />
# Enter the dashboard's IP address into the "Remote name" field and the user and API key noted earlier into the "Api username" and "Api key" fields. Click the button to submit these changes.<br />
<br />
After configuration you'll need to find the space UUID of the SWORD server. To do so, in the web interface's Spaces tab, click "View Details and Locations" for the SWORD server. The UUID will be shown at the top of the screen. The UUID is used to figure out the initial API URL to access (for example: "http://localhost:8000/api/v1/space/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/").<br />
<br />
== Example session ==<br />
<br />
Below is an example session using curl to manipulate the API. In the example a deposit is created, a file is added to it, and it is finalized.<br />
<br />
NOTE: The SWORD API is in the process of being moved to the storage service. These URLs may not work.<br />
<br />
<pre># create new deposit<br />
curl -v -H "In-Progress: true" --data-binary @mets.xml --request POST http://localhost:8000/api/v1/space/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/<br />
# response XML includes endpoints for adding additional files, etc.<br />
<br />
# add a file to the deposit<br />
curl -v -H "Content-Disposition: attachment; filename=mets.xml" --request POST \<br />
--data-binary "@mets.xml" \<br />
http://127.0.0.1:8000/api/v1/location/9c8b4ac0-0407-4360-a10d-af6c62a48b69/sword/media/<br />
<br />
# finalize transfer and approve processing<br />
curl -v -H "In-Progress: false" --request POST http://127.0.0.1:8000/api/v1/location/149cc29d-6472-4bcf-bee8-f8223bf60580/sword/<br />
</pre><br />
<br />
You might, at some point, want to list the transfers that have been started. The following curl command will do so.<br />
<br />
<pre>curl -v http://localhost:8000/api/v1/space/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/</pre><br />
<br />
If you're working on a transfer and want to list what files are included in it, the following curl command will list them.<br />
<br />
<pre># list files in transfer<br />
curl -v http://127.0.0.1:8000/api/v1/location/9c8b4ac0-0407-4360-a10d-af6c62a48b69/sword/media/</pre><br />
<br />
If you've started a deposit, but want to discard it, you can delete the deposit. The following curl command shows an example.<br />
<br />
<pre>curl -v -XDELETE http://127.0.0.1:8000/api/v1/location/149cc29d-6472-4bcf-bee8-f8223bf60580/sword/</pre><br />
<br />
== Synchronous Deposit Examples ==<br />
<br />
If you wanted to deposit a transfer then immediately finalize it you could use something like the following curl command.<br />
<br />
<pre>curl -v -H "In-Progress: false" --data-binary @mets.xml --request POST http://localhost:8000/api/v1/space/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/</pre><br />
<br />
<br />
== Endpoints ==<br />
<br />
=== Service document ===<br />
<br />
The SWORD service document provides information about the SWORD provider's capacities and lists SWORD collections. Archivematica currently includes one SWORD collection to which SWORD deposits can be made: transfers.<br />
<br />
The SWORD service document endpoint is located at /api/v1/sword.<br />
<br />
=== List existing transfers ===<br />
* HTTP Get to the Collection IRI (defined by default as: /api/v1/space/[space UUID]/sword/collection/)<br />
* Transfers are listed as an Atom feed<br />
* Each Atom feed entry contains an "atom:link" element whose href attribute contains the URL needed to get details about the transfer<br />
* optional filters via get parameters (not yet implemented)<br />
<br />
=== Create a new transfer ===<br />
* used to start a new transfer in Archivematica<br />
* HTTP POST of an Atom Entry Document to the Collection IRI (defined by default as: /api/v1/space/[space UUID]/sword/collection/)<br />
<br />
'''Possible HTTP Response Codes'''<br />
* HTTP 200 OK - transfer already exists (not yet implemented)<br />
* HTTP 201 Created - transfer has been accepted<br />
* HTTP 412 Precondition Failed - required metadata missing or invalid<br />
<br />
Valid requests will receive a Sword Deposit Receipt in the body of the response.<br />
<br />
'''Required HTTP Headers'''<br />
The HTTP POST must include certain specific http headers. <br />
<br />
Required by http 1.1 specification:<br />
* Host: Must be set to archivematica host name.<br />
* Content-Length: Must be set to the length of the atom entry document.<br />
* Content-Type: Must be set to "application/atom+xml;type=entry".<br />
<br />
Required by Archivematica. <br />
* Authorization: Must include the api key and username assigned by Archivematica.<br />
<br />
Required by SWORD 2.0 protocol:<br />
* In-Progress: Must be set to "true"<br />
<br />
Optional in SWORD 2.0 protocol:<br />
* On-Behalf-Of: not implemented by Archivematica<br />
* Slug: not implemented by Archivematica<br />
<br />
'''Required in Body'''<br />
The Body of the request must be a valid METS Document. The required fields in an Atom Entry Document are:<br />
* LABEL: used as the transfer name<br />
* id: used as an accession id (not yet implemented)<br />
* author: used as the source of acquisition (not yet implemented)<br />
* summary: not implemented yet. Could be used in the future as a description for the Transfer<br />
* updated: should be set to the current timestamp. <br />
<br />
'''Example'''<br />
Example HTTP POST request:<br />
<pre><br />
POST /api/v1/space/96606387-cc70-4b09-b422-a7220606488d/sword/collection/ HTTP/1.1<br />
Host: localhost<br />
Authorization: Archivematica-API api_key="XXXXXXXXXXXXXXXXXXXX", username="timh"<br />
Content-Length: 213<br />
Content-Type: application/atom+xml;type=entry<br />
In-Progress: true<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<METS:mets EXT_VERSION="1.1" OBJID="islandora:72" LABEL="Cinderella"<br />
xmlns:METS="http://www.loc.gov/METS/"<br />
xmlns:xlink="http://www.w3.org/1999/xlink"<br />
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"<br />
xsi:schemaLocation="http://www.loc.gov/METS/ http://www.fedora.info/definitions/1/0/mets-fedora-ext1-1.xsd"><br />
<METS:fileSec><br />
<METS:fileGrp ID="DATASTREAMS"><br />
<METS:fileGrp ID="OBJ"><br />
<METS:file ID="OBJ.0"><br />
<METS:FLocat xlink:title="Cinderella_(1865).pdf" LOCTYPE="URL"<br />
xlink:href="http://localhost:8080/fedora/get/islandora:72/OBJ/2013-08-12T14:46:43.454Z" /><br />
</METS:file><br />
</METS:fileGrp><br />
</METS:fileGrp><br />
</METS:fileSec><br />
</METS:mets><br />
</pre><br />
<br />
Example Response:<br />
<pre><br />
201 Created<br />
Location: http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/<br />
<br />
<entry xmlns="http://www.w3.org/2005/Atom"<br />
xmlns:sword="http://purl.org/net/sword/"<br />
xmlns:dcterms="http://purl.org/dc/terms/"><br />
<br />
<title>Cinderella</title><br />
<id>91d4f258-0050-4914-9d0c-6a74815358d2</id><br />
<updated></updated><br />
<generator uri="https://www.archivematica.org" version="1.0"/><br />
<br />
<summary>A deposit was started.</summary><br />
<sword:treatment>A deposit directory was created and, optionally, asynchronous download of digital objects.</sword:treatment><br />
<br />
<link rel="alternate" href="http://www.swordserver.ac.uk/col1/mydeposit.html"/><br />
<link rel="edit-media" href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/media/"/><br />
<link rel="edit" href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/" /><br />
<link rel="http://purl.org/net/sword/terms/add" href="http://192.168.1.76:8000/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/" /><br />
<link rel="http://purl.org/net/sword/terms/statement" type="application/atom+xml;type=feed"<br />
href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/state/" /><br />
</entry><br />
</pre><br />
<br />
=== Add Files to a Transfer ===<br />
<br />
Posting file metadata (not yet implemented):<br />
* POST a METS file to the SE-IRI, listed below.<br />
* HTTP headers are required similar to Create Transfer call (above).<br />
* Body must include a valid Atom Entry document, that has METS embedded inside it.<br />
<br />
Posts file data:<br />
* It is possible to also POST the actual file to a deposit location's EM-IRI (/api/v1/location/[location UUID]/sword/media/)<br />
* The file should be posted as the request body and the filename specified using the Content-Disposition header (as per RFC 6266): for example "Content-Disposition: Attachment; filename=dog.jpg"<br />
* An MD5 checksum for an uploaded file can be provided via the Content-MD5 header (as per RFC 1544): for example "Content-MD5: Q2hlY2sgSW50ZWdyaXR5IQ=="<br />
* If only an Atom Entry Document is POST'ed, Archivematica will look for uri's in the file StructMap section of the METS file, and attempt to GET each file listed, to include in the Transfer. (not yet implemented)<br />
<br />
=== Finalize a Transfer ===<br />
* POST with no body to the SE-IRI<br />
* set In-Progress HTTP header to : false<br />
* This will tell Archivematica that no further content will be added or removed from the Transfer. <br />
* Archivematica will finish fetching any files that were added previously, and once they have all been downloaded, the Transfer will start through the Archivematica pipeline.<br />
<br />
'''Example'''<br />
<pre><br />
POST http://localhost/api/v1/location/55ce8053-113a-4954-8aa3-fc9771da0bda/sword/ HTTP/1.1<br />
Host: localhost<br />
Authorization: Archivematica-API api_key="XXXXXXXXXXXXXXXXXXXX", username="timh"<br />
Content-Length: 0<br />
Content-Type: application/atom+xml;type=entry<br />
In-Progress: false<br />
</pre><br />
<br />
The response will be HTTP 200/OK or 400/Error (400 if the Transfer was already finalized). If the transfer doesn't exist the response will be HTTP 404.<br />
<br />
=== Get Status of Transfer ===<br />
To check Status:<br />
<br />
GET the State-IRI<br />
in this example:<br />
<br />
GET http://localhost/api/v1/location/09224ddb-4c7d-404c-9218-2f2e1b5a599e/sword/state/ HTTP/1.1<br />
<br />
response will include:<br />
<pre><atom:feed xmlns:sword="http://purl.org/net/sword/terms/" <br />
xmlns:atom="http://www.w3.org/2005/Atom"><br />
<br />
<atom:category scheme="http://purl.org/net/sword/terms/state"<br />
term="failed"<br />
label="State"><br />
Deposit initiation: Failed<br />
</atom:category><br />
<br />
</atom:feed></pre><br />
the list of possible descriptions is not finalized.<br />
<br />
The state term value will either be "processing" (asynchronous deposit still working), "complete" (ready to be finalized), or "failed" (asynchronous deposit encountered an error).<br />
<br />
== Additional Details == <br />
<br />
=== Transfer Details ===<br />
* redirect to Edit-IRI<br />
* used to get basic info about a Transfer with HTTP GET<br />
* can update basic info using HTTP PUT (not yet implemented)<br />
* can allow deletion with HTTP DELETE<br />
* follows the form: /api/v1/location/[deposit location UUID]/sword/<br />
* example: http://192.168.1.231:8000/api/v1/location/09224ddb-4c7d-404c-9218-2f2e1b5a599e/sword/<br />
<br />
=== EM-IRI ===<br />
* Edit-Media IRI <br />
* used to add new objects to an existing transfer<br />
* follows the form: [archivematica hostname]/api/v2/transfer/[uuid of transfer]/media<br />
* example: /api/v1/location/[deposit location UUID]/sword/media/<br />
<br />
An HTTP POST to the em-iri for a transfer should include a file as the body<br />
<br />
An HTTP GET should return a list of files in the transfer<br />
<br />
An HTTP DELETE to the em-iri will remove all digital objects from the Transfer. This is a valid operation only while the Transfer is being assembled. Once the Transfer has been finalized, attempting to DELETE will return an error.<br />
<br />
=== Edit-IRI ===<br />
The client can replace the metadata of a resource by performing an HTTP PUT of a new Atom Entry on the Edit-IRI. (not yet implemented)<br />
<br />
This would be used to update metadata about a transfer, such as the transfer name.<br />
<br />
* example: http://localhost/api/v2/transfer/1225c695-cfb8-4ebb-aaaa-80da344efa6a/edit<br />
<br />
=== SE-IRI ===<br />
* example: http://localhost/api/v2/transfer/add/1225c695-cfb8-4ebb-aaaa-80da344efa6a (not yet implemented)<br />
<br />
=== State-IRI ===<br />
* used to retrieve status of transfer<br />
* implemented as Atom document<br />
* example: /api/v1/location/[deposit location UUID]/sword/state/<br />
* should be able to subscribe like RSS feed<br />
<br />
=== Service document ===</div>Mcantelonhttps://wiki.archivematica.org/index.php?title=Sword_API&diff=9330Sword API2014-01-10T22:46:11Z<p>Mcantelon: /* Example session */</p>
<hr />
<div><br />
== Overview ==<br />
<br />
One of the 1.1 release features is a sponsored project to integrate Archivematica with Islandora. This integration will be accomplished by creating a [http://swordapp.org Sword] 2.0 API for the Archivematica [https://www.archivematica.org/wiki/Administrator_manual_1.0#Storage_service storage service]. Islandora development work will add functionality to Islandora to use this API to deposit digital objects into Archviematica.<br />
<br />
As described [[Overview|elsewhere]] on this wiki, ''"the primary function of Archivematica is to process digital transfers (accessioned digital objects), turn them into SIPs, apply format policies and create high-quality, repository-independent Archival Information Packages (AIP)"''.<br />
<br />
The Archivematica Sword API allows 3rd party applications to automate the process of creating Transfers. <br />
#Create Transfer - set the name and other metadata about a Transfer<br />
#Populate Transfer - add/edit/update digital objects in a Transfer, and associated metadata<br />
#Finalize Transfer - indicates that the Transfer is ready to start processing.<br />
<br />
After content has been deposited, if users have access to the deposit directory they can also manually manipulate the deposit directory aside from any manipulation using the API.<br />
<br />
Once a Transfer has been created, populated and finalized, Archivematica will begin processing that Transfer.<br />
<br />
== Configuration ==<br />
<br />
The SWORD API is part of the Archivematica storage service REST API. The storage service also talks to the Archivematica dashboard, however, to notify it that a, transfer created from a SWORD deposit, has been approved for processing.<br />
<br />
To use the SWORD API you must install the Archivematica dashboard 1.0 branch and the Archivematica storage service dev/issue-5980-islandora branch.<br />
<br />
Dashboard configuration:<br />
<br />
# In dashboard REST API administration, add the IP of the storage service server to IP whitelist<br />
# In dashboard user administration, take note of username and API key for a dashboard user (example: user "demo" and API key "4e5f32ab2aefd3543e1b19a2de554dd65f90108a")<br />
# In dashboard general admininstration, take note of the dashboard's UUID<br />
<br />
Storage service configuration:<br />
<br />
# In the storage service web interface's Pipelines tab, find the dashboard pipeline (using dashboard's UUID noted during dashboard configuration)<br />
# Enter the dashboard's IP address into the "Remote name" field and the user and API key noted earlier into the "Api username" and "Api key" fields. Click the button to submit these changes.<br />
<br />
After configuration you'll need to find the space UUID of the SWORD server. To do so, in the web interface's Spaces tab, click "View Details and Locations" for the SWORD server. The UUID will be shown at the top of the screen. The UUID is used to figure out the initial API URL to access (for example: "http://localhost:8000/api/v1/space/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/").<br />
<br />
== Example session ==<br />
<br />
Below is an example session using curl to manipulate the API. In the example a deposit is created, a file is added to it, and it is finalized.<br />
<br />
NOTE: The SWORD API is in the process of being moved to the storage service. These URLs may not work.<br />
<br />
<pre># create new deposit<br />
curl -v -H "In-Progress: true" --data-binary @mets.xml --request POST http://localhost:8000/api/v1/space/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/<br />
# response XML includes endpoints for adding additional files, etc.<br />
<br />
# add a file to the deposit<br />
curl -v -H "Content-Disposition: attachment; filename=mets.xml" --request POST \<br />
--data-binary "@mets.xml" \<br />
http://127.0.0.1:8000/api/v1/location/9c8b4ac0-0407-4360-a10d-af6c62a48b69/sword/media/<br />
<br />
# finalize transfer and approve processing<br />
curl -v -H "In-Progress: false" --request POST http://127.0.0.1:8000/api/v1/location/149cc29d-6472-4bcf-bee8-f8223bf60580/sword/<br />
</pre><br />
<br />
You might, at some point, want to list the transfers that have been started. The following curl command will do so.<br />
<br />
<pre>curl -v http://localhost:8000/api/v1/location/52bbe770-3f96-4493-8d93-ded54c958c51/sword/collection/</pre><br />
<br />
If you're working on a transfer and want to list what files are included in it, the following curl command will list them.<br />
<br />
<pre># list files in transfer<br />
curl -v http://127.0.0.1:8000/api/v1/location/9c8b4ac0-0407-4360-a10d-af6c62a48b69/sword/media/</pre><br />
<br />
If you've started a deposit, but want to discard it, you can delete the deposit. The following curl command shows an example.<br />
<br />
<pre>curl -v -XDELETE http://127.0.0.1:8000/api/v1/location/149cc29d-6472-4bcf-bee8-f8223bf60580/sword/</pre><br />
<br />
== Synchronous Deposit Examples ==<br />
<br />
If you wanted to deposit a transfer then immediately finalize it you could use something like the following curl command.<br />
<br />
<pre>curl -v -H "In-Progress: false" --data-binary @mets.xml --request POST http://localhost:8000/api/v1/space/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/</pre><br />
<br />
<br />
== Endpoints ==<br />
<br />
=== Service document ===<br />
<br />
The SWORD service document provides information about the SWORD provider's capacities and lists SWORD collections. Archivematica currently includes one SWORD collection to which SWORD deposits can be made: transfers.<br />
<br />
The SWORD service document endpoint is located at /api/v1/sword.<br />
<br />
=== List existing transfers ===<br />
* HTTP Get to the Collection IRI (defined by default as: /api/v1/space/[space UUID]/sword/collection/)<br />
* Transfers are listed as an Atom feed<br />
* Each Atom feed entry contains an "atom:link" element whose href attribute contains the URL needed to get details about the transfer<br />
* optional filters via get parameters (not yet implemented)<br />
<br />
=== Create a new transfer ===<br />
* used to start a new transfer in Archivematica<br />
* HTTP POST of an Atom Entry Document to the Collection IRI (defined by default as: /api/v1/space/[space UUID]/sword/collection/)<br />
<br />
'''Possible HTTP Response Codes'''<br />
* HTTP 200 OK - transfer already exists (not yet implemented)<br />
* HTTP 201 Created - transfer has been accepted<br />
* HTTP 412 Precondition Failed - required metadata missing or invalid<br />
<br />
Valid requests will receive a Sword Deposit Receipt in the body of the response.<br />
<br />
'''Required HTTP Headers'''<br />
The HTTP POST must include certain specific http headers. <br />
<br />
Required by http 1.1 specification:<br />
* Host: Must be set to archivematica host name.<br />
* Content-Length: Must be set to the length of the atom entry document.<br />
* Content-Type: Must be set to "application/atom+xml;type=entry".<br />
<br />
Required by Archivematica. <br />
* Authorization: Must include the api key and username assigned by Archivematica.<br />
<br />
Required by SWORD 2.0 protocol:<br />
* In-Progress: Must be set to "true"<br />
<br />
Optional in SWORD 2.0 protocol:<br />
* On-Behalf-Of: not implemented by Archivematica<br />
* Slug: not implemented by Archivematica<br />
<br />
'''Required in Body'''<br />
The Body of the request must be a valid METS Document. The required fields in an Atom Entry Document are:<br />
* LABEL: used as the transfer name<br />
* id: used as an accession id (not yet implemented)<br />
* author: used as the source of acquisition (not yet implemented)<br />
* summary: not implemented yet. Could be used in the future as a description for the Transfer<br />
* updated: should be set to the current timestamp. <br />
<br />
'''Example'''<br />
Example HTTP POST request:<br />
<pre><br />
POST /api/v1/space/96606387-cc70-4b09-b422-a7220606488d/sword/collection/ HTTP/1.1<br />
Host: localhost<br />
Authorization: Archivematica-API api_key="XXXXXXXXXXXXXXXXXXXX", username="timh"<br />
Content-Length: 213<br />
Content-Type: application/atom+xml;type=entry<br />
In-Progress: true<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<METS:mets EXT_VERSION="1.1" OBJID="islandora:72" LABEL="Cinderella"<br />
xmlns:METS="http://www.loc.gov/METS/"<br />
xmlns:xlink="http://www.w3.org/1999/xlink"<br />
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"<br />
xsi:schemaLocation="http://www.loc.gov/METS/ http://www.fedora.info/definitions/1/0/mets-fedora-ext1-1.xsd"><br />
<METS:fileSec><br />
<METS:fileGrp ID="DATASTREAMS"><br />
<METS:fileGrp ID="OBJ"><br />
<METS:file ID="OBJ.0"><br />
<METS:FLocat xlink:title="Cinderella_(1865).pdf" LOCTYPE="URL"<br />
xlink:href="http://localhost:8080/fedora/get/islandora:72/OBJ/2013-08-12T14:46:43.454Z" /><br />
</METS:file><br />
</METS:fileGrp><br />
</METS:fileGrp><br />
</METS:fileSec><br />
</METS:mets><br />
</pre><br />
<br />
Example Response:<br />
<pre><br />
201 Created<br />
Location: http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/<br />
<br />
<entry xmlns="http://www.w3.org/2005/Atom"<br />
xmlns:sword="http://purl.org/net/sword/"<br />
xmlns:dcterms="http://purl.org/dc/terms/"><br />
<br />
<title>Cinderella</title><br />
<id>91d4f258-0050-4914-9d0c-6a74815358d2</id><br />
<updated></updated><br />
<generator uri="https://www.archivematica.org" version="1.0"/><br />
<br />
<summary>A deposit was started.</summary><br />
<sword:treatment>A deposit directory was created and, optionally, asynchronous download of digital objects.</sword:treatment><br />
<br />
<link rel="alternate" href="http://www.swordserver.ac.uk/col1/mydeposit.html"/><br />
<link rel="edit-media" href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/media/"/><br />
<link rel="edit" href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/" /><br />
<link rel="http://purl.org/net/sword/terms/add" href="http://192.168.1.76:8000/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/" /><br />
<link rel="http://purl.org/net/sword/terms/statement" type="application/atom+xml;type=feed"<br />
href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/state/" /><br />
</entry><br />
</pre><br />
<br />
=== Add Files to a Transfer ===<br />
<br />
Posting file metadata (not yet implemented):<br />
* POST a METS file to the SE-IRI, listed below.<br />
* HTTP headers are required similar to Create Transfer call (above).<br />
* Body must include a valid Atom Entry document, that has METS embedded inside it.<br />
<br />
Posts file data:<br />
* It is possible to also POST the actual file to a deposit location's EM-IRI (/api/v1/location/[location UUID]/sword/media/)<br />
* The file should be posted as the request body and the filename specified using the Content-Disposition header (as per RFC 6266): for example "Content-Disposition: Attachment; filename=dog.jpg"<br />
* An MD5 checksum for an uploaded file can be provided via the Content-MD5 header (as per RFC 1544): for example "Content-MD5: Q2hlY2sgSW50ZWdyaXR5IQ=="<br />
* If only an Atom Entry Document is POST'ed, Archivematica will look for uri's in the file StructMap section of the METS file, and attempt to GET each file listed, to include in the Transfer. (not yet implemented)<br />
<br />
=== Finalize a Transfer ===<br />
* POST with no body to the SE-IRI<br />
* set In-Progress HTTP header to : false<br />
* This will tell Archivematica that no further content will be added or removed from the Transfer. <br />
* Archivematica will finish fetching any files that were added previously, and once they have all been downloaded, the Transfer will start through the Archivematica pipeline.<br />
<br />
'''Example'''<br />
<pre><br />
POST http://localhost/api/v1/location/55ce8053-113a-4954-8aa3-fc9771da0bda/sword/ HTTP/1.1<br />
Host: localhost<br />
Authorization: Archivematica-API api_key="XXXXXXXXXXXXXXXXXXXX", username="timh"<br />
Content-Length: 0<br />
Content-Type: application/atom+xml;type=entry<br />
In-Progress: false<br />
</pre><br />
<br />
The response will be HTTP 200/OK or 400/Error (400 if the Transfer was already finalized). If the transfer doesn't exist the response will be HTTP 404.<br />
<br />
=== Get Status of Transfer ===<br />
To check Status:<br />
<br />
GET the State-IRI<br />
in this example:<br />
<br />
GET http://localhost/api/v1/location/09224ddb-4c7d-404c-9218-2f2e1b5a599e/sword/state/ HTTP/1.1<br />
<br />
response will include:<br />
<pre><atom:feed xmlns:sword="http://purl.org/net/sword/terms/" <br />
xmlns:atom="http://www.w3.org/2005/Atom"><br />
<br />
<atom:category scheme="http://purl.org/net/sword/terms/state"<br />
term="failed"<br />
label="State"><br />
Deposit initiation: Failed<br />
</atom:category><br />
<br />
</atom:feed></pre><br />
the list of possible descriptions is not finalized.<br />
<br />
The state term value will either be "processing" (asynchronous deposit still working), "complete" (ready to be finalized), or "failed" (asynchronous deposit encountered an error).<br />
<br />
== Additional Details == <br />
<br />
=== Transfer Details ===<br />
* redirect to Edit-IRI<br />
* used to get basic info about a Transfer with HTTP GET<br />
* can update basic info using HTTP PUT (not yet implemented)<br />
* can allow deletion with HTTP DELETE<br />
* follows the form: /api/v1/location/[deposit location UUID]/sword/<br />
* example: http://192.168.1.231:8000/api/v1/location/09224ddb-4c7d-404c-9218-2f2e1b5a599e/sword/<br />
<br />
=== EM-IRI ===<br />
* Edit-Media IRI <br />
* used to add new objects to an existing transfer<br />
* follows the form: [archivematica hostname]/api/v2/transfer/[uuid of transfer]/media<br />
* example: /api/v1/location/[deposit location UUID]/sword/media/<br />
<br />
An HTTP POST to the em-iri for a transfer should include a file as the body<br />
<br />
An HTTP GET should return a list of files in the transfer<br />
<br />
An HTTP DELETE to the em-iri will remove all digital objects from the Transfer. This is a valid operation only while the Transfer is being assembled. Once the Transfer has been finalized, attempting to DELETE will return an error.<br />
<br />
=== Edit-IRI ===<br />
The client can replace the metadata of a resource by performing an HTTP PUT of a new Atom Entry on the Edit-IRI. (not yet implemented)<br />
<br />
This would be used to update metadata about a transfer, such as the transfer name.<br />
<br />
* example: http://localhost/api/v2/transfer/1225c695-cfb8-4ebb-aaaa-80da344efa6a/edit<br />
<br />
=== SE-IRI ===<br />
* example: http://localhost/api/v2/transfer/add/1225c695-cfb8-4ebb-aaaa-80da344efa6a (not yet implemented)<br />
<br />
=== State-IRI ===<br />
* used to retrieve status of transfer<br />
* implemented as Atom document<br />
* example: /api/v1/location/[deposit location UUID]/sword/state/<br />
* should be able to subscribe like RSS feed<br />
<br />
=== Service document ===</div>Mcantelonhttps://wiki.archivematica.org/index.php?title=Sword_API&diff=9329Sword API2014-01-10T22:33:00Z<p>Mcantelon: /* Example session */</p>
<hr />
<div><br />
== Overview ==<br />
<br />
One of the 1.1 release features is a sponsored project to integrate Archivematica with Islandora. This integration will be accomplished by creating a [http://swordapp.org Sword] 2.0 API for the Archivematica [https://www.archivematica.org/wiki/Administrator_manual_1.0#Storage_service storage service]. Islandora development work will add functionality to Islandora to use this API to deposit digital objects into Archviematica.<br />
<br />
As described [[Overview|elsewhere]] on this wiki, ''"the primary function of Archivematica is to process digital transfers (accessioned digital objects), turn them into SIPs, apply format policies and create high-quality, repository-independent Archival Information Packages (AIP)"''.<br />
<br />
The Archivematica Sword API allows 3rd party applications to automate the process of creating Transfers. <br />
#Create Transfer - set the name and other metadata about a Transfer<br />
#Populate Transfer - add/edit/update digital objects in a Transfer, and associated metadata<br />
#Finalize Transfer - indicates that the Transfer is ready to start processing.<br />
<br />
After content has been deposited, if users have access to the deposit directory they can also manually manipulate the deposit directory aside from any manipulation using the API.<br />
<br />
Once a Transfer has been created, populated and finalized, Archivematica will begin processing that Transfer.<br />
<br />
== Configuration ==<br />
<br />
The SWORD API is part of the Archivematica storage service REST API. The storage service also talks to the Archivematica dashboard, however, to notify it that a, transfer created from a SWORD deposit, has been approved for processing.<br />
<br />
To use the SWORD API you must install the Archivematica dashboard 1.0 branch and the Archivematica storage service dev/issue-5980-islandora branch.<br />
<br />
Dashboard configuration:<br />
<br />
# In dashboard REST API administration, add the IP of the storage service server to IP whitelist<br />
# In dashboard user administration, take note of username and API key for a dashboard user (example: user "demo" and API key "4e5f32ab2aefd3543e1b19a2de554dd65f90108a")<br />
# In dashboard general admininstration, take note of the dashboard's UUID<br />
<br />
Storage service configuration:<br />
<br />
# In the storage service web interface's Pipelines tab, find the dashboard pipeline (using dashboard's UUID noted during dashboard configuration)<br />
# Enter the dashboard's IP address into the "Remote name" field and the user and API key noted earlier into the "Api username" and "Api key" fields. Click the button to submit these changes.<br />
<br />
After configuration you'll need to find the space UUID of the SWORD server. To do so, in the web interface's Spaces tab, click "View Details and Locations" for the SWORD server. The UUID will be shown at the top of the screen. The UUID is used to figure out the initial API URL to access (for example: "http://localhost:8000/api/v1/space/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/").<br />
<br />
== Example session ==<br />
<br />
Below is an example session using curl to manipulate the API. In the example a deposit is created, a file is added to it, and it is finalized.<br />
<br />
NOTE: The SWORD API is in the process of being moved to the storage service. These URLs may not work.<br />
<br />
<pre># create new deposit<br />
curl -v -H "In-Progress: true" --request POST http://localhost:8000/api/v1/space/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/<br />
# response XML includes endpoints for adding additional files, etc.<br />
<br />
# add a file to the deposit<br />
curl -v -H "Content-Disposition: attachment; filename=mets.xml" --request POST \<br />
--data-binary "@mets.xml" \<br />
http://127.0.0.1:8000/api/v1/location/9c8b4ac0-0407-4360-a10d-af6c62a48b69/sword/media/<br />
<br />
# finalize transfer and approve processing<br />
curl -v -H "In-Progress: false" --request POST http://127.0.0.1:8000/api/v1/location/149cc29d-6472-4bcf-bee8-f8223bf60580/sword/<br />
</pre><br />
<br />
You might, at some point, want to list the transfers that have been started. The following curl command will do so.<br />
<br />
<pre>curl -v http://localhost:8000/api/v1/location/52bbe770-3f96-4493-8d93-ded54c958c51/sword/collection/</pre><br />
<br />
If you're working on a transfer and want to list what files are included in it, the following curl command will list them.<br />
<br />
<pre># list files in transfer<br />
curl -v http://127.0.0.1:8000/api/v1/location/9c8b4ac0-0407-4360-a10d-af6c62a48b69/sword/media/</pre><br />
<br />
If you've started a deposit, but want to discard it, you can delete the deposit. The following curl command shows an example.<br />
<br />
<pre>curl -v -XDELETE http://127.0.0.1:8000/api/v1/location/149cc29d-6472-4bcf-bee8-f8223bf60580/sword/</pre><br />
<br />
== Synchronous Deposit Examples ==<br />
<br />
If you wanted to deposit a transfer then immediately finalize it you could use something like the following curl command.<br />
<br />
<pre>curl -v -H "In-Progress: false" --data-binary @mets.xml --request POST http://localhost:8000/api/v1/space/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/</pre><br />
<br />
<br />
== Endpoints ==<br />
<br />
=== Service document ===<br />
<br />
The SWORD service document provides information about the SWORD provider's capacities and lists SWORD collections. Archivematica currently includes one SWORD collection to which SWORD deposits can be made: transfers.<br />
<br />
The SWORD service document endpoint is located at /api/v1/sword.<br />
<br />
=== List existing transfers ===<br />
* HTTP Get to the Collection IRI (defined by default as: /api/v1/space/[space UUID]/sword/collection/)<br />
* Transfers are listed as an Atom feed<br />
* Each Atom feed entry contains an "atom:link" element whose href attribute contains the URL needed to get details about the transfer<br />
* optional filters via get parameters (not yet implemented)<br />
<br />
=== Create a new transfer ===<br />
* used to start a new transfer in Archivematica<br />
* HTTP POST of an Atom Entry Document to the Collection IRI (defined by default as: /api/v1/space/[space UUID]/sword/collection/)<br />
<br />
'''Possible HTTP Response Codes'''<br />
* HTTP 200 OK - transfer already exists (not yet implemented)<br />
* HTTP 201 Created - transfer has been accepted<br />
* HTTP 412 Precondition Failed - required metadata missing or invalid<br />
<br />
Valid requests will receive a Sword Deposit Receipt in the body of the response.<br />
<br />
'''Required HTTP Headers'''<br />
The HTTP POST must include certain specific http headers. <br />
<br />
Required by http 1.1 specification:<br />
* Host: Must be set to archivematica host name.<br />
* Content-Length: Must be set to the length of the atom entry document.<br />
* Content-Type: Must be set to "application/atom+xml;type=entry".<br />
<br />
Required by Archivematica. <br />
* Authorization: Must include the api key and username assigned by Archivematica.<br />
<br />
Required by SWORD 2.0 protocol:<br />
* In-Progress: Must be set to "true"<br />
<br />
Optional in SWORD 2.0 protocol:<br />
* On-Behalf-Of: not implemented by Archivematica<br />
* Slug: not implemented by Archivematica<br />
<br />
'''Required in Body'''<br />
The Body of the request must be a valid METS Document. The required fields in an Atom Entry Document are:<br />
* LABEL: used as the transfer name<br />
* id: used as an accession id (not yet implemented)<br />
* author: used as the source of acquisition (not yet implemented)<br />
* summary: not implemented yet. Could be used in the future as a description for the Transfer<br />
* updated: should be set to the current timestamp. <br />
<br />
'''Example'''<br />
Example HTTP POST request:<br />
<pre><br />
POST /api/v1/space/96606387-cc70-4b09-b422-a7220606488d/sword/collection/ HTTP/1.1<br />
Host: localhost<br />
Authorization: Archivematica-API api_key="XXXXXXXXXXXXXXXXXXXX", username="timh"<br />
Content-Length: 213<br />
Content-Type: application/atom+xml;type=entry<br />
In-Progress: true<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<METS:mets EXT_VERSION="1.1" OBJID="islandora:72" LABEL="Cinderella"<br />
xmlns:METS="http://www.loc.gov/METS/"<br />
xmlns:xlink="http://www.w3.org/1999/xlink"<br />
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"<br />
xsi:schemaLocation="http://www.loc.gov/METS/ http://www.fedora.info/definitions/1/0/mets-fedora-ext1-1.xsd"><br />
<METS:fileSec><br />
<METS:fileGrp ID="DATASTREAMS"><br />
<METS:fileGrp ID="OBJ"><br />
<METS:file ID="OBJ.0"><br />
<METS:FLocat xlink:title="Cinderella_(1865).pdf" LOCTYPE="URL"<br />
xlink:href="http://localhost:8080/fedora/get/islandora:72/OBJ/2013-08-12T14:46:43.454Z" /><br />
</METS:file><br />
</METS:fileGrp><br />
</METS:fileGrp><br />
</METS:fileSec><br />
</METS:mets><br />
</pre><br />
<br />
Example Response:<br />
<pre><br />
201 Created<br />
Location: http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/<br />
<br />
<entry xmlns="http://www.w3.org/2005/Atom"<br />
xmlns:sword="http://purl.org/net/sword/"<br />
xmlns:dcterms="http://purl.org/dc/terms/"><br />
<br />
<title>Cinderella</title><br />
<id>91d4f258-0050-4914-9d0c-6a74815358d2</id><br />
<updated></updated><br />
<generator uri="https://www.archivematica.org" version="1.0"/><br />
<br />
<summary>A deposit was started.</summary><br />
<sword:treatment>A deposit directory was created and, optionally, asynchronous download of digital objects.</sword:treatment><br />
<br />
<link rel="alternate" href="http://www.swordserver.ac.uk/col1/mydeposit.html"/><br />
<link rel="edit-media" href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/media/"/><br />
<link rel="edit" href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/" /><br />
<link rel="http://purl.org/net/sword/terms/add" href="http://192.168.1.76:8000/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/" /><br />
<link rel="http://purl.org/net/sword/terms/statement" type="application/atom+xml;type=feed"<br />
href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/state/" /><br />
</entry><br />
</pre><br />
<br />
=== Add Files to a Transfer ===<br />
<br />
Posting file metadata (not yet implemented):<br />
* POST a METS file to the SE-IRI, listed below.<br />
* HTTP headers are required similar to Create Transfer call (above).<br />
* Body must include a valid Atom Entry document, that has METS embedded inside it.<br />
<br />
Posts file data:<br />
* It is possible to also POST the actual file to a deposit location's EM-IRI (/api/v1/location/[location UUID]/sword/media/)<br />
* The file should be posted as the request body and the filename specified using the Content-Disposition header (as per RFC 6266): for example "Content-Disposition: Attachment; filename=dog.jpg"<br />
* An MD5 checksum for an uploaded file can be provided via the Content-MD5 header (as per RFC 1544): for example "Content-MD5: Q2hlY2sgSW50ZWdyaXR5IQ=="<br />
* If only an Atom Entry Document is POST'ed, Archivematica will look for uri's in the file StructMap section of the METS file, and attempt to GET each file listed, to include in the Transfer. (not yet implemented)<br />
<br />
=== Finalize a Transfer ===<br />
* POST with no body to the SE-IRI<br />
* set In-Progress HTTP header to : false<br />
* This will tell Archivematica that no further content will be added or removed from the Transfer. <br />
* Archivematica will finish fetching any files that were added previously, and once they have all been downloaded, the Transfer will start through the Archivematica pipeline.<br />
<br />
'''Example'''<br />
<pre><br />
POST http://localhost/api/v1/location/55ce8053-113a-4954-8aa3-fc9771da0bda/sword/ HTTP/1.1<br />
Host: localhost<br />
Authorization: Archivematica-API api_key="XXXXXXXXXXXXXXXXXXXX", username="timh"<br />
Content-Length: 0<br />
Content-Type: application/atom+xml;type=entry<br />
In-Progress: false<br />
</pre><br />
<br />
The response will be HTTP 200/OK or 400/Error (400 if the Transfer was already finalized). If the transfer doesn't exist the response will be HTTP 404.<br />
<br />
=== Get Status of Transfer ===<br />
To check Status:<br />
<br />
GET the State-IRI<br />
in this example:<br />
<br />
GET http://localhost/api/v1/location/09224ddb-4c7d-404c-9218-2f2e1b5a599e/sword/state/ HTTP/1.1<br />
<br />
response will include:<br />
<pre><atom:feed xmlns:sword="http://purl.org/net/sword/terms/" <br />
xmlns:atom="http://www.w3.org/2005/Atom"><br />
<br />
<atom:category scheme="http://purl.org/net/sword/terms/state"<br />
term="failed"<br />
label="State"><br />
Deposit initiation: Failed<br />
</atom:category><br />
<br />
</atom:feed></pre><br />
the list of possible descriptions is not finalized.<br />
<br />
The state term value will either be "processing" (asynchronous deposit still working), "complete" (ready to be finalized), or "failed" (asynchronous deposit encountered an error).<br />
<br />
== Additional Details == <br />
<br />
=== Transfer Details ===<br />
* redirect to Edit-IRI<br />
* used to get basic info about a Transfer with HTTP GET<br />
* can update basic info using HTTP PUT (not yet implemented)<br />
* can allow deletion with HTTP DELETE<br />
* follows the form: /api/v1/location/[deposit location UUID]/sword/<br />
* example: http://192.168.1.231:8000/api/v1/location/09224ddb-4c7d-404c-9218-2f2e1b5a599e/sword/<br />
<br />
=== EM-IRI ===<br />
* Edit-Media IRI <br />
* used to add new objects to an existing transfer<br />
* follows the form: [archivematica hostname]/api/v2/transfer/[uuid of transfer]/media<br />
* example: /api/v1/location/[deposit location UUID]/sword/media/<br />
<br />
An HTTP POST to the em-iri for a transfer should include a file as the body<br />
<br />
An HTTP GET should return a list of files in the transfer<br />
<br />
An HTTP DELETE to the em-iri will remove all digital objects from the Transfer. This is a valid operation only while the Transfer is being assembled. Once the Transfer has been finalized, attempting to DELETE will return an error.<br />
<br />
=== Edit-IRI ===<br />
The client can replace the metadata of a resource by performing an HTTP PUT of a new Atom Entry on the Edit-IRI. (not yet implemented)<br />
<br />
This would be used to update metadata about a transfer, such as the transfer name.<br />
<br />
* example: http://localhost/api/v2/transfer/1225c695-cfb8-4ebb-aaaa-80da344efa6a/edit<br />
<br />
=== SE-IRI ===<br />
* example: http://localhost/api/v2/transfer/add/1225c695-cfb8-4ebb-aaaa-80da344efa6a (not yet implemented)<br />
<br />
=== State-IRI ===<br />
* used to retrieve status of transfer<br />
* implemented as Atom document<br />
* example: /api/v1/location/[deposit location UUID]/sword/state/<br />
* should be able to subscribe like RSS feed<br />
<br />
=== Service document ===</div>Mcantelonhttps://wiki.archivematica.org/index.php?title=Sword_API&diff=9328Sword API2014-01-10T22:32:43Z<p>Mcantelon: /* Example session */</p>
<hr />
<div><br />
== Overview ==<br />
<br />
One of the 1.1 release features is a sponsored project to integrate Archivematica with Islandora. This integration will be accomplished by creating a [http://swordapp.org Sword] 2.0 API for the Archivematica [https://www.archivematica.org/wiki/Administrator_manual_1.0#Storage_service storage service]. Islandora development work will add functionality to Islandora to use this API to deposit digital objects into Archviematica.<br />
<br />
As described [[Overview|elsewhere]] on this wiki, ''"the primary function of Archivematica is to process digital transfers (accessioned digital objects), turn them into SIPs, apply format policies and create high-quality, repository-independent Archival Information Packages (AIP)"''.<br />
<br />
The Archivematica Sword API allows 3rd party applications to automate the process of creating Transfers. <br />
#Create Transfer - set the name and other metadata about a Transfer<br />
#Populate Transfer - add/edit/update digital objects in a Transfer, and associated metadata<br />
#Finalize Transfer - indicates that the Transfer is ready to start processing.<br />
<br />
After content has been deposited, if users have access to the deposit directory they can also manually manipulate the deposit directory aside from any manipulation using the API.<br />
<br />
Once a Transfer has been created, populated and finalized, Archivematica will begin processing that Transfer.<br />
<br />
== Configuration ==<br />
<br />
The SWORD API is part of the Archivematica storage service REST API. The storage service also talks to the Archivematica dashboard, however, to notify it that a, transfer created from a SWORD deposit, has been approved for processing.<br />
<br />
To use the SWORD API you must install the Archivematica dashboard 1.0 branch and the Archivematica storage service dev/issue-5980-islandora branch.<br />
<br />
Dashboard configuration:<br />
<br />
# In dashboard REST API administration, add the IP of the storage service server to IP whitelist<br />
# In dashboard user administration, take note of username and API key for a dashboard user (example: user "demo" and API key "4e5f32ab2aefd3543e1b19a2de554dd65f90108a")<br />
# In dashboard general admininstration, take note of the dashboard's UUID<br />
<br />
Storage service configuration:<br />
<br />
# In the storage service web interface's Pipelines tab, find the dashboard pipeline (using dashboard's UUID noted during dashboard configuration)<br />
# Enter the dashboard's IP address into the "Remote name" field and the user and API key noted earlier into the "Api username" and "Api key" fields. Click the button to submit these changes.<br />
<br />
After configuration you'll need to find the space UUID of the SWORD server. To do so, in the web interface's Spaces tab, click "View Details and Locations" for the SWORD server. The UUID will be shown at the top of the screen. The UUID is used to figure out the initial API URL to access (for example: "http://localhost:8000/api/v1/space/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/").<br />
<br />
== Example session ==<br />
<br />
Below is an example session using curl to manipulate the API. In the example a deposit is created, a file is added to it, and it is finalized.<br />
<br />
NOTE: The SWORD API is in the process of being moved to the storage service. These URLs may not work.<br />
<br />
<pre># create new deposit<br />
curl -v -H "In-Progress: true" --request POST http://localhost:8000/api/v1/space/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/<br />
# response XML includes endpoints for adding additional files, etc.<br />
<br />
# add a file to the deposit<br />
curl -v -H "Content-Disposition: attachment; filename=mets.xml" --request POST \<br />
--data-binary "@joke.jpg" \<br />
http://127.0.0.1:8000/api/v1/location/9c8b4ac0-0407-4360-a10d-af6c62a48b69/sword/media/<br />
<br />
# finalize transfer and approve processing<br />
curl -v -H "In-Progress: false" --request POST http://127.0.0.1:8000/api/v1/location/149cc29d-6472-4bcf-bee8-f8223bf60580/sword/<br />
</pre><br />
<br />
You might, at some point, want to list the transfers that have been started. The following curl command will do so.<br />
<br />
<pre>curl -v http://localhost:8000/api/v1/location/52bbe770-3f96-4493-8d93-ded54c958c51/sword/collection/</pre><br />
<br />
If you're working on a transfer and want to list what files are included in it, the following curl command will list them.<br />
<br />
<pre># list files in transfer<br />
curl -v http://127.0.0.1:8000/api/v1/location/9c8b4ac0-0407-4360-a10d-af6c62a48b69/sword/media/</pre><br />
<br />
If you've started a deposit, but want to discard it, you can delete the deposit. The following curl command shows an example.<br />
<br />
<pre>curl -v -XDELETE http://127.0.0.1:8000/api/v1/location/149cc29d-6472-4bcf-bee8-f8223bf60580/sword/</pre><br />
<br />
== Synchronous Deposit Examples ==<br />
<br />
If you wanted to deposit a transfer then immediately finalize it you could use something like the following curl command.<br />
<br />
<pre>curl -v -H "In-Progress: false" --data-binary @mets.xml --request POST http://localhost:8000/api/v1/space/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/</pre><br />
<br />
<br />
== Endpoints ==<br />
<br />
=== Service document ===<br />
<br />
The SWORD service document provides information about the SWORD provider's capacities and lists SWORD collections. Archivematica currently includes one SWORD collection to which SWORD deposits can be made: transfers.<br />
<br />
The SWORD service document endpoint is located at /api/v1/sword.<br />
<br />
=== List existing transfers ===<br />
* HTTP Get to the Collection IRI (defined by default as: /api/v1/space/[space UUID]/sword/collection/)<br />
* Transfers are listed as an Atom feed<br />
* Each Atom feed entry contains an "atom:link" element whose href attribute contains the URL needed to get details about the transfer<br />
* optional filters via get parameters (not yet implemented)<br />
<br />
=== Create a new transfer ===<br />
* used to start a new transfer in Archivematica<br />
* HTTP POST of an Atom Entry Document to the Collection IRI (defined by default as: /api/v1/space/[space UUID]/sword/collection/)<br />
<br />
'''Possible HTTP Response Codes'''<br />
* HTTP 200 OK - transfer already exists (not yet implemented)<br />
* HTTP 201 Created - transfer has been accepted<br />
* HTTP 412 Precondition Failed - required metadata missing or invalid<br />
<br />
Valid requests will receive a Sword Deposit Receipt in the body of the response.<br />
<br />
'''Required HTTP Headers'''<br />
The HTTP POST must include certain specific http headers. <br />
<br />
Required by http 1.1 specification:<br />
* Host: Must be set to archivematica host name.<br />
* Content-Length: Must be set to the length of the atom entry document.<br />
* Content-Type: Must be set to "application/atom+xml;type=entry".<br />
<br />
Required by Archivematica. <br />
* Authorization: Must include the api key and username assigned by Archivematica.<br />
<br />
Required by SWORD 2.0 protocol:<br />
* In-Progress: Must be set to "true"<br />
<br />
Optional in SWORD 2.0 protocol:<br />
* On-Behalf-Of: not implemented by Archivematica<br />
* Slug: not implemented by Archivematica<br />
<br />
'''Required in Body'''<br />
The Body of the request must be a valid METS Document. The required fields in an Atom Entry Document are:<br />
* LABEL: used as the transfer name<br />
* id: used as an accession id (not yet implemented)<br />
* author: used as the source of acquisition (not yet implemented)<br />
* summary: not implemented yet. Could be used in the future as a description for the Transfer<br />
* updated: should be set to the current timestamp. <br />
<br />
'''Example'''<br />
Example HTTP POST request:<br />
<pre><br />
POST /api/v1/space/96606387-cc70-4b09-b422-a7220606488d/sword/collection/ HTTP/1.1<br />
Host: localhost<br />
Authorization: Archivematica-API api_key="XXXXXXXXXXXXXXXXXXXX", username="timh"<br />
Content-Length: 213<br />
Content-Type: application/atom+xml;type=entry<br />
In-Progress: true<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<METS:mets EXT_VERSION="1.1" OBJID="islandora:72" LABEL="Cinderella"<br />
xmlns:METS="http://www.loc.gov/METS/"<br />
xmlns:xlink="http://www.w3.org/1999/xlink"<br />
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"<br />
xsi:schemaLocation="http://www.loc.gov/METS/ http://www.fedora.info/definitions/1/0/mets-fedora-ext1-1.xsd"><br />
<METS:fileSec><br />
<METS:fileGrp ID="DATASTREAMS"><br />
<METS:fileGrp ID="OBJ"><br />
<METS:file ID="OBJ.0"><br />
<METS:FLocat xlink:title="Cinderella_(1865).pdf" LOCTYPE="URL"<br />
xlink:href="http://localhost:8080/fedora/get/islandora:72/OBJ/2013-08-12T14:46:43.454Z" /><br />
</METS:file><br />
</METS:fileGrp><br />
</METS:fileGrp><br />
</METS:fileSec><br />
</METS:mets><br />
</pre><br />
<br />
Example Response:<br />
<pre><br />
201 Created<br />
Location: http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/<br />
<br />
<entry xmlns="http://www.w3.org/2005/Atom"<br />
xmlns:sword="http://purl.org/net/sword/"<br />
xmlns:dcterms="http://purl.org/dc/terms/"><br />
<br />
<title>Cinderella</title><br />
<id>91d4f258-0050-4914-9d0c-6a74815358d2</id><br />
<updated></updated><br />
<generator uri="https://www.archivematica.org" version="1.0"/><br />
<br />
<summary>A deposit was started.</summary><br />
<sword:treatment>A deposit directory was created and, optionally, asynchronous download of digital objects.</sword:treatment><br />
<br />
<link rel="alternate" href="http://www.swordserver.ac.uk/col1/mydeposit.html"/><br />
<link rel="edit-media" href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/media/"/><br />
<link rel="edit" href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/" /><br />
<link rel="http://purl.org/net/sword/terms/add" href="http://192.168.1.76:8000/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/" /><br />
<link rel="http://purl.org/net/sword/terms/statement" type="application/atom+xml;type=feed"<br />
href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/state/" /><br />
</entry><br />
</pre><br />
<br />
=== Add Files to a Transfer ===<br />
<br />
Posting file metadata (not yet implemented):<br />
* POST a METS file to the SE-IRI, listed below.<br />
* HTTP headers are required similar to Create Transfer call (above).<br />
* Body must include a valid Atom Entry document, that has METS embedded inside it.<br />
<br />
Posts file data:<br />
* It is possible to also POST the actual file to a deposit location's EM-IRI (/api/v1/location/[location UUID]/sword/media/)<br />
* The file should be posted as the request body and the filename specified using the Content-Disposition header (as per RFC 6266): for example "Content-Disposition: Attachment; filename=dog.jpg"<br />
* An MD5 checksum for an uploaded file can be provided via the Content-MD5 header (as per RFC 1544): for example "Content-MD5: Q2hlY2sgSW50ZWdyaXR5IQ=="<br />
* If only an Atom Entry Document is POST'ed, Archivematica will look for uri's in the file StructMap section of the METS file, and attempt to GET each file listed, to include in the Transfer. (not yet implemented)<br />
<br />
=== Finalize a Transfer ===<br />
* POST with no body to the SE-IRI<br />
* set In-Progress HTTP header to : false<br />
* This will tell Archivematica that no further content will be added or removed from the Transfer. <br />
* Archivematica will finish fetching any files that were added previously, and once they have all been downloaded, the Transfer will start through the Archivematica pipeline.<br />
<br />
'''Example'''<br />
<pre><br />
POST http://localhost/api/v1/location/55ce8053-113a-4954-8aa3-fc9771da0bda/sword/ HTTP/1.1<br />
Host: localhost<br />
Authorization: Archivematica-API api_key="XXXXXXXXXXXXXXXXXXXX", username="timh"<br />
Content-Length: 0<br />
Content-Type: application/atom+xml;type=entry<br />
In-Progress: false<br />
</pre><br />
<br />
The response will be HTTP 200/OK or 400/Error (400 if the Transfer was already finalized). If the transfer doesn't exist the response will be HTTP 404.<br />
<br />
=== Get Status of Transfer ===<br />
To check Status:<br />
<br />
GET the State-IRI<br />
in this example:<br />
<br />
GET http://localhost/api/v1/location/09224ddb-4c7d-404c-9218-2f2e1b5a599e/sword/state/ HTTP/1.1<br />
<br />
response will include:<br />
<pre><atom:feed xmlns:sword="http://purl.org/net/sword/terms/" <br />
xmlns:atom="http://www.w3.org/2005/Atom"><br />
<br />
<atom:category scheme="http://purl.org/net/sword/terms/state"<br />
term="failed"<br />
label="State"><br />
Deposit initiation: Failed<br />
</atom:category><br />
<br />
</atom:feed></pre><br />
the list of possible descriptions is not finalized.<br />
<br />
The state term value will either be "processing" (asynchronous deposit still working), "complete" (ready to be finalized), or "failed" (asynchronous deposit encountered an error).<br />
<br />
== Additional Details == <br />
<br />
=== Transfer Details ===<br />
* redirect to Edit-IRI<br />
* used to get basic info about a Transfer with HTTP GET<br />
* can update basic info using HTTP PUT (not yet implemented)<br />
* can allow deletion with HTTP DELETE<br />
* follows the form: /api/v1/location/[deposit location UUID]/sword/<br />
* example: http://192.168.1.231:8000/api/v1/location/09224ddb-4c7d-404c-9218-2f2e1b5a599e/sword/<br />
<br />
=== EM-IRI ===<br />
* Edit-Media IRI <br />
* used to add new objects to an existing transfer<br />
* follows the form: [archivematica hostname]/api/v2/transfer/[uuid of transfer]/media<br />
* example: /api/v1/location/[deposit location UUID]/sword/media/<br />
<br />
An HTTP POST to the em-iri for a transfer should include a file as the body<br />
<br />
An HTTP GET should return a list of files in the transfer<br />
<br />
An HTTP DELETE to the em-iri will remove all digital objects from the Transfer. This is a valid operation only while the Transfer is being assembled. Once the Transfer has been finalized, attempting to DELETE will return an error.<br />
<br />
=== Edit-IRI ===<br />
The client can replace the metadata of a resource by performing an HTTP PUT of a new Atom Entry on the Edit-IRI. (not yet implemented)<br />
<br />
This would be used to update metadata about a transfer, such as the transfer name.<br />
<br />
* example: http://localhost/api/v2/transfer/1225c695-cfb8-4ebb-aaaa-80da344efa6a/edit<br />
<br />
=== SE-IRI ===<br />
* example: http://localhost/api/v2/transfer/add/1225c695-cfb8-4ebb-aaaa-80da344efa6a (not yet implemented)<br />
<br />
=== State-IRI ===<br />
* used to retrieve status of transfer<br />
* implemented as Atom document<br />
* example: /api/v1/location/[deposit location UUID]/sword/state/<br />
* should be able to subscribe like RSS feed<br />
<br />
=== Service document ===</div>Mcantelonhttps://wiki.archivematica.org/index.php?title=Sword_API&diff=9327Sword API2014-01-10T22:27:28Z<p>Mcantelon: /* Example session */</p>
<hr />
<div><br />
== Overview ==<br />
<br />
One of the 1.1 release features is a sponsored project to integrate Archivematica with Islandora. This integration will be accomplished by creating a [http://swordapp.org Sword] 2.0 API for the Archivematica [https://www.archivematica.org/wiki/Administrator_manual_1.0#Storage_service storage service]. Islandora development work will add functionality to Islandora to use this API to deposit digital objects into Archviematica.<br />
<br />
As described [[Overview|elsewhere]] on this wiki, ''"the primary function of Archivematica is to process digital transfers (accessioned digital objects), turn them into SIPs, apply format policies and create high-quality, repository-independent Archival Information Packages (AIP)"''.<br />
<br />
The Archivematica Sword API allows 3rd party applications to automate the process of creating Transfers. <br />
#Create Transfer - set the name and other metadata about a Transfer<br />
#Populate Transfer - add/edit/update digital objects in a Transfer, and associated metadata<br />
#Finalize Transfer - indicates that the Transfer is ready to start processing.<br />
<br />
After content has been deposited, if users have access to the deposit directory they can also manually manipulate the deposit directory aside from any manipulation using the API.<br />
<br />
Once a Transfer has been created, populated and finalized, Archivematica will begin processing that Transfer.<br />
<br />
== Configuration ==<br />
<br />
The SWORD API is part of the Archivematica storage service REST API. The storage service also talks to the Archivematica dashboard, however, to notify it that a, transfer created from a SWORD deposit, has been approved for processing.<br />
<br />
To use the SWORD API you must install the Archivematica dashboard 1.0 branch and the Archivematica storage service dev/issue-5980-islandora branch.<br />
<br />
Dashboard configuration:<br />
<br />
# In dashboard REST API administration, add the IP of the storage service server to IP whitelist<br />
# In dashboard user administration, take note of username and API key for a dashboard user (example: user "demo" and API key "4e5f32ab2aefd3543e1b19a2de554dd65f90108a")<br />
# In dashboard general admininstration, take note of the dashboard's UUID<br />
<br />
Storage service configuration:<br />
<br />
# In the storage service web interface's Pipelines tab, find the dashboard pipeline (using dashboard's UUID noted during dashboard configuration)<br />
# Enter the dashboard's IP address into the "Remote name" field and the user and API key noted earlier into the "Api username" and "Api key" fields. Click the button to submit these changes.<br />
<br />
After configuration you'll need to find the space UUID of the SWORD server. To do so, in the web interface's Spaces tab, click "View Details and Locations" for the SWORD server. The UUID will be shown at the top of the screen. The UUID is used to figure out the initial API URL to access (for example: "http://localhost:8000/api/v1/space/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/").<br />
<br />
== Example session ==<br />
<br />
Below is an example session using curl to manipulate the API. In the example a deposit is created, a file is added to it, and it is finalized.<br />
<br />
NOTE: The SWORD API is in the process of being moved to the storage service. These URLs may not work.<br />
<br />
<pre># create new deposit<br />
curl -v -H "In-Progress: true" --request POST http://localhost:8000/api/v1/space/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/<br />
# response XML includes endpoints for adding additional files, etc.<br />
<br />
# add another file to the transfer<br />
curl -v -H "Content-Disposition: attachment; filename=mets.xml" --request POST \<br />
--data-binary "@joke.jpg" \<br />
http://127.0.0.1:8000/api/v1/location/9c8b4ac0-0407-4360-a10d-af6c62a48b69/sword/media/<br />
<br />
# finalize transfer and approve processing<br />
curl -v -H "In-Progress: false" --request POST http://127.0.0.1:8000/api/v1/location/149cc29d-6472-4bcf-bee8-f8223bf60580/sword/<br />
</pre><br />
<br />
You might, at some point, want to list the transfers that have been started. The following curl command will do so.<br />
<br />
<pre>curl -v http://localhost:8000/api/v1/location/52bbe770-3f96-4493-8d93-ded54c958c51/sword/collection/</pre><br />
<br />
If you're working on a transfer and want to list what files are included in it, the following curl command will list them.<br />
<br />
<pre># list files in transfer<br />
curl -v http://127.0.0.1:8000/api/v1/location/9c8b4ac0-0407-4360-a10d-af6c62a48b69/sword/media/</pre><br />
<br />
If you've started a deposit, but want to discard it, you can delete the deposit. The following curl command shows an example.<br />
<br />
<pre>curl -v -XDELETE http://127.0.0.1:8000/api/v1/location/149cc29d-6472-4bcf-bee8-f8223bf60580/sword/</pre><br />
<br />
== Synchronous Deposit Examples ==<br />
<br />
If you wanted to deposit a transfer then immediately finalize it you could use something like the following curl command.<br />
<br />
<pre>curl -v -H "In-Progress: false" --data-binary @mets.xml --request POST http://localhost:8000/api/v1/space/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/</pre><br />
<br />
<br />
== Endpoints ==<br />
<br />
=== Service document ===<br />
<br />
The SWORD service document provides information about the SWORD provider's capacities and lists SWORD collections. Archivematica currently includes one SWORD collection to which SWORD deposits can be made: transfers.<br />
<br />
The SWORD service document endpoint is located at /api/v1/sword.<br />
<br />
=== List existing transfers ===<br />
* HTTP Get to the Collection IRI (defined by default as: /api/v1/space/[space UUID]/sword/collection/)<br />
* Transfers are listed as an Atom feed<br />
* Each Atom feed entry contains an "atom:link" element whose href attribute contains the URL needed to get details about the transfer<br />
* optional filters via get parameters (not yet implemented)<br />
<br />
=== Create a new transfer ===<br />
* used to start a new transfer in Archivematica<br />
* HTTP POST of an Atom Entry Document to the Collection IRI (defined by default as: /api/v1/space/[space UUID]/sword/collection/)<br />
<br />
'''Possible HTTP Response Codes'''<br />
* HTTP 200 OK - transfer already exists (not yet implemented)<br />
* HTTP 201 Created - transfer has been accepted<br />
* HTTP 412 Precondition Failed - required metadata missing or invalid<br />
<br />
Valid requests will receive a Sword Deposit Receipt in the body of the response.<br />
<br />
'''Required HTTP Headers'''<br />
The HTTP POST must include certain specific http headers. <br />
<br />
Required by http 1.1 specification:<br />
* Host: Must be set to archivematica host name.<br />
* Content-Length: Must be set to the length of the atom entry document.<br />
* Content-Type: Must be set to "application/atom+xml;type=entry".<br />
<br />
Required by Archivematica. <br />
* Authorization: Must include the api key and username assigned by Archivematica.<br />
<br />
Required by SWORD 2.0 protocol:<br />
* In-Progress: Must be set to "true"<br />
<br />
Optional in SWORD 2.0 protocol:<br />
* On-Behalf-Of: not implemented by Archivematica<br />
* Slug: not implemented by Archivematica<br />
<br />
'''Required in Body'''<br />
The Body of the request must be a valid METS Document. The required fields in an Atom Entry Document are:<br />
* LABEL: used as the transfer name<br />
* id: used as an accession id (not yet implemented)<br />
* author: used as the source of acquisition (not yet implemented)<br />
* summary: not implemented yet. Could be used in the future as a description for the Transfer<br />
* updated: should be set to the current timestamp. <br />
<br />
'''Example'''<br />
Example HTTP POST request:<br />
<pre><br />
POST /api/v1/space/96606387-cc70-4b09-b422-a7220606488d/sword/collection/ HTTP/1.1<br />
Host: localhost<br />
Authorization: Archivematica-API api_key="XXXXXXXXXXXXXXXXXXXX", username="timh"<br />
Content-Length: 213<br />
Content-Type: application/atom+xml;type=entry<br />
In-Progress: true<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<METS:mets EXT_VERSION="1.1" OBJID="islandora:72" LABEL="Cinderella"<br />
xmlns:METS="http://www.loc.gov/METS/"<br />
xmlns:xlink="http://www.w3.org/1999/xlink"<br />
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"<br />
xsi:schemaLocation="http://www.loc.gov/METS/ http://www.fedora.info/definitions/1/0/mets-fedora-ext1-1.xsd"><br />
<METS:fileSec><br />
<METS:fileGrp ID="DATASTREAMS"><br />
<METS:fileGrp ID="OBJ"><br />
<METS:file ID="OBJ.0"><br />
<METS:FLocat xlink:title="Cinderella_(1865).pdf" LOCTYPE="URL"<br />
xlink:href="http://localhost:8080/fedora/get/islandora:72/OBJ/2013-08-12T14:46:43.454Z" /><br />
</METS:file><br />
</METS:fileGrp><br />
</METS:fileGrp><br />
</METS:fileSec><br />
</METS:mets><br />
</pre><br />
<br />
Example Response:<br />
<pre><br />
201 Created<br />
Location: http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/<br />
<br />
<entry xmlns="http://www.w3.org/2005/Atom"<br />
xmlns:sword="http://purl.org/net/sword/"<br />
xmlns:dcterms="http://purl.org/dc/terms/"><br />
<br />
<title>Cinderella</title><br />
<id>91d4f258-0050-4914-9d0c-6a74815358d2</id><br />
<updated></updated><br />
<generator uri="https://www.archivematica.org" version="1.0"/><br />
<br />
<summary>A deposit was started.</summary><br />
<sword:treatment>A deposit directory was created and, optionally, asynchronous download of digital objects.</sword:treatment><br />
<br />
<link rel="alternate" href="http://www.swordserver.ac.uk/col1/mydeposit.html"/><br />
<link rel="edit-media" href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/media/"/><br />
<link rel="edit" href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/" /><br />
<link rel="http://purl.org/net/sword/terms/add" href="http://192.168.1.76:8000/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/" /><br />
<link rel="http://purl.org/net/sword/terms/statement" type="application/atom+xml;type=feed"<br />
href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/state/" /><br />
</entry><br />
</pre><br />
<br />
=== Add Files to a Transfer ===<br />
<br />
Posting file metadata (not yet implemented):<br />
* POST a METS file to the SE-IRI, listed below.<br />
* HTTP headers are required similar to Create Transfer call (above).<br />
* Body must include a valid Atom Entry document, that has METS embedded inside it.<br />
<br />
Posts file data:<br />
* It is possible to also POST the actual file to a deposit location's EM-IRI (/api/v1/location/[location UUID]/sword/media/)<br />
* The file should be posted as the request body and the filename specified using the Content-Disposition header (as per RFC 6266): for example "Content-Disposition: Attachment; filename=dog.jpg"<br />
* An MD5 checksum for an uploaded file can be provided via the Content-MD5 header (as per RFC 1544): for example "Content-MD5: Q2hlY2sgSW50ZWdyaXR5IQ=="<br />
* If only an Atom Entry Document is POST'ed, Archivematica will look for uri's in the file StructMap section of the METS file, and attempt to GET each file listed, to include in the Transfer. (not yet implemented)<br />
<br />
=== Finalize a Transfer ===<br />
* POST with no body to the SE-IRI<br />
* set In-Progress HTTP header to : false<br />
* This will tell Archivematica that no further content will be added or removed from the Transfer. <br />
* Archivematica will finish fetching any files that were added previously, and once they have all been downloaded, the Transfer will start through the Archivematica pipeline.<br />
<br />
'''Example'''<br />
<pre><br />
POST http://localhost/api/v1/location/55ce8053-113a-4954-8aa3-fc9771da0bda/sword/ HTTP/1.1<br />
Host: localhost<br />
Authorization: Archivematica-API api_key="XXXXXXXXXXXXXXXXXXXX", username="timh"<br />
Content-Length: 0<br />
Content-Type: application/atom+xml;type=entry<br />
In-Progress: false<br />
</pre><br />
<br />
The response will be HTTP 200/OK or 400/Error (400 if the Transfer was already finalized). If the transfer doesn't exist the response will be HTTP 404.<br />
<br />
=== Get Status of Transfer ===<br />
To check Status:<br />
<br />
GET the State-IRI<br />
in this example:<br />
<br />
GET http://localhost/api/v1/location/09224ddb-4c7d-404c-9218-2f2e1b5a599e/sword/state/ HTTP/1.1<br />
<br />
response will include:<br />
<pre><atom:feed xmlns:sword="http://purl.org/net/sword/terms/" <br />
xmlns:atom="http://www.w3.org/2005/Atom"><br />
<br />
<atom:category scheme="http://purl.org/net/sword/terms/state"<br />
term="failed"<br />
label="State"><br />
Deposit initiation: Failed<br />
</atom:category><br />
<br />
</atom:feed></pre><br />
the list of possible descriptions is not finalized.<br />
<br />
The state term value will either be "processing" (asynchronous deposit still working), "complete" (ready to be finalized), or "failed" (asynchronous deposit encountered an error).<br />
<br />
== Additional Details == <br />
<br />
=== Transfer Details ===<br />
* redirect to Edit-IRI<br />
* used to get basic info about a Transfer with HTTP GET<br />
* can update basic info using HTTP PUT (not yet implemented)<br />
* can allow deletion with HTTP DELETE<br />
* follows the form: /api/v1/location/[deposit location UUID]/sword/<br />
* example: http://192.168.1.231:8000/api/v1/location/09224ddb-4c7d-404c-9218-2f2e1b5a599e/sword/<br />
<br />
=== EM-IRI ===<br />
* Edit-Media IRI <br />
* used to add new objects to an existing transfer<br />
* follows the form: [archivematica hostname]/api/v2/transfer/[uuid of transfer]/media<br />
* example: /api/v1/location/[deposit location UUID]/sword/media/<br />
<br />
An HTTP POST to the em-iri for a transfer should include a file as the body<br />
<br />
An HTTP GET should return a list of files in the transfer<br />
<br />
An HTTP DELETE to the em-iri will remove all digital objects from the Transfer. This is a valid operation only while the Transfer is being assembled. Once the Transfer has been finalized, attempting to DELETE will return an error.<br />
<br />
=== Edit-IRI ===<br />
The client can replace the metadata of a resource by performing an HTTP PUT of a new Atom Entry on the Edit-IRI. (not yet implemented)<br />
<br />
This would be used to update metadata about a transfer, such as the transfer name.<br />
<br />
* example: http://localhost/api/v2/transfer/1225c695-cfb8-4ebb-aaaa-80da344efa6a/edit<br />
<br />
=== SE-IRI ===<br />
* example: http://localhost/api/v2/transfer/add/1225c695-cfb8-4ebb-aaaa-80da344efa6a (not yet implemented)<br />
<br />
=== State-IRI ===<br />
* used to retrieve status of transfer<br />
* implemented as Atom document<br />
* example: /api/v1/location/[deposit location UUID]/sword/state/<br />
* should be able to subscribe like RSS feed<br />
<br />
=== Service document ===</div>Mcantelonhttps://wiki.archivematica.org/index.php?title=Sword_API&diff=9326Sword API2014-01-10T22:03:42Z<p>Mcantelon: /* Configuration */</p>
<hr />
<div><br />
== Overview ==<br />
<br />
One of the 1.1 release features is a sponsored project to integrate Archivematica with Islandora. This integration will be accomplished by creating a [http://swordapp.org Sword] 2.0 API for the Archivematica [https://www.archivematica.org/wiki/Administrator_manual_1.0#Storage_service storage service]. Islandora development work will add functionality to Islandora to use this API to deposit digital objects into Archviematica.<br />
<br />
As described [[Overview|elsewhere]] on this wiki, ''"the primary function of Archivematica is to process digital transfers (accessioned digital objects), turn them into SIPs, apply format policies and create high-quality, repository-independent Archival Information Packages (AIP)"''.<br />
<br />
The Archivematica Sword API allows 3rd party applications to automate the process of creating Transfers. <br />
#Create Transfer - set the name and other metadata about a Transfer<br />
#Populate Transfer - add/edit/update digital objects in a Transfer, and associated metadata<br />
#Finalize Transfer - indicates that the Transfer is ready to start processing.<br />
<br />
After content has been deposited, if users have access to the deposit directory they can also manually manipulate the deposit directory aside from any manipulation using the API.<br />
<br />
Once a Transfer has been created, populated and finalized, Archivematica will begin processing that Transfer.<br />
<br />
== Configuration ==<br />
<br />
The SWORD API is part of the Archivematica storage service REST API. The storage service also talks to the Archivematica dashboard, however, to notify it that a, transfer created from a SWORD deposit, has been approved for processing.<br />
<br />
To use the SWORD API you must install the Archivematica dashboard 1.0 branch and the Archivematica storage service dev/issue-5980-islandora branch.<br />
<br />
Dashboard configuration:<br />
<br />
# In dashboard REST API administration, add the IP of the storage service server to IP whitelist<br />
# In dashboard user administration, take note of username and API key for a dashboard user (example: user "demo" and API key "4e5f32ab2aefd3543e1b19a2de554dd65f90108a")<br />
# In dashboard general admininstration, take note of the dashboard's UUID<br />
<br />
Storage service configuration:<br />
<br />
# In the storage service web interface's Pipelines tab, find the dashboard pipeline (using dashboard's UUID noted during dashboard configuration)<br />
# Enter the dashboard's IP address into the "Remote name" field and the user and API key noted earlier into the "Api username" and "Api key" fields. Click the button to submit these changes.<br />
<br />
After configuration you'll need to find the space UUID of the SWORD server. To do so, in the web interface's Spaces tab, click "View Details and Locations" for the SWORD server. The UUID will be shown at the top of the screen. The UUID is used to figure out the initial API URL to access (for example: "http://localhost:8000/api/v1/space/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/").<br />
<br />
== Example session ==<br />
<br />
Below is an example session using curl to manipulate the API. In the example a deposit is created, a file is added to it, and it is finalized.<br />
<br />
NOTE: The SWORD API is in the process of being moved to the storage service. These URLs may not work.<br />
<br />
<pre># create new deposit<br />
curl -v -H "In-Progress: false" --data-binary @mets.xml --request POST http://localhost:8000/api/v1/space/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/<br />
# response XML includes endpoints for adding addition files, etc.<br />
<br />
# add another file to the transfer<br />
curl -v -H "Content-Disposition: attachment; filename=joke.jpg" --request POST \<br />
--data-binary "@joke.jpg" \<br />
http://127.0.0.1:8000/api/v1/location/9c8b4ac0-0407-4360-a10d-af6c62a48b69/sword/media/<br />
<br />
# finalize transfer and approve processing<br />
curl -v -H "In-Progress: false" --request POST http://127.0.0.1:8000/api/v1/location/149cc29d-6472-4bcf-bee8-f8223bf60580/sword/<br />
</pre><br />
<br />
You might, at some point, want to list the transfers that have been started. The following curl command will do so.<br />
<br />
<pre>curl -v http://localhost:8000/api/v1/location/52bbe770-3f96-4493-8d93-ded54c958c51/sword/collection/</pre><br />
<br />
If you're working on a transfer and want to list what files are included in it, the following curl command will list them.<br />
<br />
<pre># list files in transfer<br />
curl -v http://127.0.0.1:8000/api/v1/location/9c8b4ac0-0407-4360-a10d-af6c62a48b69/sword/media/</pre><br />
<br />
If you've started a deposit, but want to discard it, you can delete the deposit. The following curl command shows an example.<br />
<br />
<pre>curl -v -XDELETE http://127.0.0.1:8000/api/v1/location/149cc29d-6472-4bcf-bee8-f8223bf60580/sword/</pre><br />
<br />
== Synchronous Deposit Examples ==<br />
<br />
If you wanted to deposit a transfer then immediately finalize it you could use something like the following curl command.<br />
<br />
<pre>curl -v -H "In-Progress: false" --data-binary @mets.xml --request POST http://localhost:8000/api/v1/space/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/</pre><br />
<br />
<br />
== Endpoints ==<br />
<br />
=== Service document ===<br />
<br />
The SWORD service document provides information about the SWORD provider's capacities and lists SWORD collections. Archivematica currently includes one SWORD collection to which SWORD deposits can be made: transfers.<br />
<br />
The SWORD service document endpoint is located at /api/v1/sword.<br />
<br />
=== List existing transfers ===<br />
* HTTP Get to the Collection IRI (defined by default as: /api/v1/space/[space UUID]/sword/collection/)<br />
* Transfers are listed as an Atom feed<br />
* Each Atom feed entry contains an "atom:link" element whose href attribute contains the URL needed to get details about the transfer<br />
* optional filters via get parameters (not yet implemented)<br />
<br />
=== Create a new transfer ===<br />
* used to start a new transfer in Archivematica<br />
* HTTP POST of an Atom Entry Document to the Collection IRI (defined by default as: /api/v1/space/[space UUID]/sword/collection/)<br />
<br />
'''Possible HTTP Response Codes'''<br />
* HTTP 200 OK - transfer already exists (not yet implemented)<br />
* HTTP 201 Created - transfer has been accepted<br />
* HTTP 412 Precondition Failed - required metadata missing or invalid<br />
<br />
Valid requests will receive a Sword Deposit Receipt in the body of the response.<br />
<br />
'''Required HTTP Headers'''<br />
The HTTP POST must include certain specific http headers. <br />
<br />
Required by http 1.1 specification:<br />
* Host: Must be set to archivematica host name.<br />
* Content-Length: Must be set to the length of the atom entry document.<br />
* Content-Type: Must be set to "application/atom+xml;type=entry".<br />
<br />
Required by Archivematica. <br />
* Authorization: Must include the api key and username assigned by Archivematica.<br />
<br />
Required by SWORD 2.0 protocol:<br />
* In-Progress: Must be set to "true"<br />
<br />
Optional in SWORD 2.0 protocol:<br />
* On-Behalf-Of: not implemented by Archivematica<br />
* Slug: not implemented by Archivematica<br />
<br />
'''Required in Body'''<br />
The Body of the request must be a valid METS Document. The required fields in an Atom Entry Document are:<br />
* LABEL: used as the transfer name<br />
* id: used as an accession id (not yet implemented)<br />
* author: used as the source of acquisition (not yet implemented)<br />
* summary: not implemented yet. Could be used in the future as a description for the Transfer<br />
* updated: should be set to the current timestamp. <br />
<br />
'''Example'''<br />
Example HTTP POST request:<br />
<pre><br />
POST /api/v1/space/96606387-cc70-4b09-b422-a7220606488d/sword/collection/ HTTP/1.1<br />
Host: localhost<br />
Authorization: Archivematica-API api_key="XXXXXXXXXXXXXXXXXXXX", username="timh"<br />
Content-Length: 213<br />
Content-Type: application/atom+xml;type=entry<br />
In-Progress: true<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<METS:mets EXT_VERSION="1.1" OBJID="islandora:72" LABEL="Cinderella"<br />
xmlns:METS="http://www.loc.gov/METS/"<br />
xmlns:xlink="http://www.w3.org/1999/xlink"<br />
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"<br />
xsi:schemaLocation="http://www.loc.gov/METS/ http://www.fedora.info/definitions/1/0/mets-fedora-ext1-1.xsd"><br />
<METS:fileSec><br />
<METS:fileGrp ID="DATASTREAMS"><br />
<METS:fileGrp ID="OBJ"><br />
<METS:file ID="OBJ.0"><br />
<METS:FLocat xlink:title="Cinderella_(1865).pdf" LOCTYPE="URL"<br />
xlink:href="http://localhost:8080/fedora/get/islandora:72/OBJ/2013-08-12T14:46:43.454Z" /><br />
</METS:file><br />
</METS:fileGrp><br />
</METS:fileGrp><br />
</METS:fileSec><br />
</METS:mets><br />
</pre><br />
<br />
Example Response:<br />
<pre><br />
201 Created<br />
Location: http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/<br />
<br />
<entry xmlns="http://www.w3.org/2005/Atom"<br />
xmlns:sword="http://purl.org/net/sword/"<br />
xmlns:dcterms="http://purl.org/dc/terms/"><br />
<br />
<title>Cinderella</title><br />
<id>91d4f258-0050-4914-9d0c-6a74815358d2</id><br />
<updated></updated><br />
<generator uri="https://www.archivematica.org" version="1.0"/><br />
<br />
<summary>A deposit was started.</summary><br />
<sword:treatment>A deposit directory was created and, optionally, asynchronous download of digital objects.</sword:treatment><br />
<br />
<link rel="alternate" href="http://www.swordserver.ac.uk/col1/mydeposit.html"/><br />
<link rel="edit-media" href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/media/"/><br />
<link rel="edit" href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/" /><br />
<link rel="http://purl.org/net/sword/terms/add" href="http://192.168.1.76:8000/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/" /><br />
<link rel="http://purl.org/net/sword/terms/statement" type="application/atom+xml;type=feed"<br />
href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/state/" /><br />
</entry><br />
</pre><br />
<br />
=== Add Files to a Transfer ===<br />
<br />
Posting file metadata (not yet implemented):<br />
* POST a METS file to the SE-IRI, listed below.<br />
* HTTP headers are required similar to Create Transfer call (above).<br />
* Body must include a valid Atom Entry document, that has METS embedded inside it.<br />
<br />
Posts file data:<br />
* It is possible to also POST the actual file to a deposit location's EM-IRI (/api/v1/location/[location UUID]/sword/media/)<br />
* The file should be posted as the request body and the filename specified using the Content-Disposition header (as per RFC 6266): for example "Content-Disposition: Attachment; filename=dog.jpg"<br />
* An MD5 checksum for an uploaded file can be provided via the Content-MD5 header (as per RFC 1544): for example "Content-MD5: Q2hlY2sgSW50ZWdyaXR5IQ=="<br />
* If only an Atom Entry Document is POST'ed, Archivematica will look for uri's in the file StructMap section of the METS file, and attempt to GET each file listed, to include in the Transfer. (not yet implemented)<br />
<br />
=== Finalize a Transfer ===<br />
* POST with no body to the SE-IRI<br />
* set In-Progress HTTP header to : false<br />
* This will tell Archivematica that no further content will be added or removed from the Transfer. <br />
* Archivematica will finish fetching any files that were added previously, and once they have all been downloaded, the Transfer will start through the Archivematica pipeline.<br />
<br />
'''Example'''<br />
<pre><br />
POST http://localhost/api/v1/location/55ce8053-113a-4954-8aa3-fc9771da0bda/sword/ HTTP/1.1<br />
Host: localhost<br />
Authorization: Archivematica-API api_key="XXXXXXXXXXXXXXXXXXXX", username="timh"<br />
Content-Length: 0<br />
Content-Type: application/atom+xml;type=entry<br />
In-Progress: false<br />
</pre><br />
<br />
The response will be HTTP 200/OK or 400/Error (400 if the Transfer was already finalized). If the transfer doesn't exist the response will be HTTP 404.<br />
<br />
=== Get Status of Transfer ===<br />
To check Status:<br />
<br />
GET the State-IRI<br />
in this example:<br />
<br />
GET http://localhost/api/v1/location/09224ddb-4c7d-404c-9218-2f2e1b5a599e/sword/state/ HTTP/1.1<br />
<br />
response will include:<br />
<pre><atom:feed xmlns:sword="http://purl.org/net/sword/terms/" <br />
xmlns:atom="http://www.w3.org/2005/Atom"><br />
<br />
<atom:category scheme="http://purl.org/net/sword/terms/state"<br />
term="failed"<br />
label="State"><br />
Deposit initiation: Failed<br />
</atom:category><br />
<br />
</atom:feed></pre><br />
the list of possible descriptions is not finalized.<br />
<br />
The state term value will either be "processing" (asynchronous deposit still working), "complete" (ready to be finalized), or "failed" (asynchronous deposit encountered an error).<br />
<br />
== Additional Details == <br />
<br />
=== Transfer Details ===<br />
* redirect to Edit-IRI<br />
* used to get basic info about a Transfer with HTTP GET<br />
* can update basic info using HTTP PUT (not yet implemented)<br />
* can allow deletion with HTTP DELETE<br />
* follows the form: /api/v1/location/[deposit location UUID]/sword/<br />
* example: http://192.168.1.231:8000/api/v1/location/09224ddb-4c7d-404c-9218-2f2e1b5a599e/sword/<br />
<br />
=== EM-IRI ===<br />
* Edit-Media IRI <br />
* used to add new objects to an existing transfer<br />
* follows the form: [archivematica hostname]/api/v2/transfer/[uuid of transfer]/media<br />
* example: /api/v1/location/[deposit location UUID]/sword/media/<br />
<br />
An HTTP POST to the em-iri for a transfer should include a file as the body<br />
<br />
An HTTP GET should return a list of files in the transfer<br />
<br />
An HTTP DELETE to the em-iri will remove all digital objects from the Transfer. This is a valid operation only while the Transfer is being assembled. Once the Transfer has been finalized, attempting to DELETE will return an error.<br />
<br />
=== Edit-IRI ===<br />
The client can replace the metadata of a resource by performing an HTTP PUT of a new Atom Entry on the Edit-IRI. (not yet implemented)<br />
<br />
This would be used to update metadata about a transfer, such as the transfer name.<br />
<br />
* example: http://localhost/api/v2/transfer/1225c695-cfb8-4ebb-aaaa-80da344efa6a/edit<br />
<br />
=== SE-IRI ===<br />
* example: http://localhost/api/v2/transfer/add/1225c695-cfb8-4ebb-aaaa-80da344efa6a (not yet implemented)<br />
<br />
=== State-IRI ===<br />
* used to retrieve status of transfer<br />
* implemented as Atom document<br />
* example: /api/v1/location/[deposit location UUID]/sword/state/<br />
* should be able to subscribe like RSS feed<br />
<br />
=== Service document ===</div>Mcantelonhttps://wiki.archivematica.org/index.php?title=Sword_API&diff=9325Sword API2014-01-10T21:59:57Z<p>Mcantelon: /* Configuration */</p>
<hr />
<div><br />
== Overview ==<br />
<br />
One of the 1.1 release features is a sponsored project to integrate Archivematica with Islandora. This integration will be accomplished by creating a [http://swordapp.org Sword] 2.0 API for the Archivematica [https://www.archivematica.org/wiki/Administrator_manual_1.0#Storage_service storage service]. Islandora development work will add functionality to Islandora to use this API to deposit digital objects into Archviematica.<br />
<br />
As described [[Overview|elsewhere]] on this wiki, ''"the primary function of Archivematica is to process digital transfers (accessioned digital objects), turn them into SIPs, apply format policies and create high-quality, repository-independent Archival Information Packages (AIP)"''.<br />
<br />
The Archivematica Sword API allows 3rd party applications to automate the process of creating Transfers. <br />
#Create Transfer - set the name and other metadata about a Transfer<br />
#Populate Transfer - add/edit/update digital objects in a Transfer, and associated metadata<br />
#Finalize Transfer - indicates that the Transfer is ready to start processing.<br />
<br />
After content has been deposited, if users have access to the deposit directory they can also manually manipulate the deposit directory aside from any manipulation using the API.<br />
<br />
Once a Transfer has been created, populated and finalized, Archivematica will begin processing that Transfer.<br />
<br />
== Configuration ==<br />
<br />
The SWORD API is part of the Archivematica storage service REST API. The storage service also talks to the Archivematica dashboard, however, to notify it that a, transfer created from a SWORD deposit, has been approved for processing.<br />
<br />
To use the SWORD API you must install the Archivematica dashboard 1.0 branch and the Archivematica storage service dev/issue-5980-islandora branch.<br />
<br />
Dashboard configuration:<br />
<br />
# In dashboard REST API administration, add the IP of the storage service server to IP whitelist<br />
# In dashboard user administration, take note of username and API key for a dashboard user (example: user "demo" and API key "4e5f32ab2aefd3543e1b19a2de554dd65f90108a")<br />
# In dashboard general admininstration, take note of the dashboard's UUID<br />
<br />
Storage service configuration:<br />
<br />
# In the storage service web interface's Pipelines tab, find the dashboard pipeline (using dashboard's UUID noted during dashboard configuration)<br />
# Enter the dashboard's IP address into the "Remote name" field and the user and API key noted earlier into the "Api username" and "Api key" fields. Click the button to submit these changes.<br />
<br />
Finding the space UUID of the SWORD server:<br />
<br />
# In the web interface's Spaces tab, click "View Details and Locations" for the SWORD server. The UUID will be shown at the top of the screen.<br />
<br />
== Example session ==<br />
<br />
Below is an example session using curl to manipulate the API. In the example a deposit is created, a file is added to it, and it is finalized.<br />
<br />
NOTE: The SWORD API is in the process of being moved to the storage service. These URLs may not work.<br />
<br />
<pre># create new deposit<br />
curl -v -H "In-Progress: false" --data-binary @mets.xml --request POST http://localhost:8000/api/v1/space/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/<br />
# response XML includes endpoints for adding addition files, etc.<br />
<br />
# add another file to the transfer<br />
curl -v -H "Content-Disposition: attachment; filename=joke.jpg" --request POST \<br />
--data-binary "@joke.jpg" \<br />
http://127.0.0.1:8000/api/v1/location/9c8b4ac0-0407-4360-a10d-af6c62a48b69/sword/media/<br />
<br />
# finalize transfer and approve processing<br />
curl -v -H "In-Progress: false" --request POST http://127.0.0.1:8000/api/v1/location/149cc29d-6472-4bcf-bee8-f8223bf60580/sword/<br />
</pre><br />
<br />
You might, at some point, want to list the transfers that have been started. The following curl command will do so.<br />
<br />
<pre>curl -v http://localhost:8000/api/v1/location/52bbe770-3f96-4493-8d93-ded54c958c51/sword/collection/</pre><br />
<br />
If you're working on a transfer and want to list what files are included in it, the following curl command will list them.<br />
<br />
<pre># list files in transfer<br />
curl -v http://127.0.0.1:8000/api/v1/location/9c8b4ac0-0407-4360-a10d-af6c62a48b69/sword/media/</pre><br />
<br />
If you've started a deposit, but want to discard it, you can delete the deposit. The following curl command shows an example.<br />
<br />
<pre>curl -v -XDELETE http://127.0.0.1:8000/api/v1/location/149cc29d-6472-4bcf-bee8-f8223bf60580/sword/</pre><br />
<br />
== Synchronous Deposit Examples ==<br />
<br />
If you wanted to deposit a transfer then immediately finalize it you could use something like the following curl command.<br />
<br />
<pre>curl -v -H "In-Progress: false" --data-binary @mets.xml --request POST http://localhost:8000/api/v1/space/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/</pre><br />
<br />
<br />
== Endpoints ==<br />
<br />
=== Service document ===<br />
<br />
The SWORD service document provides information about the SWORD provider's capacities and lists SWORD collections. Archivematica currently includes one SWORD collection to which SWORD deposits can be made: transfers.<br />
<br />
The SWORD service document endpoint is located at /api/v1/sword.<br />
<br />
=== List existing transfers ===<br />
* HTTP Get to the Collection IRI (defined by default as: /api/v1/space/[space UUID]/sword/collection/)<br />
* Transfers are listed as an Atom feed<br />
* Each Atom feed entry contains an "atom:link" element whose href attribute contains the URL needed to get details about the transfer<br />
* optional filters via get parameters (not yet implemented)<br />
<br />
=== Create a new transfer ===<br />
* used to start a new transfer in Archivematica<br />
* HTTP POST of an Atom Entry Document to the Collection IRI (defined by default as: /api/v1/space/[space UUID]/sword/collection/)<br />
<br />
'''Possible HTTP Response Codes'''<br />
* HTTP 200 OK - transfer already exists (not yet implemented)<br />
* HTTP 201 Created - transfer has been accepted<br />
* HTTP 412 Precondition Failed - required metadata missing or invalid<br />
<br />
Valid requests will receive a Sword Deposit Receipt in the body of the response.<br />
<br />
'''Required HTTP Headers'''<br />
The HTTP POST must include certain specific http headers. <br />
<br />
Required by http 1.1 specification:<br />
* Host: Must be set to archivematica host name.<br />
* Content-Length: Must be set to the length of the atom entry document.<br />
* Content-Type: Must be set to "application/atom+xml;type=entry".<br />
<br />
Required by Archivematica. <br />
* Authorization: Must include the api key and username assigned by Archivematica.<br />
<br />
Required by SWORD 2.0 protocol:<br />
* In-Progress: Must be set to "true"<br />
<br />
Optional in SWORD 2.0 protocol:<br />
* On-Behalf-Of: not implemented by Archivematica<br />
* Slug: not implemented by Archivematica<br />
<br />
'''Required in Body'''<br />
The Body of the request must be a valid METS Document. The required fields in an Atom Entry Document are:<br />
* LABEL: used as the transfer name<br />
* id: used as an accession id (not yet implemented)<br />
* author: used as the source of acquisition (not yet implemented)<br />
* summary: not implemented yet. Could be used in the future as a description for the Transfer<br />
* updated: should be set to the current timestamp. <br />
<br />
'''Example'''<br />
Example HTTP POST request:<br />
<pre><br />
POST /api/v1/space/96606387-cc70-4b09-b422-a7220606488d/sword/collection/ HTTP/1.1<br />
Host: localhost<br />
Authorization: Archivematica-API api_key="XXXXXXXXXXXXXXXXXXXX", username="timh"<br />
Content-Length: 213<br />
Content-Type: application/atom+xml;type=entry<br />
In-Progress: true<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<METS:mets EXT_VERSION="1.1" OBJID="islandora:72" LABEL="Cinderella"<br />
xmlns:METS="http://www.loc.gov/METS/"<br />
xmlns:xlink="http://www.w3.org/1999/xlink"<br />
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"<br />
xsi:schemaLocation="http://www.loc.gov/METS/ http://www.fedora.info/definitions/1/0/mets-fedora-ext1-1.xsd"><br />
<METS:fileSec><br />
<METS:fileGrp ID="DATASTREAMS"><br />
<METS:fileGrp ID="OBJ"><br />
<METS:file ID="OBJ.0"><br />
<METS:FLocat xlink:title="Cinderella_(1865).pdf" LOCTYPE="URL"<br />
xlink:href="http://localhost:8080/fedora/get/islandora:72/OBJ/2013-08-12T14:46:43.454Z" /><br />
</METS:file><br />
</METS:fileGrp><br />
</METS:fileGrp><br />
</METS:fileSec><br />
</METS:mets><br />
</pre><br />
<br />
Example Response:<br />
<pre><br />
201 Created<br />
Location: http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/<br />
<br />
<entry xmlns="http://www.w3.org/2005/Atom"<br />
xmlns:sword="http://purl.org/net/sword/"<br />
xmlns:dcterms="http://purl.org/dc/terms/"><br />
<br />
<title>Cinderella</title><br />
<id>91d4f258-0050-4914-9d0c-6a74815358d2</id><br />
<updated></updated><br />
<generator uri="https://www.archivematica.org" version="1.0"/><br />
<br />
<summary>A deposit was started.</summary><br />
<sword:treatment>A deposit directory was created and, optionally, asynchronous download of digital objects.</sword:treatment><br />
<br />
<link rel="alternate" href="http://www.swordserver.ac.uk/col1/mydeposit.html"/><br />
<link rel="edit-media" href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/media/"/><br />
<link rel="edit" href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/" /><br />
<link rel="http://purl.org/net/sword/terms/add" href="http://192.168.1.76:8000/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/" /><br />
<link rel="http://purl.org/net/sword/terms/statement" type="application/atom+xml;type=feed"<br />
href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/state/" /><br />
</entry><br />
</pre><br />
<br />
=== Add Files to a Transfer ===<br />
<br />
Posting file metadata (not yet implemented):<br />
* POST a METS file to the SE-IRI, listed below.<br />
* HTTP headers are required similar to Create Transfer call (above).<br />
* Body must include a valid Atom Entry document, that has METS embedded inside it.<br />
<br />
Posts file data:<br />
* It is possible to also POST the actual file to a deposit location's EM-IRI (/api/v1/location/[location UUID]/sword/media/)<br />
* The file should be posted as the request body and the filename specified using the Content-Disposition header (as per RFC 6266): for example "Content-Disposition: Attachment; filename=dog.jpg"<br />
* An MD5 checksum for an uploaded file can be provided via the Content-MD5 header (as per RFC 1544): for example "Content-MD5: Q2hlY2sgSW50ZWdyaXR5IQ=="<br />
* If only an Atom Entry Document is POST'ed, Archivematica will look for uri's in the file StructMap section of the METS file, and attempt to GET each file listed, to include in the Transfer. (not yet implemented)<br />
<br />
=== Finalize a Transfer ===<br />
* POST with no body to the SE-IRI<br />
* set In-Progress HTTP header to : false<br />
* This will tell Archivematica that no further content will be added or removed from the Transfer. <br />
* Archivematica will finish fetching any files that were added previously, and once they have all been downloaded, the Transfer will start through the Archivematica pipeline.<br />
<br />
'''Example'''<br />
<pre><br />
POST http://localhost/api/v1/location/55ce8053-113a-4954-8aa3-fc9771da0bda/sword/ HTTP/1.1<br />
Host: localhost<br />
Authorization: Archivematica-API api_key="XXXXXXXXXXXXXXXXXXXX", username="timh"<br />
Content-Length: 0<br />
Content-Type: application/atom+xml;type=entry<br />
In-Progress: false<br />
</pre><br />
<br />
The response will be HTTP 200/OK or 400/Error (400 if the Transfer was already finalized). If the transfer doesn't exist the response will be HTTP 404.<br />
<br />
=== Get Status of Transfer ===<br />
To check Status:<br />
<br />
GET the State-IRI<br />
in this example:<br />
<br />
GET http://localhost/api/v1/location/09224ddb-4c7d-404c-9218-2f2e1b5a599e/sword/state/ HTTP/1.1<br />
<br />
response will include:<br />
<pre><atom:feed xmlns:sword="http://purl.org/net/sword/terms/" <br />
xmlns:atom="http://www.w3.org/2005/Atom"><br />
<br />
<atom:category scheme="http://purl.org/net/sword/terms/state"<br />
term="failed"<br />
label="State"><br />
Deposit initiation: Failed<br />
</atom:category><br />
<br />
</atom:feed></pre><br />
the list of possible descriptions is not finalized.<br />
<br />
The state term value will either be "processing" (asynchronous deposit still working), "complete" (ready to be finalized), or "failed" (asynchronous deposit encountered an error).<br />
<br />
== Additional Details == <br />
<br />
=== Transfer Details ===<br />
* redirect to Edit-IRI<br />
* used to get basic info about a Transfer with HTTP GET<br />
* can update basic info using HTTP PUT (not yet implemented)<br />
* can allow deletion with HTTP DELETE<br />
* follows the form: /api/v1/location/[deposit location UUID]/sword/<br />
* example: http://192.168.1.231:8000/api/v1/location/09224ddb-4c7d-404c-9218-2f2e1b5a599e/sword/<br />
<br />
=== EM-IRI ===<br />
* Edit-Media IRI <br />
* used to add new objects to an existing transfer<br />
* follows the form: [archivematica hostname]/api/v2/transfer/[uuid of transfer]/media<br />
* example: /api/v1/location/[deposit location UUID]/sword/media/<br />
<br />
An HTTP POST to the em-iri for a transfer should include a file as the body<br />
<br />
An HTTP GET should return a list of files in the transfer<br />
<br />
An HTTP DELETE to the em-iri will remove all digital objects from the Transfer. This is a valid operation only while the Transfer is being assembled. Once the Transfer has been finalized, attempting to DELETE will return an error.<br />
<br />
=== Edit-IRI ===<br />
The client can replace the metadata of a resource by performing an HTTP PUT of a new Atom Entry on the Edit-IRI. (not yet implemented)<br />
<br />
This would be used to update metadata about a transfer, such as the transfer name.<br />
<br />
* example: http://localhost/api/v2/transfer/1225c695-cfb8-4ebb-aaaa-80da344efa6a/edit<br />
<br />
=== SE-IRI ===<br />
* example: http://localhost/api/v2/transfer/add/1225c695-cfb8-4ebb-aaaa-80da344efa6a (not yet implemented)<br />
<br />
=== State-IRI ===<br />
* used to retrieve status of transfer<br />
* implemented as Atom document<br />
* example: /api/v1/location/[deposit location UUID]/sword/state/<br />
* should be able to subscribe like RSS feed<br />
<br />
=== Service document ===</div>Mcantelonhttps://wiki.archivematica.org/index.php?title=Sword_API&diff=9324Sword API2014-01-10T21:56:17Z<p>Mcantelon: </p>
<hr />
<div><br />
== Overview ==<br />
<br />
One of the 1.1 release features is a sponsored project to integrate Archivematica with Islandora. This integration will be accomplished by creating a [http://swordapp.org Sword] 2.0 API for the Archivematica [https://www.archivematica.org/wiki/Administrator_manual_1.0#Storage_service storage service]. Islandora development work will add functionality to Islandora to use this API to deposit digital objects into Archviematica.<br />
<br />
As described [[Overview|elsewhere]] on this wiki, ''"the primary function of Archivematica is to process digital transfers (accessioned digital objects), turn them into SIPs, apply format policies and create high-quality, repository-independent Archival Information Packages (AIP)"''.<br />
<br />
The Archivematica Sword API allows 3rd party applications to automate the process of creating Transfers. <br />
#Create Transfer - set the name and other metadata about a Transfer<br />
#Populate Transfer - add/edit/update digital objects in a Transfer, and associated metadata<br />
#Finalize Transfer - indicates that the Transfer is ready to start processing.<br />
<br />
After content has been deposited, if users have access to the deposit directory they can also manually manipulate the deposit directory aside from any manipulation using the API.<br />
<br />
Once a Transfer has been created, populated and finalized, Archivematica will begin processing that Transfer.<br />
<br />
== Configuration ==<br />
<br />
The SWORD API is part of the Archivematica storage service REST API. The storage service also talks to the Archivematica dashboard, however, to notify it that a, transfer created from a SWORD deposit, has been approved for processing.<br />
<br />
To use the SWORD API you must install the Archivematica dashboard 1.0 branch and the Archivematica storage service dev/issue-5980-islandora branch.<br />
<br />
Dashboard configuration:<br />
<br />
# In dashboard REST API administration, add the IP of the storage service server to IP whitelist<br />
# In dashboard user administration, take note of username and API key for a dashboard user (example: user "demo" and API key "4e5f32ab2aefd3543e1b19a2de554dd65f90108a")<br />
# In dashboard general admininstration, take note of the dashboard's UUID<br />
<br />
Storage service configuration:<br />
<br />
# In the storage service web interface's Pipelines tab, find the dashboard pipeline (using dashboard's UUID noted during dashboard configuration)<br />
# Enter the dashboard's IP address into the "Remote name" field and the user and API key noted earlier into the "Api username" and "Api key" fields. Click the button to submit these changes.<br />
<br />
== Example session ==<br />
<br />
Below is an example session using curl to manipulate the API. In the example a deposit is created, a file is added to it, and it is finalized.<br />
<br />
NOTE: The SWORD API is in the process of being moved to the storage service. These URLs may not work.<br />
<br />
<pre># create new deposit<br />
curl -v -H "In-Progress: false" --data-binary @mets.xml --request POST http://localhost:8000/api/v1/space/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/<br />
# response XML includes endpoints for adding addition files, etc.<br />
<br />
# add another file to the transfer<br />
curl -v -H "Content-Disposition: attachment; filename=joke.jpg" --request POST \<br />
--data-binary "@joke.jpg" \<br />
http://127.0.0.1:8000/api/v1/location/9c8b4ac0-0407-4360-a10d-af6c62a48b69/sword/media/<br />
<br />
# finalize transfer and approve processing<br />
curl -v -H "In-Progress: false" --request POST http://127.0.0.1:8000/api/v1/location/149cc29d-6472-4bcf-bee8-f8223bf60580/sword/<br />
</pre><br />
<br />
You might, at some point, want to list the transfers that have been started. The following curl command will do so.<br />
<br />
<pre>curl -v http://localhost:8000/api/v1/location/52bbe770-3f96-4493-8d93-ded54c958c51/sword/collection/</pre><br />
<br />
If you're working on a transfer and want to list what files are included in it, the following curl command will list them.<br />
<br />
<pre># list files in transfer<br />
curl -v http://127.0.0.1:8000/api/v1/location/9c8b4ac0-0407-4360-a10d-af6c62a48b69/sword/media/</pre><br />
<br />
If you've started a deposit, but want to discard it, you can delete the deposit. The following curl command shows an example.<br />
<br />
<pre>curl -v -XDELETE http://127.0.0.1:8000/api/v1/location/149cc29d-6472-4bcf-bee8-f8223bf60580/sword/</pre><br />
<br />
== Synchronous Deposit Examples ==<br />
<br />
If you wanted to deposit a transfer then immediately finalize it you could use something like the following curl command.<br />
<br />
<pre>curl -v -H "In-Progress: false" --data-binary @mets.xml --request POST http://localhost:8000/api/v1/space/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/</pre><br />
<br />
<br />
== Endpoints ==<br />
<br />
=== Service document ===<br />
<br />
The SWORD service document provides information about the SWORD provider's capacities and lists SWORD collections. Archivematica currently includes one SWORD collection to which SWORD deposits can be made: transfers.<br />
<br />
The SWORD service document endpoint is located at /api/v1/sword.<br />
<br />
=== List existing transfers ===<br />
* HTTP Get to the Collection IRI (defined by default as: /api/v1/space/[space UUID]/sword/collection/)<br />
* Transfers are listed as an Atom feed<br />
* Each Atom feed entry contains an "atom:link" element whose href attribute contains the URL needed to get details about the transfer<br />
* optional filters via get parameters (not yet implemented)<br />
<br />
=== Create a new transfer ===<br />
* used to start a new transfer in Archivematica<br />
* HTTP POST of an Atom Entry Document to the Collection IRI (defined by default as: /api/v1/space/[space UUID]/sword/collection/)<br />
<br />
'''Possible HTTP Response Codes'''<br />
* HTTP 200 OK - transfer already exists (not yet implemented)<br />
* HTTP 201 Created - transfer has been accepted<br />
* HTTP 412 Precondition Failed - required metadata missing or invalid<br />
<br />
Valid requests will receive a Sword Deposit Receipt in the body of the response.<br />
<br />
'''Required HTTP Headers'''<br />
The HTTP POST must include certain specific http headers. <br />
<br />
Required by http 1.1 specification:<br />
* Host: Must be set to archivematica host name.<br />
* Content-Length: Must be set to the length of the atom entry document.<br />
* Content-Type: Must be set to "application/atom+xml;type=entry".<br />
<br />
Required by Archivematica. <br />
* Authorization: Must include the api key and username assigned by Archivematica.<br />
<br />
Required by SWORD 2.0 protocol:<br />
* In-Progress: Must be set to "true"<br />
<br />
Optional in SWORD 2.0 protocol:<br />
* On-Behalf-Of: not implemented by Archivematica<br />
* Slug: not implemented by Archivematica<br />
<br />
'''Required in Body'''<br />
The Body of the request must be a valid METS Document. The required fields in an Atom Entry Document are:<br />
* LABEL: used as the transfer name<br />
* id: used as an accession id (not yet implemented)<br />
* author: used as the source of acquisition (not yet implemented)<br />
* summary: not implemented yet. Could be used in the future as a description for the Transfer<br />
* updated: should be set to the current timestamp. <br />
<br />
'''Example'''<br />
Example HTTP POST request:<br />
<pre><br />
POST /api/v1/space/96606387-cc70-4b09-b422-a7220606488d/sword/collection/ HTTP/1.1<br />
Host: localhost<br />
Authorization: Archivematica-API api_key="XXXXXXXXXXXXXXXXXXXX", username="timh"<br />
Content-Length: 213<br />
Content-Type: application/atom+xml;type=entry<br />
In-Progress: true<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<METS:mets EXT_VERSION="1.1" OBJID="islandora:72" LABEL="Cinderella"<br />
xmlns:METS="http://www.loc.gov/METS/"<br />
xmlns:xlink="http://www.w3.org/1999/xlink"<br />
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"<br />
xsi:schemaLocation="http://www.loc.gov/METS/ http://www.fedora.info/definitions/1/0/mets-fedora-ext1-1.xsd"><br />
<METS:fileSec><br />
<METS:fileGrp ID="DATASTREAMS"><br />
<METS:fileGrp ID="OBJ"><br />
<METS:file ID="OBJ.0"><br />
<METS:FLocat xlink:title="Cinderella_(1865).pdf" LOCTYPE="URL"<br />
xlink:href="http://localhost:8080/fedora/get/islandora:72/OBJ/2013-08-12T14:46:43.454Z" /><br />
</METS:file><br />
</METS:fileGrp><br />
</METS:fileGrp><br />
</METS:fileSec><br />
</METS:mets><br />
</pre><br />
<br />
Example Response:<br />
<pre><br />
201 Created<br />
Location: http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/<br />
<br />
<entry xmlns="http://www.w3.org/2005/Atom"<br />
xmlns:sword="http://purl.org/net/sword/"<br />
xmlns:dcterms="http://purl.org/dc/terms/"><br />
<br />
<title>Cinderella</title><br />
<id>91d4f258-0050-4914-9d0c-6a74815358d2</id><br />
<updated></updated><br />
<generator uri="https://www.archivematica.org" version="1.0"/><br />
<br />
<summary>A deposit was started.</summary><br />
<sword:treatment>A deposit directory was created and, optionally, asynchronous download of digital objects.</sword:treatment><br />
<br />
<link rel="alternate" href="http://www.swordserver.ac.uk/col1/mydeposit.html"/><br />
<link rel="edit-media" href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/media/"/><br />
<link rel="edit" href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/" /><br />
<link rel="http://purl.org/net/sword/terms/add" href="http://192.168.1.76:8000/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/" /><br />
<link rel="http://purl.org/net/sword/terms/statement" type="application/atom+xml;type=feed"<br />
href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/state/" /><br />
</entry><br />
</pre><br />
<br />
=== Add Files to a Transfer ===<br />
<br />
Posting file metadata (not yet implemented):<br />
* POST a METS file to the SE-IRI, listed below.<br />
* HTTP headers are required similar to Create Transfer call (above).<br />
* Body must include a valid Atom Entry document, that has METS embedded inside it.<br />
<br />
Posts file data:<br />
* It is possible to also POST the actual file to a deposit location's EM-IRI (/api/v1/location/[location UUID]/sword/media/)<br />
* The file should be posted as the request body and the filename specified using the Content-Disposition header (as per RFC 6266): for example "Content-Disposition: Attachment; filename=dog.jpg"<br />
* An MD5 checksum for an uploaded file can be provided via the Content-MD5 header (as per RFC 1544): for example "Content-MD5: Q2hlY2sgSW50ZWdyaXR5IQ=="<br />
* If only an Atom Entry Document is POST'ed, Archivematica will look for uri's in the file StructMap section of the METS file, and attempt to GET each file listed, to include in the Transfer. (not yet implemented)<br />
<br />
=== Finalize a Transfer ===<br />
* POST with no body to the SE-IRI<br />
* set In-Progress HTTP header to : false<br />
* This will tell Archivematica that no further content will be added or removed from the Transfer. <br />
* Archivematica will finish fetching any files that were added previously, and once they have all been downloaded, the Transfer will start through the Archivematica pipeline.<br />
<br />
'''Example'''<br />
<pre><br />
POST http://localhost/api/v1/location/55ce8053-113a-4954-8aa3-fc9771da0bda/sword/ HTTP/1.1<br />
Host: localhost<br />
Authorization: Archivematica-API api_key="XXXXXXXXXXXXXXXXXXXX", username="timh"<br />
Content-Length: 0<br />
Content-Type: application/atom+xml;type=entry<br />
In-Progress: false<br />
</pre><br />
<br />
The response will be HTTP 200/OK or 400/Error (400 if the Transfer was already finalized). If the transfer doesn't exist the response will be HTTP 404.<br />
<br />
=== Get Status of Transfer ===<br />
To check Status:<br />
<br />
GET the State-IRI<br />
in this example:<br />
<br />
GET http://localhost/api/v1/location/09224ddb-4c7d-404c-9218-2f2e1b5a599e/sword/state/ HTTP/1.1<br />
<br />
response will include:<br />
<pre><atom:feed xmlns:sword="http://purl.org/net/sword/terms/" <br />
xmlns:atom="http://www.w3.org/2005/Atom"><br />
<br />
<atom:category scheme="http://purl.org/net/sword/terms/state"<br />
term="failed"<br />
label="State"><br />
Deposit initiation: Failed<br />
</atom:category><br />
<br />
</atom:feed></pre><br />
the list of possible descriptions is not finalized.<br />
<br />
The state term value will either be "processing" (asynchronous deposit still working), "complete" (ready to be finalized), or "failed" (asynchronous deposit encountered an error).<br />
<br />
== Additional Details == <br />
<br />
=== Transfer Details ===<br />
* redirect to Edit-IRI<br />
* used to get basic info about a Transfer with HTTP GET<br />
* can update basic info using HTTP PUT (not yet implemented)<br />
* can allow deletion with HTTP DELETE<br />
* follows the form: /api/v1/location/[deposit location UUID]/sword/<br />
* example: http://192.168.1.231:8000/api/v1/location/09224ddb-4c7d-404c-9218-2f2e1b5a599e/sword/<br />
<br />
=== EM-IRI ===<br />
* Edit-Media IRI <br />
* used to add new objects to an existing transfer<br />
* follows the form: [archivematica hostname]/api/v2/transfer/[uuid of transfer]/media<br />
* example: /api/v1/location/[deposit location UUID]/sword/media/<br />
<br />
An HTTP POST to the em-iri for a transfer should include a file as the body<br />
<br />
An HTTP GET should return a list of files in the transfer<br />
<br />
An HTTP DELETE to the em-iri will remove all digital objects from the Transfer. This is a valid operation only while the Transfer is being assembled. Once the Transfer has been finalized, attempting to DELETE will return an error.<br />
<br />
=== Edit-IRI ===<br />
The client can replace the metadata of a resource by performing an HTTP PUT of a new Atom Entry on the Edit-IRI. (not yet implemented)<br />
<br />
This would be used to update metadata about a transfer, such as the transfer name.<br />
<br />
* example: http://localhost/api/v2/transfer/1225c695-cfb8-4ebb-aaaa-80da344efa6a/edit<br />
<br />
=== SE-IRI ===<br />
* example: http://localhost/api/v2/transfer/add/1225c695-cfb8-4ebb-aaaa-80da344efa6a (not yet implemented)<br />
<br />
=== State-IRI ===<br />
* used to retrieve status of transfer<br />
* implemented as Atom document<br />
* example: /api/v1/location/[deposit location UUID]/sword/state/<br />
* should be able to subscribe like RSS feed<br />
<br />
=== Service document ===</div>Mcantelonhttps://wiki.archivematica.org/index.php?title=Sword_API&diff=9323Sword API2014-01-10T21:53:56Z<p>Mcantelon: </p>
<hr />
<div><br />
== Overview ==<br />
<br />
One of the 1.1 release features is a sponsored project to integrate Archivematica with Islandora. This integration will be accomplished by creating a [http://swordapp.org Sword] 2.0 API for the Archivematica [https://www.archivematica.org/wiki/Administrator_manual_1.0#Storage_service storage service]. Islandora development work will add functionality to Islandora to use this API to deposit digital objects into Archviematica.<br />
<br />
As described [[Overview|elsewhere]] on this wiki, ''"the primary function of Archivematica is to process digital transfers (accessioned digital objects), turn them into SIPs, apply format policies and create high-quality, repository-independent Archival Information Packages (AIP)"''.<br />
<br />
The Archivematica Sword API allows 3rd party applications to automate the process of creating Transfers. <br />
#Create Transfer - set the name and other metadata about a Transfer<br />
#Populate Transfer - add/edit/update digital objects in a Transfer, and associated metadata<br />
#Finalize Transfer - indicates that the Transfer is ready to start processing.<br />
<br />
After content has been deposited, if users have access to the deposit directory they can also manually manipulate the deposit directory aside from any manipulation using the API.<br />
<br />
Once a Transfer has been created, populated and finalized, Archivematica will begin processing that Transfer.<br />
<br />
== Configuration ==<br />
<br />
The SWORD API is part of the Archivematica storage service REST API. The storage service also talks to the Archivematica dashboard, however, to notify it that a, transfer created from a SWORD deposit, has been approved for processing.<br />
<br />
To use the SWORD API you must install the Archivematica dashboard 1.0 branch and the Archivematica storage service dev/issue-5980-islandora branch.<br />
<br />
Dashboard configuration:<br />
<br />
# In dashboard REST API administration, add the IP of the storage service server to IP whitelist<br />
# In dashboard user administration, take note of username and API key for a dashboard user (example: user "demo" and API key "4e5f32ab2aefd3543e1b19a2de554dd65f90108a")<br />
# In dashboard general admininstration, take note of the dashboard's UUID<br />
<br />
Storage service configuration:<br />
<br />
# In the storage service web interface's Pipelines tab, find the dashboard pipeline (using dashboard's UUID noted during dashboard configuration)<br />
# Enter the dashboard's IP address into the "Remote name" field and the user and API key noted earlier into the "Api username" and "Api key" fields. Click the button to submit these changes.<br />
<br />
== Endpoints ==<br />
<br />
=== Service document ===<br />
<br />
The SWORD service document provides information about the SWORD provider's capacities and lists SWORD collections. Archivematica currently includes one SWORD collection to which SWORD deposits can be made: transfers.<br />
<br />
The SWORD service document endpoint is located at /api/v1/sword.<br />
<br />
=== List existing transfers ===<br />
* HTTP Get to the Collection IRI (defined by default as: /api/v1/space/[space UUID]/sword/collection/)<br />
* Transfers are listed as an Atom feed<br />
* Each Atom feed entry contains an "atom:link" element whose href attribute contains the URL needed to get details about the transfer<br />
* optional filters via get parameters (not yet implemented)<br />
<br />
=== Create a new transfer ===<br />
* used to start a new transfer in Archivematica<br />
* HTTP POST of an Atom Entry Document to the Collection IRI (defined by default as: /api/v1/space/[space UUID]/sword/collection/)<br />
<br />
'''Possible HTTP Response Codes'''<br />
* HTTP 200 OK - transfer already exists (not yet implemented)<br />
* HTTP 201 Created - transfer has been accepted<br />
* HTTP 412 Precondition Failed - required metadata missing or invalid<br />
<br />
Valid requests will receive a Sword Deposit Receipt in the body of the response.<br />
<br />
'''Required HTTP Headers'''<br />
The HTTP POST must include certain specific http headers. <br />
<br />
Required by http 1.1 specification:<br />
* Host: Must be set to archivematica host name.<br />
* Content-Length: Must be set to the length of the atom entry document.<br />
* Content-Type: Must be set to "application/atom+xml;type=entry".<br />
<br />
Required by Archivematica. <br />
* Authorization: Must include the api key and username assigned by Archivematica.<br />
<br />
Required by SWORD 2.0 protocol:<br />
* In-Progress: Must be set to "true"<br />
<br />
Optional in SWORD 2.0 protocol:<br />
* On-Behalf-Of: not implemented by Archivematica<br />
* Slug: not implemented by Archivematica<br />
<br />
'''Required in Body'''<br />
The Body of the request must be a valid METS Document. The required fields in an Atom Entry Document are:<br />
* LABEL: used as the transfer name<br />
* id: used as an accession id (not yet implemented)<br />
* author: used as the source of acquisition (not yet implemented)<br />
* summary: not implemented yet. Could be used in the future as a description for the Transfer<br />
* updated: should be set to the current timestamp. <br />
<br />
'''Example'''<br />
Example HTTP POST request:<br />
<pre><br />
POST /api/v1/space/96606387-cc70-4b09-b422-a7220606488d/sword/collection/ HTTP/1.1<br />
Host: localhost<br />
Authorization: Archivematica-API api_key="XXXXXXXXXXXXXXXXXXXX", username="timh"<br />
Content-Length: 213<br />
Content-Type: application/atom+xml;type=entry<br />
In-Progress: true<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<METS:mets EXT_VERSION="1.1" OBJID="islandora:72" LABEL="Cinderella"<br />
xmlns:METS="http://www.loc.gov/METS/"<br />
xmlns:xlink="http://www.w3.org/1999/xlink"<br />
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"<br />
xsi:schemaLocation="http://www.loc.gov/METS/ http://www.fedora.info/definitions/1/0/mets-fedora-ext1-1.xsd"><br />
<METS:fileSec><br />
<METS:fileGrp ID="DATASTREAMS"><br />
<METS:fileGrp ID="OBJ"><br />
<METS:file ID="OBJ.0"><br />
<METS:FLocat xlink:title="Cinderella_(1865).pdf" LOCTYPE="URL"<br />
xlink:href="http://localhost:8080/fedora/get/islandora:72/OBJ/2013-08-12T14:46:43.454Z" /><br />
</METS:file><br />
</METS:fileGrp><br />
</METS:fileGrp><br />
</METS:fileSec><br />
</METS:mets><br />
</pre><br />
<br />
Example Response:<br />
<pre><br />
201 Created<br />
Location: http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/<br />
<br />
<entry xmlns="http://www.w3.org/2005/Atom"<br />
xmlns:sword="http://purl.org/net/sword/"<br />
xmlns:dcterms="http://purl.org/dc/terms/"><br />
<br />
<title>Cinderella</title><br />
<id>91d4f258-0050-4914-9d0c-6a74815358d2</id><br />
<updated></updated><br />
<generator uri="https://www.archivematica.org" version="1.0"/><br />
<br />
<summary>A deposit was started.</summary><br />
<sword:treatment>A deposit directory was created and, optionally, asynchronous download of digital objects.</sword:treatment><br />
<br />
<link rel="alternate" href="http://www.swordserver.ac.uk/col1/mydeposit.html"/><br />
<link rel="edit-media" href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/media/"/><br />
<link rel="edit" href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/" /><br />
<link rel="http://purl.org/net/sword/terms/add" href="http://192.168.1.76:8000/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/" /><br />
<link rel="http://purl.org/net/sword/terms/statement" type="application/atom+xml;type=feed"<br />
href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/state/" /><br />
</entry><br />
</pre><br />
<br />
=== Add Files to a Transfer ===<br />
<br />
Posting file metadata (not yet implemented):<br />
* POST a METS file to the SE-IRI, listed below.<br />
* HTTP headers are required similar to Create Transfer call (above).<br />
* Body must include a valid Atom Entry document, that has METS embedded inside it.<br />
<br />
Posts file data:<br />
* It is possible to also POST the actual file to a deposit location's EM-IRI (/api/v1/location/[location UUID]/sword/media/)<br />
* The file should be posted as the request body and the filename specified using the Content-Disposition header (as per RFC 6266): for example "Content-Disposition: Attachment; filename=dog.jpg"<br />
* An MD5 checksum for an uploaded file can be provided via the Content-MD5 header (as per RFC 1544): for example "Content-MD5: Q2hlY2sgSW50ZWdyaXR5IQ=="<br />
* If only an Atom Entry Document is POST'ed, Archivematica will look for uri's in the file StructMap section of the METS file, and attempt to GET each file listed, to include in the Transfer. (not yet implemented)<br />
<br />
=== Finalize a Transfer ===<br />
* POST with no body to the SE-IRI<br />
* set In-Progress HTTP header to : false<br />
* This will tell Archivematica that no further content will be added or removed from the Transfer. <br />
* Archivematica will finish fetching any files that were added previously, and once they have all been downloaded, the Transfer will start through the Archivematica pipeline.<br />
<br />
'''Example'''<br />
<pre><br />
POST http://localhost/api/v1/location/55ce8053-113a-4954-8aa3-fc9771da0bda/sword/ HTTP/1.1<br />
Host: localhost<br />
Authorization: Archivematica-API api_key="XXXXXXXXXXXXXXXXXXXX", username="timh"<br />
Content-Length: 0<br />
Content-Type: application/atom+xml;type=entry<br />
In-Progress: false<br />
</pre><br />
<br />
The response will be HTTP 200/OK or 400/Error (400 if the Transfer was already finalized). If the transfer doesn't exist the response will be HTTP 404.<br />
<br />
=== Get Status of Transfer ===<br />
To check Status:<br />
<br />
GET the State-IRI<br />
in this example:<br />
<br />
GET http://localhost/api/v1/location/09224ddb-4c7d-404c-9218-2f2e1b5a599e/sword/state/ HTTP/1.1<br />
<br />
response will include:<br />
<pre><atom:feed xmlns:sword="http://purl.org/net/sword/terms/" <br />
xmlns:atom="http://www.w3.org/2005/Atom"><br />
<br />
<atom:category scheme="http://purl.org/net/sword/terms/state"<br />
term="failed"<br />
label="State"><br />
Deposit initiation: Failed<br />
</atom:category><br />
<br />
</atom:feed></pre><br />
the list of possible descriptions is not finalized.<br />
<br />
The state term value will either be "processing" (asynchronous deposit still working), "complete" (ready to be finalized), or "failed" (asynchronous deposit encountered an error).<br />
<br />
== Additional Details == <br />
<br />
=== Transfer Details ===<br />
* redirect to Edit-IRI<br />
* used to get basic info about a Transfer with HTTP GET<br />
* can update basic info using HTTP PUT (not yet implemented)<br />
* can allow deletion with HTTP DELETE<br />
* follows the form: /api/v1/location/[deposit location UUID]/sword/<br />
* example: http://192.168.1.231:8000/api/v1/location/09224ddb-4c7d-404c-9218-2f2e1b5a599e/sword/<br />
<br />
=== EM-IRI ===<br />
* Edit-Media IRI <br />
* used to add new objects to an existing transfer<br />
* follows the form: [archivematica hostname]/api/v2/transfer/[uuid of transfer]/media<br />
* example: /api/v1/location/[deposit location UUID]/sword/media/<br />
<br />
An HTTP POST to the em-iri for a transfer should include a file as the body<br />
<br />
An HTTP GET should return a list of files in the transfer<br />
<br />
An HTTP DELETE to the em-iri will remove all digital objects from the Transfer. This is a valid operation only while the Transfer is being assembled. Once the Transfer has been finalized, attempting to DELETE will return an error.<br />
<br />
=== Edit-IRI ===<br />
The client can replace the metadata of a resource by performing an HTTP PUT of a new Atom Entry on the Edit-IRI. (not yet implemented)<br />
<br />
This would be used to update metadata about a transfer, such as the transfer name.<br />
<br />
* example: http://localhost/api/v2/transfer/1225c695-cfb8-4ebb-aaaa-80da344efa6a/edit<br />
<br />
=== SE-IRI ===<br />
* example: http://localhost/api/v2/transfer/add/1225c695-cfb8-4ebb-aaaa-80da344efa6a (not yet implemented)<br />
<br />
=== State-IRI ===<br />
* used to retrieve status of transfer<br />
* implemented as Atom document<br />
* example: /api/v1/location/[deposit location UUID]/sword/state/<br />
* should be able to subscribe like RSS feed<br />
<br />
=== Service document ===<br />
<br />
== Example session ==<br />
<br />
Below is an example session using curl to manipulate the API. In the example a deposit is created, a file is added to it, and it is finalized.<br />
<br />
NOTE: The SWORD API is in the process of being moved to the storage service. These URLs may not work.<br />
<br />
<pre># create new deposit<br />
curl -v -H "In-Progress: false" --data-binary @mets.xml --request POST http://localhost:8000/api/v1/space/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/<br />
# response XML includes endpoints for adding addition files, etc.<br />
<br />
# add another file to the transfer<br />
curl -v -H "Content-Disposition: attachment; filename=joke.jpg" --request POST \<br />
--data-binary "@joke.jpg" \<br />
http://127.0.0.1:8000/api/v1/location/9c8b4ac0-0407-4360-a10d-af6c62a48b69/sword/media/<br />
<br />
# finalize transfer and approve processing<br />
curl -v -H "In-Progress: false" --request POST http://127.0.0.1:8000/api/v1/location/149cc29d-6472-4bcf-bee8-f8223bf60580/sword/<br />
</pre><br />
<br />
You might, at some point, want to list the transfers that have been started. The following curl command will do so.<br />
<br />
<pre>curl -v http://localhost:8000/api/v1/location/52bbe770-3f96-4493-8d93-ded54c958c51/sword/collection/</pre><br />
<br />
If you're working on a transfer and want to list what files are included in it, the following curl command will list them.<br />
<br />
<pre># list files in transfer<br />
curl -v http://127.0.0.1:8000/api/v1/location/9c8b4ac0-0407-4360-a10d-af6c62a48b69/sword/media/</pre><br />
<br />
If you've started a deposit, but want to discard it, you can delete the deposit. The following curl command shows an example.<br />
<br />
<pre>curl -v -XDELETE http://127.0.0.1:8000/api/v1/location/149cc29d-6472-4bcf-bee8-f8223bf60580/sword/</pre><br />
<br />
== Synchronous Deposit Examples ==<br />
<br />
If you wanted to deposit a transfer then immediately finalize it you could use something like the following curl command.<br />
<br />
<pre>curl -v -H "In-Progress: false" --data-binary @mets.xml --request POST http://localhost:8000/api/v1/space/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/</pre></div>Mcantelonhttps://wiki.archivematica.org/index.php?title=Sword_API&diff=9322Sword API2014-01-10T21:52:37Z<p>Mcantelon: /* Configuration */</p>
<hr />
<div><br />
== Overview ==<br />
<br />
One of the 1.1 release features is a sponsored project to integrate Archivematica with Islandora. This integration will be accomplished by creating a [http://swordapp.org Sword] 2.0 API for the Archivematica [https://www.archivematica.org/wiki/Administrator_manual_1.0#Storage_service storage service]. Islandora development work will add functionality to Islandora to use this API to deposit digital objects into Archviematica.<br />
<br />
As described [[Overview|elsewhere]] on this wiki, ''"the primary function of Archivematica is to process digital transfers (accessioned digital objects), turn them into SIPs, apply format policies and create high-quality, repository-independent Archival Information Packages (AIP)"''.<br />
<br />
The Archivematica Sword API allows 3rd party applications to automate the process of creating Transfers. <br />
#Create Transfer - set the name and other metadata about a Transfer<br />
#Populate Transfer - add/edit/update digital objects in a Transfer, and associated metadata<br />
#Finalize Transfer - indicates that the Transfer is ready to start processing.<br />
<br />
After content has been deposited, if users have access to the deposit directory they can also manually manipulate the deposit directory aside from any manipulation using the API.<br />
<br />
Once a Transfer has been created, populated and finalized, Archivematica will begin processing that Transfer.<br />
<br />
== Endpoints ==<br />
<br />
=== Service document ===<br />
<br />
The SWORD service document provides information about the SWORD provider's capacities and lists SWORD collections. Archivematica currently includes one SWORD collection to which SWORD deposits can be made: transfers.<br />
<br />
The SWORD service document endpoint is located at /api/v1/sword.<br />
<br />
=== List existing transfers ===<br />
* HTTP Get to the Collection IRI (defined by default as: /api/v1/space/[space UUID]/sword/collection/)<br />
* Transfers are listed as an Atom feed<br />
* Each Atom feed entry contains an "atom:link" element whose href attribute contains the URL needed to get details about the transfer<br />
* optional filters via get parameters (not yet implemented)<br />
<br />
=== Create a new transfer ===<br />
* used to start a new transfer in Archivematica<br />
* HTTP POST of an Atom Entry Document to the Collection IRI (defined by default as: /api/v1/space/[space UUID]/sword/collection/)<br />
<br />
'''Possible HTTP Response Codes'''<br />
* HTTP 200 OK - transfer already exists (not yet implemented)<br />
* HTTP 201 Created - transfer has been accepted<br />
* HTTP 412 Precondition Failed - required metadata missing or invalid<br />
<br />
Valid requests will receive a Sword Deposit Receipt in the body of the response.<br />
<br />
'''Required HTTP Headers'''<br />
The HTTP POST must include certain specific http headers. <br />
<br />
Required by http 1.1 specification:<br />
* Host: Must be set to archivematica host name.<br />
* Content-Length: Must be set to the length of the atom entry document.<br />
* Content-Type: Must be set to "application/atom+xml;type=entry".<br />
<br />
Required by Archivematica. <br />
* Authorization: Must include the api key and username assigned by Archivematica.<br />
<br />
Required by SWORD 2.0 protocol:<br />
* In-Progress: Must be set to "true"<br />
<br />
Optional in SWORD 2.0 protocol:<br />
* On-Behalf-Of: not implemented by Archivematica<br />
* Slug: not implemented by Archivematica<br />
<br />
'''Required in Body'''<br />
The Body of the request must be a valid METS Document. The required fields in an Atom Entry Document are:<br />
* LABEL: used as the transfer name<br />
* id: used as an accession id (not yet implemented)<br />
* author: used as the source of acquisition (not yet implemented)<br />
* summary: not implemented yet. Could be used in the future as a description for the Transfer<br />
* updated: should be set to the current timestamp. <br />
<br />
'''Example'''<br />
Example HTTP POST request:<br />
<pre><br />
POST /api/v1/space/96606387-cc70-4b09-b422-a7220606488d/sword/collection/ HTTP/1.1<br />
Host: localhost<br />
Authorization: Archivematica-API api_key="XXXXXXXXXXXXXXXXXXXX", username="timh"<br />
Content-Length: 213<br />
Content-Type: application/atom+xml;type=entry<br />
In-Progress: true<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<METS:mets EXT_VERSION="1.1" OBJID="islandora:72" LABEL="Cinderella"<br />
xmlns:METS="http://www.loc.gov/METS/"<br />
xmlns:xlink="http://www.w3.org/1999/xlink"<br />
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"<br />
xsi:schemaLocation="http://www.loc.gov/METS/ http://www.fedora.info/definitions/1/0/mets-fedora-ext1-1.xsd"><br />
<METS:fileSec><br />
<METS:fileGrp ID="DATASTREAMS"><br />
<METS:fileGrp ID="OBJ"><br />
<METS:file ID="OBJ.0"><br />
<METS:FLocat xlink:title="Cinderella_(1865).pdf" LOCTYPE="URL"<br />
xlink:href="http://localhost:8080/fedora/get/islandora:72/OBJ/2013-08-12T14:46:43.454Z" /><br />
</METS:file><br />
</METS:fileGrp><br />
</METS:fileGrp><br />
</METS:fileSec><br />
</METS:mets><br />
</pre><br />
<br />
Example Response:<br />
<pre><br />
201 Created<br />
Location: http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/<br />
<br />
<entry xmlns="http://www.w3.org/2005/Atom"<br />
xmlns:sword="http://purl.org/net/sword/"<br />
xmlns:dcterms="http://purl.org/dc/terms/"><br />
<br />
<title>Cinderella</title><br />
<id>91d4f258-0050-4914-9d0c-6a74815358d2</id><br />
<updated></updated><br />
<generator uri="https://www.archivematica.org" version="1.0"/><br />
<br />
<summary>A deposit was started.</summary><br />
<sword:treatment>A deposit directory was created and, optionally, asynchronous download of digital objects.</sword:treatment><br />
<br />
<link rel="alternate" href="http://www.swordserver.ac.uk/col1/mydeposit.html"/><br />
<link rel="edit-media" href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/media/"/><br />
<link rel="edit" href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/" /><br />
<link rel="http://purl.org/net/sword/terms/add" href="http://192.168.1.76:8000/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/" /><br />
<link rel="http://purl.org/net/sword/terms/statement" type="application/atom+xml;type=feed"<br />
href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/state/" /><br />
</entry><br />
</pre><br />
<br />
=== Add Files to a Transfer ===<br />
<br />
Posting file metadata (not yet implemented):<br />
* POST a METS file to the SE-IRI, listed below.<br />
* HTTP headers are required similar to Create Transfer call (above).<br />
* Body must include a valid Atom Entry document, that has METS embedded inside it.<br />
<br />
Posts file data:<br />
* It is possible to also POST the actual file to a deposit location's EM-IRI (/api/v1/location/[location UUID]/sword/media/)<br />
* The file should be posted as the request body and the filename specified using the Content-Disposition header (as per RFC 6266): for example "Content-Disposition: Attachment; filename=dog.jpg"<br />
* An MD5 checksum for an uploaded file can be provided via the Content-MD5 header (as per RFC 1544): for example "Content-MD5: Q2hlY2sgSW50ZWdyaXR5IQ=="<br />
* If only an Atom Entry Document is POST'ed, Archivematica will look for uri's in the file StructMap section of the METS file, and attempt to GET each file listed, to include in the Transfer. (not yet implemented)<br />
<br />
=== Finalize a Transfer ===<br />
* POST with no body to the SE-IRI<br />
* set In-Progress HTTP header to : false<br />
* This will tell Archivematica that no further content will be added or removed from the Transfer. <br />
* Archivematica will finish fetching any files that were added previously, and once they have all been downloaded, the Transfer will start through the Archivematica pipeline.<br />
<br />
'''Example'''<br />
<pre><br />
POST http://localhost/api/v1/location/55ce8053-113a-4954-8aa3-fc9771da0bda/sword/ HTTP/1.1<br />
Host: localhost<br />
Authorization: Archivematica-API api_key="XXXXXXXXXXXXXXXXXXXX", username="timh"<br />
Content-Length: 0<br />
Content-Type: application/atom+xml;type=entry<br />
In-Progress: false<br />
</pre><br />
<br />
The response will be HTTP 200/OK or 400/Error (400 if the Transfer was already finalized). If the transfer doesn't exist the response will be HTTP 404.<br />
<br />
=== Get Status of Transfer ===<br />
To check Status:<br />
<br />
GET the State-IRI<br />
in this example:<br />
<br />
GET http://localhost/api/v1/location/09224ddb-4c7d-404c-9218-2f2e1b5a599e/sword/state/ HTTP/1.1<br />
<br />
response will include:<br />
<pre><atom:feed xmlns:sword="http://purl.org/net/sword/terms/" <br />
xmlns:atom="http://www.w3.org/2005/Atom"><br />
<br />
<atom:category scheme="http://purl.org/net/sword/terms/state"<br />
term="failed"<br />
label="State"><br />
Deposit initiation: Failed<br />
</atom:category><br />
<br />
</atom:feed></pre><br />
the list of possible descriptions is not finalized.<br />
<br />
The state term value will either be "processing" (asynchronous deposit still working), "complete" (ready to be finalized), or "failed" (asynchronous deposit encountered an error).<br />
<br />
== Additional Details == <br />
<br />
=== Transfer Details ===<br />
* redirect to Edit-IRI<br />
* used to get basic info about a Transfer with HTTP GET<br />
* can update basic info using HTTP PUT (not yet implemented)<br />
* can allow deletion with HTTP DELETE<br />
* follows the form: /api/v1/location/[deposit location UUID]/sword/<br />
* example: http://192.168.1.231:8000/api/v1/location/09224ddb-4c7d-404c-9218-2f2e1b5a599e/sword/<br />
<br />
=== EM-IRI ===<br />
* Edit-Media IRI <br />
* used to add new objects to an existing transfer<br />
* follows the form: [archivematica hostname]/api/v2/transfer/[uuid of transfer]/media<br />
* example: /api/v1/location/[deposit location UUID]/sword/media/<br />
<br />
An HTTP POST to the em-iri for a transfer should include a file as the body<br />
<br />
An HTTP GET should return a list of files in the transfer<br />
<br />
An HTTP DELETE to the em-iri will remove all digital objects from the Transfer. This is a valid operation only while the Transfer is being assembled. Once the Transfer has been finalized, attempting to DELETE will return an error.<br />
<br />
=== Edit-IRI ===<br />
The client can replace the metadata of a resource by performing an HTTP PUT of a new Atom Entry on the Edit-IRI. (not yet implemented)<br />
<br />
This would be used to update metadata about a transfer, such as the transfer name.<br />
<br />
* example: http://localhost/api/v2/transfer/1225c695-cfb8-4ebb-aaaa-80da344efa6a/edit<br />
<br />
=== SE-IRI ===<br />
* example: http://localhost/api/v2/transfer/add/1225c695-cfb8-4ebb-aaaa-80da344efa6a (not yet implemented)<br />
<br />
=== State-IRI ===<br />
* used to retrieve status of transfer<br />
* implemented as Atom document<br />
* example: /api/v1/location/[deposit location UUID]/sword/state/<br />
* should be able to subscribe like RSS feed<br />
<br />
=== Service document ===<br />
<br />
== Configuration ==<br />
<br />
The SWORD API is part of the Archivematica storage service REST API. The storage service also talks to the Archivematica dashboard, however, to notify it that a, transfer created from a SWORD deposit, has been approved for processing.<br />
<br />
To use the SWORD API you must install the Archivematica dashboard 1.0 branch and the Archivematica storage service dev/issue-5980-islandora branch.<br />
<br />
Dashboard configuration:<br />
<br />
# In dashboard REST API administration, add the IP of the storage service server to IP whitelist<br />
# In dashboard user administration, take note of username and API key for a dashboard user (example: user "demo" and API key "4e5f32ab2aefd3543e1b19a2de554dd65f90108a")<br />
# In dashboard general admininstration, take note of the dashboard's UUID<br />
<br />
Storage service configuration:<br />
<br />
# In the storage service web interface's Pipelines tab, find the dashboard pipeline (using dashboard's UUID noted during dashboard configuration)<br />
# Enter the dashboard's IP address into the "Remote name" field and the user and API key noted earlier into the "Api username" and "Api key" fields. Click the button to submit these changes.<br />
<br />
== Example session ==<br />
<br />
Below is an example session using curl to manipulate the API. In the example a deposit is created, a file is added to it, and it is finalized.<br />
<br />
NOTE: The SWORD API is in the process of being moved to the storage service. These URLs may not work.<br />
<br />
<pre># create new deposit<br />
curl -v -H "In-Progress: false" --data-binary @mets.xml --request POST http://localhost:8000/api/v1/space/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/<br />
# response XML includes endpoints for adding addition files, etc.<br />
<br />
# add another file to the transfer<br />
curl -v -H "Content-Disposition: attachment; filename=joke.jpg" --request POST \<br />
--data-binary "@joke.jpg" \<br />
http://127.0.0.1:8000/api/v1/location/9c8b4ac0-0407-4360-a10d-af6c62a48b69/sword/media/<br />
<br />
# finalize transfer and approve processing<br />
curl -v -H "In-Progress: false" --request POST http://127.0.0.1:8000/api/v1/location/149cc29d-6472-4bcf-bee8-f8223bf60580/sword/<br />
</pre><br />
<br />
You might, at some point, want to list the transfers that have been started. The following curl command will do so.<br />
<br />
<pre>curl -v http://localhost:8000/api/v1/location/52bbe770-3f96-4493-8d93-ded54c958c51/sword/collection/</pre><br />
<br />
If you're working on a transfer and want to list what files are included in it, the following curl command will list them.<br />
<br />
<pre># list files in transfer<br />
curl -v http://127.0.0.1:8000/api/v1/location/9c8b4ac0-0407-4360-a10d-af6c62a48b69/sword/media/</pre><br />
<br />
If you've started a deposit, but want to discard it, you can delete the deposit. The following curl command shows an example.<br />
<br />
<pre>curl -v -XDELETE http://127.0.0.1:8000/api/v1/location/149cc29d-6472-4bcf-bee8-f8223bf60580/sword/</pre><br />
<br />
== Synchronous Deposit Examples ==<br />
<br />
If you wanted to deposit a transfer then immediately finalize it you could use something like the following curl command.<br />
<br />
<pre>curl -v -H "In-Progress: false" --data-binary @mets.xml --request POST http://localhost:8000/api/v1/space/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/</pre></div>Mcantelonhttps://wiki.archivematica.org/index.php?title=Sword_API&diff=9321Sword API2014-01-10T21:50:47Z<p>Mcantelon: /* Configuration */</p>
<hr />
<div><br />
== Overview ==<br />
<br />
One of the 1.1 release features is a sponsored project to integrate Archivematica with Islandora. This integration will be accomplished by creating a [http://swordapp.org Sword] 2.0 API for the Archivematica [https://www.archivematica.org/wiki/Administrator_manual_1.0#Storage_service storage service]. Islandora development work will add functionality to Islandora to use this API to deposit digital objects into Archviematica.<br />
<br />
As described [[Overview|elsewhere]] on this wiki, ''"the primary function of Archivematica is to process digital transfers (accessioned digital objects), turn them into SIPs, apply format policies and create high-quality, repository-independent Archival Information Packages (AIP)"''.<br />
<br />
The Archivematica Sword API allows 3rd party applications to automate the process of creating Transfers. <br />
#Create Transfer - set the name and other metadata about a Transfer<br />
#Populate Transfer - add/edit/update digital objects in a Transfer, and associated metadata<br />
#Finalize Transfer - indicates that the Transfer is ready to start processing.<br />
<br />
After content has been deposited, if users have access to the deposit directory they can also manually manipulate the deposit directory aside from any manipulation using the API.<br />
<br />
Once a Transfer has been created, populated and finalized, Archivematica will begin processing that Transfer.<br />
<br />
== Endpoints ==<br />
<br />
=== Service document ===<br />
<br />
The SWORD service document provides information about the SWORD provider's capacities and lists SWORD collections. Archivematica currently includes one SWORD collection to which SWORD deposits can be made: transfers.<br />
<br />
The SWORD service document endpoint is located at /api/v1/sword.<br />
<br />
=== List existing transfers ===<br />
* HTTP Get to the Collection IRI (defined by default as: /api/v1/space/[space UUID]/sword/collection/)<br />
* Transfers are listed as an Atom feed<br />
* Each Atom feed entry contains an "atom:link" element whose href attribute contains the URL needed to get details about the transfer<br />
* optional filters via get parameters (not yet implemented)<br />
<br />
=== Create a new transfer ===<br />
* used to start a new transfer in Archivematica<br />
* HTTP POST of an Atom Entry Document to the Collection IRI (defined by default as: /api/v1/space/[space UUID]/sword/collection/)<br />
<br />
'''Possible HTTP Response Codes'''<br />
* HTTP 200 OK - transfer already exists (not yet implemented)<br />
* HTTP 201 Created - transfer has been accepted<br />
* HTTP 412 Precondition Failed - required metadata missing or invalid<br />
<br />
Valid requests will receive a Sword Deposit Receipt in the body of the response.<br />
<br />
'''Required HTTP Headers'''<br />
The HTTP POST must include certain specific http headers. <br />
<br />
Required by http 1.1 specification:<br />
* Host: Must be set to archivematica host name.<br />
* Content-Length: Must be set to the length of the atom entry document.<br />
* Content-Type: Must be set to "application/atom+xml;type=entry".<br />
<br />
Required by Archivematica. <br />
* Authorization: Must include the api key and username assigned by Archivematica.<br />
<br />
Required by SWORD 2.0 protocol:<br />
* In-Progress: Must be set to "true"<br />
<br />
Optional in SWORD 2.0 protocol:<br />
* On-Behalf-Of: not implemented by Archivematica<br />
* Slug: not implemented by Archivematica<br />
<br />
'''Required in Body'''<br />
The Body of the request must be a valid METS Document. The required fields in an Atom Entry Document are:<br />
* LABEL: used as the transfer name<br />
* id: used as an accession id (not yet implemented)<br />
* author: used as the source of acquisition (not yet implemented)<br />
* summary: not implemented yet. Could be used in the future as a description for the Transfer<br />
* updated: should be set to the current timestamp. <br />
<br />
'''Example'''<br />
Example HTTP POST request:<br />
<pre><br />
POST /api/v1/space/96606387-cc70-4b09-b422-a7220606488d/sword/collection/ HTTP/1.1<br />
Host: localhost<br />
Authorization: Archivematica-API api_key="XXXXXXXXXXXXXXXXXXXX", username="timh"<br />
Content-Length: 213<br />
Content-Type: application/atom+xml;type=entry<br />
In-Progress: true<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<METS:mets EXT_VERSION="1.1" OBJID="islandora:72" LABEL="Cinderella"<br />
xmlns:METS="http://www.loc.gov/METS/"<br />
xmlns:xlink="http://www.w3.org/1999/xlink"<br />
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"<br />
xsi:schemaLocation="http://www.loc.gov/METS/ http://www.fedora.info/definitions/1/0/mets-fedora-ext1-1.xsd"><br />
<METS:fileSec><br />
<METS:fileGrp ID="DATASTREAMS"><br />
<METS:fileGrp ID="OBJ"><br />
<METS:file ID="OBJ.0"><br />
<METS:FLocat xlink:title="Cinderella_(1865).pdf" LOCTYPE="URL"<br />
xlink:href="http://localhost:8080/fedora/get/islandora:72/OBJ/2013-08-12T14:46:43.454Z" /><br />
</METS:file><br />
</METS:fileGrp><br />
</METS:fileGrp><br />
</METS:fileSec><br />
</METS:mets><br />
</pre><br />
<br />
Example Response:<br />
<pre><br />
201 Created<br />
Location: http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/<br />
<br />
<entry xmlns="http://www.w3.org/2005/Atom"<br />
xmlns:sword="http://purl.org/net/sword/"<br />
xmlns:dcterms="http://purl.org/dc/terms/"><br />
<br />
<title>Cinderella</title><br />
<id>91d4f258-0050-4914-9d0c-6a74815358d2</id><br />
<updated></updated><br />
<generator uri="https://www.archivematica.org" version="1.0"/><br />
<br />
<summary>A deposit was started.</summary><br />
<sword:treatment>A deposit directory was created and, optionally, asynchronous download of digital objects.</sword:treatment><br />
<br />
<link rel="alternate" href="http://www.swordserver.ac.uk/col1/mydeposit.html"/><br />
<link rel="edit-media" href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/media/"/><br />
<link rel="edit" href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/" /><br />
<link rel="http://purl.org/net/sword/terms/add" href="http://192.168.1.76:8000/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/" /><br />
<link rel="http://purl.org/net/sword/terms/statement" type="application/atom+xml;type=feed"<br />
href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/state/" /><br />
</entry><br />
</pre><br />
<br />
=== Add Files to a Transfer ===<br />
<br />
Posting file metadata (not yet implemented):<br />
* POST a METS file to the SE-IRI, listed below.<br />
* HTTP headers are required similar to Create Transfer call (above).<br />
* Body must include a valid Atom Entry document, that has METS embedded inside it.<br />
<br />
Posts file data:<br />
* It is possible to also POST the actual file to a deposit location's EM-IRI (/api/v1/location/[location UUID]/sword/media/)<br />
* The file should be posted as the request body and the filename specified using the Content-Disposition header (as per RFC 6266): for example "Content-Disposition: Attachment; filename=dog.jpg"<br />
* An MD5 checksum for an uploaded file can be provided via the Content-MD5 header (as per RFC 1544): for example "Content-MD5: Q2hlY2sgSW50ZWdyaXR5IQ=="<br />
* If only an Atom Entry Document is POST'ed, Archivematica will look for uri's in the file StructMap section of the METS file, and attempt to GET each file listed, to include in the Transfer. (not yet implemented)<br />
<br />
=== Finalize a Transfer ===<br />
* POST with no body to the SE-IRI<br />
* set In-Progress HTTP header to : false<br />
* This will tell Archivematica that no further content will be added or removed from the Transfer. <br />
* Archivematica will finish fetching any files that were added previously, and once they have all been downloaded, the Transfer will start through the Archivematica pipeline.<br />
<br />
'''Example'''<br />
<pre><br />
POST http://localhost/api/v1/location/55ce8053-113a-4954-8aa3-fc9771da0bda/sword/ HTTP/1.1<br />
Host: localhost<br />
Authorization: Archivematica-API api_key="XXXXXXXXXXXXXXXXXXXX", username="timh"<br />
Content-Length: 0<br />
Content-Type: application/atom+xml;type=entry<br />
In-Progress: false<br />
</pre><br />
<br />
The response will be HTTP 200/OK or 400/Error (400 if the Transfer was already finalized). If the transfer doesn't exist the response will be HTTP 404.<br />
<br />
=== Get Status of Transfer ===<br />
To check Status:<br />
<br />
GET the State-IRI<br />
in this example:<br />
<br />
GET http://localhost/api/v1/location/09224ddb-4c7d-404c-9218-2f2e1b5a599e/sword/state/ HTTP/1.1<br />
<br />
response will include:<br />
<pre><atom:feed xmlns:sword="http://purl.org/net/sword/terms/" <br />
xmlns:atom="http://www.w3.org/2005/Atom"><br />
<br />
<atom:category scheme="http://purl.org/net/sword/terms/state"<br />
term="failed"<br />
label="State"><br />
Deposit initiation: Failed<br />
</atom:category><br />
<br />
</atom:feed></pre><br />
the list of possible descriptions is not finalized.<br />
<br />
The state term value will either be "processing" (asynchronous deposit still working), "complete" (ready to be finalized), or "failed" (asynchronous deposit encountered an error).<br />
<br />
== Additional Details == <br />
<br />
=== Transfer Details ===<br />
* redirect to Edit-IRI<br />
* used to get basic info about a Transfer with HTTP GET<br />
* can update basic info using HTTP PUT (not yet implemented)<br />
* can allow deletion with HTTP DELETE<br />
* follows the form: /api/v1/location/[deposit location UUID]/sword/<br />
* example: http://192.168.1.231:8000/api/v1/location/09224ddb-4c7d-404c-9218-2f2e1b5a599e/sword/<br />
<br />
=== EM-IRI ===<br />
* Edit-Media IRI <br />
* used to add new objects to an existing transfer<br />
* follows the form: [archivematica hostname]/api/v2/transfer/[uuid of transfer]/media<br />
* example: /api/v1/location/[deposit location UUID]/sword/media/<br />
<br />
An HTTP POST to the em-iri for a transfer should include a file as the body<br />
<br />
An HTTP GET should return a list of files in the transfer<br />
<br />
An HTTP DELETE to the em-iri will remove all digital objects from the Transfer. This is a valid operation only while the Transfer is being assembled. Once the Transfer has been finalized, attempting to DELETE will return an error.<br />
<br />
=== Edit-IRI ===<br />
The client can replace the metadata of a resource by performing an HTTP PUT of a new Atom Entry on the Edit-IRI. (not yet implemented)<br />
<br />
This would be used to update metadata about a transfer, such as the transfer name.<br />
<br />
* example: http://localhost/api/v2/transfer/1225c695-cfb8-4ebb-aaaa-80da344efa6a/edit<br />
<br />
=== SE-IRI ===<br />
* example: http://localhost/api/v2/transfer/add/1225c695-cfb8-4ebb-aaaa-80da344efa6a (not yet implemented)<br />
<br />
=== State-IRI ===<br />
* used to retrieve status of transfer<br />
* implemented as Atom document<br />
* example: /api/v1/location/[deposit location UUID]/sword/state/<br />
* should be able to subscribe like RSS feed<br />
<br />
=== Service document ===<br />
<br />
== Configuration ==<br />
<br />
The SWORD API is part of the Archivematica storage service REST API. The storage service also talks to the Archivematica dashboard, however, to notify it that a, transfer created from a SWORD deposit, has been approved for processing.<br />
<br />
# Install the Archivematica dashboard 1.0 branch and the Archivematica storage service dev/issue-5980-islandora branch<br />
# In dashboard REST API administration, add IP of storage service to IP whitelist<br />
# In dashboard user administration, take note of username and API key for a dashboard user (example: user "demo" and API key "4e5f32ab2aefd3543e1b19a2de554dd65f90108a")<br />
# In dashboard general admininstration, take note of the dashboard's UUID<br />
# In the storage service web interface's Pipelines tab, find the dashboard pipeline (using dashboard's UUID)<br />
# Enter the dashboard's IP address into the "Remote name" field and the user and API key noted earlier into the "Api username" and "Api key" fields. Click the button to submit these changes.<br />
<br />
== Example session ==<br />
<br />
Below is an example session using curl to manipulate the API. In the example a deposit is created, a file is added to it, and it is finalized.<br />
<br />
NOTE: The SWORD API is in the process of being moved to the storage service. These URLs may not work.<br />
<br />
<pre># create new deposit<br />
curl -v -H "In-Progress: false" --data-binary @mets.xml --request POST http://localhost:8000/api/v1/space/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/<br />
# response XML includes endpoints for adding addition files, etc.<br />
<br />
# add another file to the transfer<br />
curl -v -H "Content-Disposition: attachment; filename=joke.jpg" --request POST \<br />
--data-binary "@joke.jpg" \<br />
http://127.0.0.1:8000/api/v1/location/9c8b4ac0-0407-4360-a10d-af6c62a48b69/sword/media/<br />
<br />
# finalize transfer and approve processing<br />
curl -v -H "In-Progress: false" --request POST http://127.0.0.1:8000/api/v1/location/149cc29d-6472-4bcf-bee8-f8223bf60580/sword/<br />
</pre><br />
<br />
You might, at some point, want to list the transfers that have been started. The following curl command will do so.<br />
<br />
<pre>curl -v http://localhost:8000/api/v1/location/52bbe770-3f96-4493-8d93-ded54c958c51/sword/collection/</pre><br />
<br />
If you're working on a transfer and want to list what files are included in it, the following curl command will list them.<br />
<br />
<pre># list files in transfer<br />
curl -v http://127.0.0.1:8000/api/v1/location/9c8b4ac0-0407-4360-a10d-af6c62a48b69/sword/media/</pre><br />
<br />
If you've started a deposit, but want to discard it, you can delete the deposit. The following curl command shows an example.<br />
<br />
<pre>curl -v -XDELETE http://127.0.0.1:8000/api/v1/location/149cc29d-6472-4bcf-bee8-f8223bf60580/sword/</pre><br />
<br />
== Synchronous Deposit Examples ==<br />
<br />
If you wanted to deposit a transfer then immediately finalize it you could use something like the following curl command.<br />
<br />
<pre>curl -v -H "In-Progress: false" --data-binary @mets.xml --request POST http://localhost:8000/api/v1/space/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/</pre></div>Mcantelonhttps://wiki.archivematica.org/index.php?title=Sword_API&diff=9320Sword API2014-01-10T21:45:04Z<p>Mcantelon: /* Configuration */</p>
<hr />
<div><br />
== Overview ==<br />
<br />
One of the 1.1 release features is a sponsored project to integrate Archivematica with Islandora. This integration will be accomplished by creating a [http://swordapp.org Sword] 2.0 API for the Archivematica [https://www.archivematica.org/wiki/Administrator_manual_1.0#Storage_service storage service]. Islandora development work will add functionality to Islandora to use this API to deposit digital objects into Archviematica.<br />
<br />
As described [[Overview|elsewhere]] on this wiki, ''"the primary function of Archivematica is to process digital transfers (accessioned digital objects), turn them into SIPs, apply format policies and create high-quality, repository-independent Archival Information Packages (AIP)"''.<br />
<br />
The Archivematica Sword API allows 3rd party applications to automate the process of creating Transfers. <br />
#Create Transfer - set the name and other metadata about a Transfer<br />
#Populate Transfer - add/edit/update digital objects in a Transfer, and associated metadata<br />
#Finalize Transfer - indicates that the Transfer is ready to start processing.<br />
<br />
After content has been deposited, if users have access to the deposit directory they can also manually manipulate the deposit directory aside from any manipulation using the API.<br />
<br />
Once a Transfer has been created, populated and finalized, Archivematica will begin processing that Transfer.<br />
<br />
== Endpoints ==<br />
<br />
=== Service document ===<br />
<br />
The SWORD service document provides information about the SWORD provider's capacities and lists SWORD collections. Archivematica currently includes one SWORD collection to which SWORD deposits can be made: transfers.<br />
<br />
The SWORD service document endpoint is located at /api/v1/sword.<br />
<br />
=== List existing transfers ===<br />
* HTTP Get to the Collection IRI (defined by default as: /api/v1/space/[space UUID]/sword/collection/)<br />
* Transfers are listed as an Atom feed<br />
* Each Atom feed entry contains an "atom:link" element whose href attribute contains the URL needed to get details about the transfer<br />
* optional filters via get parameters (not yet implemented)<br />
<br />
=== Create a new transfer ===<br />
* used to start a new transfer in Archivematica<br />
* HTTP POST of an Atom Entry Document to the Collection IRI (defined by default as: /api/v1/space/[space UUID]/sword/collection/)<br />
<br />
'''Possible HTTP Response Codes'''<br />
* HTTP 200 OK - transfer already exists (not yet implemented)<br />
* HTTP 201 Created - transfer has been accepted<br />
* HTTP 412 Precondition Failed - required metadata missing or invalid<br />
<br />
Valid requests will receive a Sword Deposit Receipt in the body of the response.<br />
<br />
'''Required HTTP Headers'''<br />
The HTTP POST must include certain specific http headers. <br />
<br />
Required by http 1.1 specification:<br />
* Host: Must be set to archivematica host name.<br />
* Content-Length: Must be set to the length of the atom entry document.<br />
* Content-Type: Must be set to "application/atom+xml;type=entry".<br />
<br />
Required by Archivematica. <br />
* Authorization: Must include the api key and username assigned by Archivematica.<br />
<br />
Required by SWORD 2.0 protocol:<br />
* In-Progress: Must be set to "true"<br />
<br />
Optional in SWORD 2.0 protocol:<br />
* On-Behalf-Of: not implemented by Archivematica<br />
* Slug: not implemented by Archivematica<br />
<br />
'''Required in Body'''<br />
The Body of the request must be a valid METS Document. The required fields in an Atom Entry Document are:<br />
* LABEL: used as the transfer name<br />
* id: used as an accession id (not yet implemented)<br />
* author: used as the source of acquisition (not yet implemented)<br />
* summary: not implemented yet. Could be used in the future as a description for the Transfer<br />
* updated: should be set to the current timestamp. <br />
<br />
'''Example'''<br />
Example HTTP POST request:<br />
<pre><br />
POST /api/v1/space/96606387-cc70-4b09-b422-a7220606488d/sword/collection/ HTTP/1.1<br />
Host: localhost<br />
Authorization: Archivematica-API api_key="XXXXXXXXXXXXXXXXXXXX", username="timh"<br />
Content-Length: 213<br />
Content-Type: application/atom+xml;type=entry<br />
In-Progress: true<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<METS:mets EXT_VERSION="1.1" OBJID="islandora:72" LABEL="Cinderella"<br />
xmlns:METS="http://www.loc.gov/METS/"<br />
xmlns:xlink="http://www.w3.org/1999/xlink"<br />
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"<br />
xsi:schemaLocation="http://www.loc.gov/METS/ http://www.fedora.info/definitions/1/0/mets-fedora-ext1-1.xsd"><br />
<METS:fileSec><br />
<METS:fileGrp ID="DATASTREAMS"><br />
<METS:fileGrp ID="OBJ"><br />
<METS:file ID="OBJ.0"><br />
<METS:FLocat xlink:title="Cinderella_(1865).pdf" LOCTYPE="URL"<br />
xlink:href="http://localhost:8080/fedora/get/islandora:72/OBJ/2013-08-12T14:46:43.454Z" /><br />
</METS:file><br />
</METS:fileGrp><br />
</METS:fileGrp><br />
</METS:fileSec><br />
</METS:mets><br />
</pre><br />
<br />
Example Response:<br />
<pre><br />
201 Created<br />
Location: http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/<br />
<br />
<entry xmlns="http://www.w3.org/2005/Atom"<br />
xmlns:sword="http://purl.org/net/sword/"<br />
xmlns:dcterms="http://purl.org/dc/terms/"><br />
<br />
<title>Cinderella</title><br />
<id>91d4f258-0050-4914-9d0c-6a74815358d2</id><br />
<updated></updated><br />
<generator uri="https://www.archivematica.org" version="1.0"/><br />
<br />
<summary>A deposit was started.</summary><br />
<sword:treatment>A deposit directory was created and, optionally, asynchronous download of digital objects.</sword:treatment><br />
<br />
<link rel="alternate" href="http://www.swordserver.ac.uk/col1/mydeposit.html"/><br />
<link rel="edit-media" href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/media/"/><br />
<link rel="edit" href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/" /><br />
<link rel="http://purl.org/net/sword/terms/add" href="http://192.168.1.76:8000/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/" /><br />
<link rel="http://purl.org/net/sword/terms/statement" type="application/atom+xml;type=feed"<br />
href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/state/" /><br />
</entry><br />
</pre><br />
<br />
=== Add Files to a Transfer ===<br />
<br />
Posting file metadata (not yet implemented):<br />
* POST a METS file to the SE-IRI, listed below.<br />
* HTTP headers are required similar to Create Transfer call (above).<br />
* Body must include a valid Atom Entry document, that has METS embedded inside it.<br />
<br />
Posts file data:<br />
* It is possible to also POST the actual file to a deposit location's EM-IRI (/api/v1/location/[location UUID]/sword/media/)<br />
* The file should be posted as the request body and the filename specified using the Content-Disposition header (as per RFC 6266): for example "Content-Disposition: Attachment; filename=dog.jpg"<br />
* An MD5 checksum for an uploaded file can be provided via the Content-MD5 header (as per RFC 1544): for example "Content-MD5: Q2hlY2sgSW50ZWdyaXR5IQ=="<br />
* If only an Atom Entry Document is POST'ed, Archivematica will look for uri's in the file StructMap section of the METS file, and attempt to GET each file listed, to include in the Transfer. (not yet implemented)<br />
<br />
=== Finalize a Transfer ===<br />
* POST with no body to the SE-IRI<br />
* set In-Progress HTTP header to : false<br />
* This will tell Archivematica that no further content will be added or removed from the Transfer. <br />
* Archivematica will finish fetching any files that were added previously, and once they have all been downloaded, the Transfer will start through the Archivematica pipeline.<br />
<br />
'''Example'''<br />
<pre><br />
POST http://localhost/api/v1/location/55ce8053-113a-4954-8aa3-fc9771da0bda/sword/ HTTP/1.1<br />
Host: localhost<br />
Authorization: Archivematica-API api_key="XXXXXXXXXXXXXXXXXXXX", username="timh"<br />
Content-Length: 0<br />
Content-Type: application/atom+xml;type=entry<br />
In-Progress: false<br />
</pre><br />
<br />
The response will be HTTP 200/OK or 400/Error (400 if the Transfer was already finalized). If the transfer doesn't exist the response will be HTTP 404.<br />
<br />
=== Get Status of Transfer ===<br />
To check Status:<br />
<br />
GET the State-IRI<br />
in this example:<br />
<br />
GET http://localhost/api/v1/location/09224ddb-4c7d-404c-9218-2f2e1b5a599e/sword/state/ HTTP/1.1<br />
<br />
response will include:<br />
<pre><atom:feed xmlns:sword="http://purl.org/net/sword/terms/" <br />
xmlns:atom="http://www.w3.org/2005/Atom"><br />
<br />
<atom:category scheme="http://purl.org/net/sword/terms/state"<br />
term="failed"<br />
label="State"><br />
Deposit initiation: Failed<br />
</atom:category><br />
<br />
</atom:feed></pre><br />
the list of possible descriptions is not finalized.<br />
<br />
The state term value will either be "processing" (asynchronous deposit still working), "complete" (ready to be finalized), or "failed" (asynchronous deposit encountered an error).<br />
<br />
== Additional Details == <br />
<br />
=== Transfer Details ===<br />
* redirect to Edit-IRI<br />
* used to get basic info about a Transfer with HTTP GET<br />
* can update basic info using HTTP PUT (not yet implemented)<br />
* can allow deletion with HTTP DELETE<br />
* follows the form: /api/v1/location/[deposit location UUID]/sword/<br />
* example: http://192.168.1.231:8000/api/v1/location/09224ddb-4c7d-404c-9218-2f2e1b5a599e/sword/<br />
<br />
=== EM-IRI ===<br />
* Edit-Media IRI <br />
* used to add new objects to an existing transfer<br />
* follows the form: [archivematica hostname]/api/v2/transfer/[uuid of transfer]/media<br />
* example: /api/v1/location/[deposit location UUID]/sword/media/<br />
<br />
An HTTP POST to the em-iri for a transfer should include a file as the body<br />
<br />
An HTTP GET should return a list of files in the transfer<br />
<br />
An HTTP DELETE to the em-iri will remove all digital objects from the Transfer. This is a valid operation only while the Transfer is being assembled. Once the Transfer has been finalized, attempting to DELETE will return an error.<br />
<br />
=== Edit-IRI ===<br />
The client can replace the metadata of a resource by performing an HTTP PUT of a new Atom Entry on the Edit-IRI. (not yet implemented)<br />
<br />
This would be used to update metadata about a transfer, such as the transfer name.<br />
<br />
* example: http://localhost/api/v2/transfer/1225c695-cfb8-4ebb-aaaa-80da344efa6a/edit<br />
<br />
=== SE-IRI ===<br />
* example: http://localhost/api/v2/transfer/add/1225c695-cfb8-4ebb-aaaa-80da344efa6a (not yet implemented)<br />
<br />
=== State-IRI ===<br />
* used to retrieve status of transfer<br />
* implemented as Atom document<br />
* example: /api/v1/location/[deposit location UUID]/sword/state/<br />
* should be able to subscribe like RSS feed<br />
<br />
=== Service document ===<br />
<br />
== Configuration ==<br />
<br />
# Install the Archivematica dashboard 1.0 branch and the Archivematica storage service dev/issue-5980-islandora branch<br />
# In dashboard REST API administration, add IP of storage service to IP whitelist<br />
# In dashboard user administration, take note of username and API key for a dashboard user (example: user "demo" and API key "4e5f32ab2aefd3543e1b19a2de554dd65f90108a")<br />
# In dashboard general admininstration, take note of the dashboard's UUID<br />
# In the storage service web interface's Pipelines tab, find the dashboard pipeline (using dashboard's UUID)<br />
# Enter the dashboard's IP address into the "Remote name" field and the user and API key noted earlier into the "Api username" and "Api key" fields. Click the button to submit these changes.<br />
<br />
When a transfer deposit is finalized, an Archivematica dashboard can be notified in the background, via a REST API, that the transfer should be approved for processing. In this way the SWORD API can be used to start transfers.<br />
<br />
Each SWORD collection space in a storage service is associated with an Archivematica dashboard. Both the Archivematica dashboard instance and the storage service, however, require configuration.<br />
<br />
On the Archivematica dashboard side, the IP or hostname of the storage service must be added to the REST API whitelist (click "Administration" in the Archivematica navigation bar then "REST API" in the administration sidebar to get to the whitelist page).<br />
<br />
Once you're whitelisted the storage service in the Archivematica dashboard, click "General" in the administration sidebar then note the dashboard UUID. In the storage service administration interface, click "Pipelines" in the navigation bar. Find the UUID matching the dashboard then click "Edit". In the "Remote name" field enter the IP or hostname of the Archivematica dashboard. In the "Api username" field enter an Archivematica dashboard username (click "Administration" in the Archivematica navigation bar then "Users" in the administration sidebar to access the user list). In the "Api key" field enter the user's API key (a user's API key can be found by clicking the "Edit" button corresponding to a specific user on the user list page).<br />
<br />
== Example session ==<br />
<br />
Below is an example session using curl to manipulate the API. In the example a deposit is created, a file is added to it, and it is finalized.<br />
<br />
NOTE: The SWORD API is in the process of being moved to the storage service. These URLs may not work.<br />
<br />
<pre># create new deposit<br />
curl -v -H "In-Progress: false" --data-binary @mets.xml --request POST http://localhost:8000/api/v1/space/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/<br />
# response XML includes endpoints for adding addition files, etc.<br />
<br />
# add another file to the transfer<br />
curl -v -H "Content-Disposition: attachment; filename=joke.jpg" --request POST \<br />
--data-binary "@joke.jpg" \<br />
http://127.0.0.1:8000/api/v1/location/9c8b4ac0-0407-4360-a10d-af6c62a48b69/sword/media/<br />
<br />
# finalize transfer and approve processing<br />
curl -v -H "In-Progress: false" --request POST http://127.0.0.1:8000/api/v1/location/149cc29d-6472-4bcf-bee8-f8223bf60580/sword/<br />
</pre><br />
<br />
You might, at some point, want to list the transfers that have been started. The following curl command will do so.<br />
<br />
<pre>curl -v http://localhost:8000/api/v1/location/52bbe770-3f96-4493-8d93-ded54c958c51/sword/collection/</pre><br />
<br />
If you're working on a transfer and want to list what files are included in it, the following curl command will list them.<br />
<br />
<pre># list files in transfer<br />
curl -v http://127.0.0.1:8000/api/v1/location/9c8b4ac0-0407-4360-a10d-af6c62a48b69/sword/media/</pre><br />
<br />
If you've started a deposit, but want to discard it, you can delete the deposit. The following curl command shows an example.<br />
<br />
<pre>curl -v -XDELETE http://127.0.0.1:8000/api/v1/location/149cc29d-6472-4bcf-bee8-f8223bf60580/sword/</pre><br />
<br />
== Synchronous Deposit Examples ==<br />
<br />
If you wanted to deposit a transfer then immediately finalize it you could use something like the following curl command.<br />
<br />
<pre>curl -v -H "In-Progress: false" --data-binary @mets.xml --request POST http://localhost:8000/api/v1/space/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/</pre></div>Mcantelonhttps://wiki.archivematica.org/index.php?title=Sword_API&diff=9319Sword API2014-01-10T21:44:40Z<p>Mcantelon: /* Configuration */</p>
<hr />
<div><br />
== Overview ==<br />
<br />
One of the 1.1 release features is a sponsored project to integrate Archivematica with Islandora. This integration will be accomplished by creating a [http://swordapp.org Sword] 2.0 API for the Archivematica [https://www.archivematica.org/wiki/Administrator_manual_1.0#Storage_service storage service]. Islandora development work will add functionality to Islandora to use this API to deposit digital objects into Archviematica.<br />
<br />
As described [[Overview|elsewhere]] on this wiki, ''"the primary function of Archivematica is to process digital transfers (accessioned digital objects), turn them into SIPs, apply format policies and create high-quality, repository-independent Archival Information Packages (AIP)"''.<br />
<br />
The Archivematica Sword API allows 3rd party applications to automate the process of creating Transfers. <br />
#Create Transfer - set the name and other metadata about a Transfer<br />
#Populate Transfer - add/edit/update digital objects in a Transfer, and associated metadata<br />
#Finalize Transfer - indicates that the Transfer is ready to start processing.<br />
<br />
After content has been deposited, if users have access to the deposit directory they can also manually manipulate the deposit directory aside from any manipulation using the API.<br />
<br />
Once a Transfer has been created, populated and finalized, Archivematica will begin processing that Transfer.<br />
<br />
== Endpoints ==<br />
<br />
=== Service document ===<br />
<br />
The SWORD service document provides information about the SWORD provider's capacities and lists SWORD collections. Archivematica currently includes one SWORD collection to which SWORD deposits can be made: transfers.<br />
<br />
The SWORD service document endpoint is located at /api/v1/sword.<br />
<br />
=== List existing transfers ===<br />
* HTTP Get to the Collection IRI (defined by default as: /api/v1/space/[space UUID]/sword/collection/)<br />
* Transfers are listed as an Atom feed<br />
* Each Atom feed entry contains an "atom:link" element whose href attribute contains the URL needed to get details about the transfer<br />
* optional filters via get parameters (not yet implemented)<br />
<br />
=== Create a new transfer ===<br />
* used to start a new transfer in Archivematica<br />
* HTTP POST of an Atom Entry Document to the Collection IRI (defined by default as: /api/v1/space/[space UUID]/sword/collection/)<br />
<br />
'''Possible HTTP Response Codes'''<br />
* HTTP 200 OK - transfer already exists (not yet implemented)<br />
* HTTP 201 Created - transfer has been accepted<br />
* HTTP 412 Precondition Failed - required metadata missing or invalid<br />
<br />
Valid requests will receive a Sword Deposit Receipt in the body of the response.<br />
<br />
'''Required HTTP Headers'''<br />
The HTTP POST must include certain specific http headers. <br />
<br />
Required by http 1.1 specification:<br />
* Host: Must be set to archivematica host name.<br />
* Content-Length: Must be set to the length of the atom entry document.<br />
* Content-Type: Must be set to "application/atom+xml;type=entry".<br />
<br />
Required by Archivematica. <br />
* Authorization: Must include the api key and username assigned by Archivematica.<br />
<br />
Required by SWORD 2.0 protocol:<br />
* In-Progress: Must be set to "true"<br />
<br />
Optional in SWORD 2.0 protocol:<br />
* On-Behalf-Of: not implemented by Archivematica<br />
* Slug: not implemented by Archivematica<br />
<br />
'''Required in Body'''<br />
The Body of the request must be a valid METS Document. The required fields in an Atom Entry Document are:<br />
* LABEL: used as the transfer name<br />
* id: used as an accession id (not yet implemented)<br />
* author: used as the source of acquisition (not yet implemented)<br />
* summary: not implemented yet. Could be used in the future as a description for the Transfer<br />
* updated: should be set to the current timestamp. <br />
<br />
'''Example'''<br />
Example HTTP POST request:<br />
<pre><br />
POST /api/v1/space/96606387-cc70-4b09-b422-a7220606488d/sword/collection/ HTTP/1.1<br />
Host: localhost<br />
Authorization: Archivematica-API api_key="XXXXXXXXXXXXXXXXXXXX", username="timh"<br />
Content-Length: 213<br />
Content-Type: application/atom+xml;type=entry<br />
In-Progress: true<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<METS:mets EXT_VERSION="1.1" OBJID="islandora:72" LABEL="Cinderella"<br />
xmlns:METS="http://www.loc.gov/METS/"<br />
xmlns:xlink="http://www.w3.org/1999/xlink"<br />
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"<br />
xsi:schemaLocation="http://www.loc.gov/METS/ http://www.fedora.info/definitions/1/0/mets-fedora-ext1-1.xsd"><br />
<METS:fileSec><br />
<METS:fileGrp ID="DATASTREAMS"><br />
<METS:fileGrp ID="OBJ"><br />
<METS:file ID="OBJ.0"><br />
<METS:FLocat xlink:title="Cinderella_(1865).pdf" LOCTYPE="URL"<br />
xlink:href="http://localhost:8080/fedora/get/islandora:72/OBJ/2013-08-12T14:46:43.454Z" /><br />
</METS:file><br />
</METS:fileGrp><br />
</METS:fileGrp><br />
</METS:fileSec><br />
</METS:mets><br />
</pre><br />
<br />
Example Response:<br />
<pre><br />
201 Created<br />
Location: http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/<br />
<br />
<entry xmlns="http://www.w3.org/2005/Atom"<br />
xmlns:sword="http://purl.org/net/sword/"<br />
xmlns:dcterms="http://purl.org/dc/terms/"><br />
<br />
<title>Cinderella</title><br />
<id>91d4f258-0050-4914-9d0c-6a74815358d2</id><br />
<updated></updated><br />
<generator uri="https://www.archivematica.org" version="1.0"/><br />
<br />
<summary>A deposit was started.</summary><br />
<sword:treatment>A deposit directory was created and, optionally, asynchronous download of digital objects.</sword:treatment><br />
<br />
<link rel="alternate" href="http://www.swordserver.ac.uk/col1/mydeposit.html"/><br />
<link rel="edit-media" href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/media/"/><br />
<link rel="edit" href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/" /><br />
<link rel="http://purl.org/net/sword/terms/add" href="http://192.168.1.76:8000/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/" /><br />
<link rel="http://purl.org/net/sword/terms/statement" type="application/atom+xml;type=feed"<br />
href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/state/" /><br />
</entry><br />
</pre><br />
<br />
=== Add Files to a Transfer ===<br />
<br />
Posting file metadata (not yet implemented):<br />
* POST a METS file to the SE-IRI, listed below.<br />
* HTTP headers are required similar to Create Transfer call (above).<br />
* Body must include a valid Atom Entry document, that has METS embedded inside it.<br />
<br />
Posts file data:<br />
* It is possible to also POST the actual file to a deposit location's EM-IRI (/api/v1/location/[location UUID]/sword/media/)<br />
* The file should be posted as the request body and the filename specified using the Content-Disposition header (as per RFC 6266): for example "Content-Disposition: Attachment; filename=dog.jpg"<br />
* An MD5 checksum for an uploaded file can be provided via the Content-MD5 header (as per RFC 1544): for example "Content-MD5: Q2hlY2sgSW50ZWdyaXR5IQ=="<br />
* If only an Atom Entry Document is POST'ed, Archivematica will look for uri's in the file StructMap section of the METS file, and attempt to GET each file listed, to include in the Transfer. (not yet implemented)<br />
<br />
=== Finalize a Transfer ===<br />
* POST with no body to the SE-IRI<br />
* set In-Progress HTTP header to : false<br />
* This will tell Archivematica that no further content will be added or removed from the Transfer. <br />
* Archivematica will finish fetching any files that were added previously, and once they have all been downloaded, the Transfer will start through the Archivematica pipeline.<br />
<br />
'''Example'''<br />
<pre><br />
POST http://localhost/api/v1/location/55ce8053-113a-4954-8aa3-fc9771da0bda/sword/ HTTP/1.1<br />
Host: localhost<br />
Authorization: Archivematica-API api_key="XXXXXXXXXXXXXXXXXXXX", username="timh"<br />
Content-Length: 0<br />
Content-Type: application/atom+xml;type=entry<br />
In-Progress: false<br />
</pre><br />
<br />
The response will be HTTP 200/OK or 400/Error (400 if the Transfer was already finalized). If the transfer doesn't exist the response will be HTTP 404.<br />
<br />
=== Get Status of Transfer ===<br />
To check Status:<br />
<br />
GET the State-IRI<br />
in this example:<br />
<br />
GET http://localhost/api/v1/location/09224ddb-4c7d-404c-9218-2f2e1b5a599e/sword/state/ HTTP/1.1<br />
<br />
response will include:<br />
<pre><atom:feed xmlns:sword="http://purl.org/net/sword/terms/" <br />
xmlns:atom="http://www.w3.org/2005/Atom"><br />
<br />
<atom:category scheme="http://purl.org/net/sword/terms/state"<br />
term="failed"<br />
label="State"><br />
Deposit initiation: Failed<br />
</atom:category><br />
<br />
</atom:feed></pre><br />
the list of possible descriptions is not finalized.<br />
<br />
The state term value will either be "processing" (asynchronous deposit still working), "complete" (ready to be finalized), or "failed" (asynchronous deposit encountered an error).<br />
<br />
== Additional Details == <br />
<br />
=== Transfer Details ===<br />
* redirect to Edit-IRI<br />
* used to get basic info about a Transfer with HTTP GET<br />
* can update basic info using HTTP PUT (not yet implemented)<br />
* can allow deletion with HTTP DELETE<br />
* follows the form: /api/v1/location/[deposit location UUID]/sword/<br />
* example: http://192.168.1.231:8000/api/v1/location/09224ddb-4c7d-404c-9218-2f2e1b5a599e/sword/<br />
<br />
=== EM-IRI ===<br />
* Edit-Media IRI <br />
* used to add new objects to an existing transfer<br />
* follows the form: [archivematica hostname]/api/v2/transfer/[uuid of transfer]/media<br />
* example: /api/v1/location/[deposit location UUID]/sword/media/<br />
<br />
An HTTP POST to the em-iri for a transfer should include a file as the body<br />
<br />
An HTTP GET should return a list of files in the transfer<br />
<br />
An HTTP DELETE to the em-iri will remove all digital objects from the Transfer. This is a valid operation only while the Transfer is being assembled. Once the Transfer has been finalized, attempting to DELETE will return an error.<br />
<br />
=== Edit-IRI ===<br />
The client can replace the metadata of a resource by performing an HTTP PUT of a new Atom Entry on the Edit-IRI. (not yet implemented)<br />
<br />
This would be used to update metadata about a transfer, such as the transfer name.<br />
<br />
* example: http://localhost/api/v2/transfer/1225c695-cfb8-4ebb-aaaa-80da344efa6a/edit<br />
<br />
=== SE-IRI ===<br />
* example: http://localhost/api/v2/transfer/add/1225c695-cfb8-4ebb-aaaa-80da344efa6a (not yet implemented)<br />
<br />
=== State-IRI ===<br />
* used to retrieve status of transfer<br />
* implemented as Atom document<br />
* example: /api/v1/location/[deposit location UUID]/sword/state/<br />
* should be able to subscribe like RSS feed<br />
<br />
=== Service document ===<br />
<br />
== Configuration ==<br />
<br />
# Install dashboard 1.0 branch and storage service dev/issue-5980-islandora branch<br />
# In dashboard REST API administration, add IP of storage service to IP whitelist<br />
# In dashboard user administration, take note of username and API key for a dashboard user (example: user "demo" and API key "4e5f32ab2aefd3543e1b19a2de554dd65f90108a")<br />
# In dashboard general admininstration, take note of the dashboard's UUID<br />
# In the storage service web interface's Pipelines tab, find the dashboard pipeline (using dashboard's UUID)<br />
# Enter the dashboard's IP address into the "Remote name" field and the user and API key noted earlier into the "Api username" and "Api key" fields. Click the button to submit these changes.<br />
<br />
When a transfer deposit is finalized, an Archivematica dashboard can be notified in the background, via a REST API, that the transfer should be approved for processing. In this way the SWORD API can be used to start transfers.<br />
<br />
Each SWORD collection space in a storage service is associated with an Archivematica dashboard. Both the Archivematica dashboard instance and the storage service, however, require configuration.<br />
<br />
On the Archivematica dashboard side, the IP or hostname of the storage service must be added to the REST API whitelist (click "Administration" in the Archivematica navigation bar then "REST API" in the administration sidebar to get to the whitelist page).<br />
<br />
Once you're whitelisted the storage service in the Archivematica dashboard, click "General" in the administration sidebar then note the dashboard UUID. In the storage service administration interface, click "Pipelines" in the navigation bar. Find the UUID matching the dashboard then click "Edit". In the "Remote name" field enter the IP or hostname of the Archivematica dashboard. In the "Api username" field enter an Archivematica dashboard username (click "Administration" in the Archivematica navigation bar then "Users" in the administration sidebar to access the user list). In the "Api key" field enter the user's API key (a user's API key can be found by clicking the "Edit" button corresponding to a specific user on the user list page).<br />
<br />
== Example session ==<br />
<br />
Below is an example session using curl to manipulate the API. In the example a deposit is created, a file is added to it, and it is finalized.<br />
<br />
NOTE: The SWORD API is in the process of being moved to the storage service. These URLs may not work.<br />
<br />
<pre># create new deposit<br />
curl -v -H "In-Progress: false" --data-binary @mets.xml --request POST http://localhost:8000/api/v1/space/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/<br />
# response XML includes endpoints for adding addition files, etc.<br />
<br />
# add another file to the transfer<br />
curl -v -H "Content-Disposition: attachment; filename=joke.jpg" --request POST \<br />
--data-binary "@joke.jpg" \<br />
http://127.0.0.1:8000/api/v1/location/9c8b4ac0-0407-4360-a10d-af6c62a48b69/sword/media/<br />
<br />
# finalize transfer and approve processing<br />
curl -v -H "In-Progress: false" --request POST http://127.0.0.1:8000/api/v1/location/149cc29d-6472-4bcf-bee8-f8223bf60580/sword/<br />
</pre><br />
<br />
You might, at some point, want to list the transfers that have been started. The following curl command will do so.<br />
<br />
<pre>curl -v http://localhost:8000/api/v1/location/52bbe770-3f96-4493-8d93-ded54c958c51/sword/collection/</pre><br />
<br />
If you're working on a transfer and want to list what files are included in it, the following curl command will list them.<br />
<br />
<pre># list files in transfer<br />
curl -v http://127.0.0.1:8000/api/v1/location/9c8b4ac0-0407-4360-a10d-af6c62a48b69/sword/media/</pre><br />
<br />
If you've started a deposit, but want to discard it, you can delete the deposit. The following curl command shows an example.<br />
<br />
<pre>curl -v -XDELETE http://127.0.0.1:8000/api/v1/location/149cc29d-6472-4bcf-bee8-f8223bf60580/sword/</pre><br />
<br />
== Synchronous Deposit Examples ==<br />
<br />
If you wanted to deposit a transfer then immediately finalize it you could use something like the following curl command.<br />
<br />
<pre>curl -v -H "In-Progress: false" --data-binary @mets.xml --request POST http://localhost:8000/api/v1/space/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/</pre></div>Mcantelonhttps://wiki.archivematica.org/index.php?title=Meeting_20140108&diff=9303Meeting 201401082014-01-08T19:21:00Z<p>Mcantelon: Created page with "= Archivematica Development = * Holly has been working on getting automated testing into Archivematica - reading about frameworks, how to write tests, starting to set them up..."</p>
<hr />
<div>= Archivematica Development =<br />
<br />
* Holly has been working on getting automated testing into Archivematica - reading about frameworks, how to write tests, starting to set them up in Archivematica (issue #6159).<br />
<br />
* Mike C added the ability to search originals pane, including by accession ID, in SIP browser (issue #6134). The UI implementation was tricky and there's still one bug I'm dealing with.<br />
<br />
* Misty finished up the work from issue #6067 to allow arbitrary non-Unicode paths, which required changes to both the storage service and Archivematica.<br />
<br />
* Misty also diagnosed an issue with the forensic image branch, which turned out to be related to having an old Python dependency installed.<br />
<br />
* Holly quick-fixed issues #6160 and #6161 where format information and associated event weren't getting populated. Will need a solution that better fits with the FPR in future.<br />
<br />
* Holly fixed most of issue #6162 where normalization rules weren't being recorded correctly. Needs update for existing FPR rules (or verification that download of new rules works).<br />
<br />
* Holly started working on verifying/ensuring that the FPR gets updated properly (issue #5825).<br />
<br />
* Mike C added writing of copied files and directories to arrange log file during SIP arrangement (issue #6135).<br />
<br />
* Holly worked on LOCKSS support - implementing the discussed API, and meeting with Mark Jordan yesterday to discuss it in more detail (issues #5425 and #6009).<br />
<br />
* Misty got started on preparations for scalability testing.<br />
<br />
* Mike C fixed issues with adding directories from the SIP arrange panel (issue #6146).<br />
<br />
[[Category:Meetings]]</div>Mcantelonhttps://wiki.archivematica.org/index.php?title=Sword_API&diff=9176Sword API2013-11-29T23:58:02Z<p>Mcantelon: /* Synchronous Deposit Examples */</p>
<hr />
<div><br />
== Overview ==<br />
<br />
One of the 1.1 release features is a sponsored project to integrate Archivematica with Islandora. This integration will be accomplished by creating a [http://swordapp.org Sword] 2.0 API for the Archivematica [https://www.archivematica.org/wiki/Administrator_manual_1.0#Storage_service storage service]. Islandora development work will add functionality to Islandora to use this API to deposit digital objects into Archviematica.<br />
<br />
As described [[Overview|elsewhere]] on this wiki, ''"the primary function of Archivematica is to process digital transfers (accessioned digital objects), turn them into SIPs, apply format policies and create high-quality, repository-independent Archival Information Packages (AIP)"''.<br />
<br />
The Archivematica Sword API allows 3rd party applications to automate the process of creating Transfers. <br />
#Create Transfer - set the name and other metadata about a Transfer<br />
#Populate Transfer - add/edit/update digital objects in a Transfer, and associated metadata<br />
#Finalize Transfer - indicates that the Transfer is ready to start processing.<br />
<br />
After content has been deposited, if users have access to the deposit directory they can also manually manipulate the deposit directory aside from any manipulation using the API.<br />
<br />
Once a Transfer has been created, populated and finalized, Archivematica will begin processing that Transfer.<br />
<br />
== Endpoints ==<br />
<br />
=== Service document ===<br />
<br />
The SWORD service document provides information about the SWORD provider's capacities and lists SWORD collections. Archivematica currently includes one SWORD collection to which SWORD deposits can be made: transfers.<br />
<br />
The SWORD service document endpoint is located at /api/v1/sword.<br />
<br />
=== List existing transfers ===<br />
* HTTP Get to the Collection IRI (defined by default as: /api/v1/space/[space UUID]/sword/collection/)<br />
* Transfers are listed as an Atom feed<br />
* Each Atom feed entry contains an "atom:link" element whose href attribute contains the URL needed to get details about the transfer<br />
* optional filters via get parameters (not yet implemented)<br />
<br />
=== Create a new transfer ===<br />
* used to start a new transfer in Archivematica<br />
* HTTP POST of an Atom Entry Document to the Collection IRI (defined by default as: /api/v1/space/[space UUID]/sword/collection/)<br />
<br />
'''Possible HTTP Response Codes'''<br />
* HTTP 200 OK - transfer already exists (not yet implemented)<br />
* HTTP 201 Created - transfer has been accepted<br />
* HTTP 412 Precondition Failed - required metadata missing or invalid<br />
<br />
Valid requests will receive a Sword Deposit Receipt in the body of the response.<br />
<br />
'''Required HTTP Headers'''<br />
The HTTP POST must include certain specific http headers. <br />
<br />
Required by http 1.1 specification:<br />
* Host: Must be set to archivematica host name.<br />
* Content-Length: Must be set to the length of the atom entry document.<br />
* Content-Type: Must be set to "application/atom+xml;type=entry".<br />
<br />
Required by Archivematica. <br />
* Authorization: Must include the api key and username assigned by Archivematica.<br />
<br />
Required by SWORD 2.0 protocol:<br />
* In-Progress: Must be set to "true"<br />
<br />
Optional in SWORD 2.0 protocol:<br />
* On-Behalf-Of: not implemented by Archivematica<br />
* Slug: not implemented by Archivematica<br />
<br />
'''Required in Body'''<br />
The Body of the request must be a valid METS Document. The required fields in an Atom Entry Document are:<br />
* LABEL: used as the transfer name<br />
* id: used as an accession id (not yet implemented)<br />
* author: used as the source of acquisition (not yet implemented)<br />
* summary: not implemented yet. Could be used in the future as a description for the Transfer<br />
* updated: should be set to the current timestamp. <br />
<br />
'''Example'''<br />
Example HTTP POST request:<br />
<pre><br />
POST /api/v1/space/96606387-cc70-4b09-b422-a7220606488d/sword/collection/ HTTP/1.1<br />
Host: localhost<br />
Authorization: Archivematica-API api_key="XXXXXXXXXXXXXXXXXXXX", username="timh"<br />
Content-Length: 213<br />
Content-Type: application/atom+xml;type=entry<br />
In-Progress: true<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<METS:mets EXT_VERSION="1.1" OBJID="islandora:72" LABEL="Cinderella"<br />
xmlns:METS="http://www.loc.gov/METS/"<br />
xmlns:xlink="http://www.w3.org/1999/xlink"<br />
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"<br />
xsi:schemaLocation="http://www.loc.gov/METS/ http://www.fedora.info/definitions/1/0/mets-fedora-ext1-1.xsd"><br />
<METS:fileSec><br />
<METS:fileGrp ID="DATASTREAMS"><br />
<METS:fileGrp ID="OBJ"><br />
<METS:file ID="OBJ.0"><br />
<METS:FLocat xlink:title="Cinderella_(1865).pdf" LOCTYPE="URL"<br />
xlink:href="http://localhost:8080/fedora/get/islandora:72/OBJ/2013-08-12T14:46:43.454Z" /><br />
</METS:file><br />
</METS:fileGrp><br />
</METS:fileGrp><br />
</METS:fileSec><br />
</METS:mets><br />
</pre><br />
<br />
Example Response:<br />
<pre><br />
201 Created<br />
Location: http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/<br />
<br />
<entry xmlns="http://www.w3.org/2005/Atom"<br />
xmlns:sword="http://purl.org/net/sword/"<br />
xmlns:dcterms="http://purl.org/dc/terms/"><br />
<br />
<title>Cinderella</title><br />
<id>91d4f258-0050-4914-9d0c-6a74815358d2</id><br />
<updated></updated><br />
<generator uri="https://www.archivematica.org" version="1.0"/><br />
<br />
<summary>A deposit was started.</summary><br />
<sword:treatment>A deposit directory was created and, optionally, asynchronous download of digital objects.</sword:treatment><br />
<br />
<link rel="alternate" href="http://www.swordserver.ac.uk/col1/mydeposit.html"/><br />
<link rel="edit-media" href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/media/"/><br />
<link rel="edit" href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/" /><br />
<link rel="http://purl.org/net/sword/terms/add" href="http://192.168.1.76:8000/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/" /><br />
<link rel="http://purl.org/net/sword/terms/statement" type="application/atom+xml;type=feed"<br />
href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/state/" /><br />
</entry><br />
</pre><br />
<br />
=== Add Files to a Transfer ===<br />
<br />
Posting file metadata (not yet implemented):<br />
* POST a METS file to the SE-IRI, listed below.<br />
* HTTP headers are required similar to Create Transfer call (above).<br />
* Body must include a valid Atom Entry document, that has METS embedded inside it.<br />
<br />
Posts file data:<br />
* It is possible to also POST the actual file to a deposit location's EM-IRI (/api/v1/location/[location UUID]/sword/media/)<br />
* The file should be posted as the request body and the filename specified using the Content-Disposition header (as per RFC 6266): for example "Content-Disposition: Attachment; filename=dog.jpg"<br />
* An MD5 checksum for an uploaded file can be provided via the Content-MD5 header (as per RFC 1544): for example "Content-MD5: Q2hlY2sgSW50ZWdyaXR5IQ=="<br />
* If only an Atom Entry Document is POST'ed, Archivematica will look for uri's in the file StructMap section of the METS file, and attempt to GET each file listed, to include in the Transfer. (not yet implemented)<br />
<br />
=== Finalize a Transfer ===<br />
* POST with no body to the SE-IRI<br />
* set In-Progress HTTP header to : false<br />
* This will tell Archivematica that no further content will be added or removed from the Transfer. <br />
* Archivematica will finish fetching any files that were added previously, and once they have all been downloaded, the Transfer will start through the Archivematica pipeline.<br />
<br />
'''Example'''<br />
<pre><br />
POST http://localhost/api/v1/location/55ce8053-113a-4954-8aa3-fc9771da0bda/sword/ HTTP/1.1<br />
Host: localhost<br />
Authorization: Archivematica-API api_key="XXXXXXXXXXXXXXXXXXXX", username="timh"<br />
Content-Length: 0<br />
Content-Type: application/atom+xml;type=entry<br />
In-Progress: false<br />
</pre><br />
<br />
The response will be HTTP 200/OK or 400/Error (400 if the Transfer was already finalized). If the transfer doesn't exist the response will be HTTP 404.<br />
<br />
=== Get Status of Transfer ===<br />
To check Status:<br />
<br />
GET the State-IRI<br />
in this example:<br />
<br />
GET http://localhost/api/v1/location/09224ddb-4c7d-404c-9218-2f2e1b5a599e/sword/state/ HTTP/1.1<br />
<br />
response will include:<br />
<pre><atom:feed xmlns:sword="http://purl.org/net/sword/terms/" <br />
xmlns:atom="http://www.w3.org/2005/Atom"><br />
<br />
<atom:category scheme="http://purl.org/net/sword/terms/state"<br />
term="failed"<br />
label="State"><br />
Deposit initiation: Failed<br />
</atom:category><br />
<br />
</atom:feed></pre><br />
the list of possible descriptions is not finalized.<br />
<br />
The state term value will either be "processing" (asynchronous deposit still working), "complete" (ready to be finalized), or "failed" (asynchronous deposit encountered an error).<br />
<br />
== Additional Details == <br />
<br />
=== Transfer Details ===<br />
* redirect to Edit-IRI<br />
* used to get basic info about a Transfer with HTTP GET<br />
* can update basic info using HTTP PUT (not yet implemented)<br />
* can allow deletion with HTTP DELETE<br />
* follows the form: /api/v1/location/[deposit location UUID]/sword/<br />
* example: http://192.168.1.231:8000/api/v1/location/09224ddb-4c7d-404c-9218-2f2e1b5a599e/sword/<br />
<br />
=== EM-IRI ===<br />
* Edit-Media IRI <br />
* used to add new objects to an existing transfer<br />
* follows the form: [archivematica hostname]/api/v2/transfer/[uuid of transfer]/media<br />
* example: /api/v1/location/[deposit location UUID]/sword/media/<br />
<br />
An HTTP POST to the em-iri for a transfer should include a file as the body<br />
<br />
An HTTP GET should return a list of files in the transfer<br />
<br />
An HTTP DELETE to the em-iri will remove all digital objects from the Transfer. This is a valid operation only while the Transfer is being assembled. Once the Transfer has been finalized, attempting to DELETE will return an error.<br />
<br />
=== Edit-IRI ===<br />
The client can replace the metadata of a resource by performing an HTTP PUT of a new Atom Entry on the Edit-IRI. (not yet implemented)<br />
<br />
This would be used to update metadata about a transfer, such as the transfer name.<br />
<br />
* example: http://localhost/api/v2/transfer/1225c695-cfb8-4ebb-aaaa-80da344efa6a/edit<br />
<br />
=== SE-IRI ===<br />
* example: http://localhost/api/v2/transfer/add/1225c695-cfb8-4ebb-aaaa-80da344efa6a (not yet implemented)<br />
<br />
=== State-IRI ===<br />
* used to retrieve status of transfer<br />
* implemented as Atom document<br />
* example: /api/v1/location/[deposit location UUID]/sword/state/<br />
* should be able to subscribe like RSS feed<br />
<br />
=== Service document ===<br />
<br />
== Configuration ==<br />
<br />
When a transfer deposit is finalized, an Archivematica dashboard can be notified in the background, via a REST API, that the transfer should be approved for processing. In this way the SWORD API can be used to start transfers.<br />
<br />
Each SWORD collection space in a storage service is associated with an Archivematica dashboard. Both the Archivematica dashboard instance and the storage service, however, require configuration.<br />
<br />
On the Archivematica dashboard side, the IP or hostname of the storage service must be added to the REST API whitelist (click "Administration" in the Archivematica navigation bar then "REST API" in the administration sidebar to get to the whitelist page).<br />
<br />
Once you're whitelisted the storage service in the Archivematica dashboard, click "General" in the administration sidebar then note the dashboard UUID. In the storage service administration interface, click "Pipelines" in the navigation bar. Find the UUID matching the dashboard then click "Edit". In the "Remote name" field enter the IP or hostname of the Archivematica dashboard. In the "Api username" field enter an Archivematica dashboard username (click "Administration" in the Archivematica navigation bar then "Users" in the administration sidebar to access the user list). In the "Api key" field enter the user's API key (a user's API key can be found by clicking the "Edit" button corresponding to a specific user on the user list page).<br />
<br />
== Example session ==<br />
<br />
Below is an example session using curl to manipulate the API. In the example a deposit is created, a file is added to it, and it is finalized.<br />
<br />
NOTE: The SWORD API is in the process of being moved to the storage service. These URLs may not work.<br />
<br />
<pre># create new deposit<br />
curl -v -H "In-Progress: false" --data-binary @mets.xml --request POST http://localhost:8000/api/v1/space/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/<br />
# response XML includes endpoints for adding addition files, etc.<br />
<br />
# add another file to the transfer<br />
curl -v -H "Content-Disposition: attachment; filename=joke.jpg" --request POST \<br />
--data-binary "@joke.jpg" \<br />
http://127.0.0.1:8000/api/v1/location/9c8b4ac0-0407-4360-a10d-af6c62a48b69/sword/media/<br />
<br />
# finalize transfer and approve processing<br />
curl -v -H "In-Progress: false" --request POST http://127.0.0.1:8000/api/v1/location/149cc29d-6472-4bcf-bee8-f8223bf60580/sword/<br />
</pre><br />
<br />
You might, at some point, want to list the transfers that have been started. The following curl command will do so.<br />
<br />
<pre>curl -v http://localhost:8000/api/v1/location/52bbe770-3f96-4493-8d93-ded54c958c51/sword/collection/</pre><br />
<br />
If you're working on a transfer and want to list what files are included in it, the following curl command will list them.<br />
<br />
<pre># list files in transfer<br />
curl -v http://127.0.0.1:8000/api/v1/location/9c8b4ac0-0407-4360-a10d-af6c62a48b69/sword/media/</pre><br />
<br />
If you've started a deposit, but want to discard it, you can delete the deposit. The following curl command shows an example.<br />
<br />
<pre>curl -v -XDELETE http://127.0.0.1:8000/api/v1/location/149cc29d-6472-4bcf-bee8-f8223bf60580/sword/</pre><br />
<br />
== Synchronous Deposit Examples ==<br />
<br />
If you wanted to deposit a transfer then immediately finalize it you could use something like the following curl command.<br />
<br />
<pre>curl -v -H "In-Progress: false" --data-binary @mets.xml --request POST http://localhost:8000/api/v1/space/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/</pre></div>Mcantelonhttps://wiki.archivematica.org/index.php?title=Sword_API&diff=9175Sword API2013-11-29T23:55:56Z<p>Mcantelon: /* Example session */</p>
<hr />
<div><br />
== Overview ==<br />
<br />
One of the 1.1 release features is a sponsored project to integrate Archivematica with Islandora. This integration will be accomplished by creating a [http://swordapp.org Sword] 2.0 API for the Archivematica [https://www.archivematica.org/wiki/Administrator_manual_1.0#Storage_service storage service]. Islandora development work will add functionality to Islandora to use this API to deposit digital objects into Archviematica.<br />
<br />
As described [[Overview|elsewhere]] on this wiki, ''"the primary function of Archivematica is to process digital transfers (accessioned digital objects), turn them into SIPs, apply format policies and create high-quality, repository-independent Archival Information Packages (AIP)"''.<br />
<br />
The Archivematica Sword API allows 3rd party applications to automate the process of creating Transfers. <br />
#Create Transfer - set the name and other metadata about a Transfer<br />
#Populate Transfer - add/edit/update digital objects in a Transfer, and associated metadata<br />
#Finalize Transfer - indicates that the Transfer is ready to start processing.<br />
<br />
After content has been deposited, if users have access to the deposit directory they can also manually manipulate the deposit directory aside from any manipulation using the API.<br />
<br />
Once a Transfer has been created, populated and finalized, Archivematica will begin processing that Transfer.<br />
<br />
== Endpoints ==<br />
<br />
=== Service document ===<br />
<br />
The SWORD service document provides information about the SWORD provider's capacities and lists SWORD collections. Archivematica currently includes one SWORD collection to which SWORD deposits can be made: transfers.<br />
<br />
The SWORD service document endpoint is located at /api/v1/sword.<br />
<br />
=== List existing transfers ===<br />
* HTTP Get to the Collection IRI (defined by default as: /api/v1/space/[space UUID]/sword/collection/)<br />
* Transfers are listed as an Atom feed<br />
* Each Atom feed entry contains an "atom:link" element whose href attribute contains the URL needed to get details about the transfer<br />
* optional filters via get parameters (not yet implemented)<br />
<br />
=== Create a new transfer ===<br />
* used to start a new transfer in Archivematica<br />
* HTTP POST of an Atom Entry Document to the Collection IRI (defined by default as: /api/v1/space/[space UUID]/sword/collection/)<br />
<br />
'''Possible HTTP Response Codes'''<br />
* HTTP 200 OK - transfer already exists (not yet implemented)<br />
* HTTP 201 Created - transfer has been accepted<br />
* HTTP 412 Precondition Failed - required metadata missing or invalid<br />
<br />
Valid requests will receive a Sword Deposit Receipt in the body of the response.<br />
<br />
'''Required HTTP Headers'''<br />
The HTTP POST must include certain specific http headers. <br />
<br />
Required by http 1.1 specification:<br />
* Host: Must be set to archivematica host name.<br />
* Content-Length: Must be set to the length of the atom entry document.<br />
* Content-Type: Must be set to "application/atom+xml;type=entry".<br />
<br />
Required by Archivematica. <br />
* Authorization: Must include the api key and username assigned by Archivematica.<br />
<br />
Required by SWORD 2.0 protocol:<br />
* In-Progress: Must be set to "true"<br />
<br />
Optional in SWORD 2.0 protocol:<br />
* On-Behalf-Of: not implemented by Archivematica<br />
* Slug: not implemented by Archivematica<br />
<br />
'''Required in Body'''<br />
The Body of the request must be a valid METS Document. The required fields in an Atom Entry Document are:<br />
* LABEL: used as the transfer name<br />
* id: used as an accession id (not yet implemented)<br />
* author: used as the source of acquisition (not yet implemented)<br />
* summary: not implemented yet. Could be used in the future as a description for the Transfer<br />
* updated: should be set to the current timestamp. <br />
<br />
'''Example'''<br />
Example HTTP POST request:<br />
<pre><br />
POST /api/v1/space/96606387-cc70-4b09-b422-a7220606488d/sword/collection/ HTTP/1.1<br />
Host: localhost<br />
Authorization: Archivematica-API api_key="XXXXXXXXXXXXXXXXXXXX", username="timh"<br />
Content-Length: 213<br />
Content-Type: application/atom+xml;type=entry<br />
In-Progress: true<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<METS:mets EXT_VERSION="1.1" OBJID="islandora:72" LABEL="Cinderella"<br />
xmlns:METS="http://www.loc.gov/METS/"<br />
xmlns:xlink="http://www.w3.org/1999/xlink"<br />
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"<br />
xsi:schemaLocation="http://www.loc.gov/METS/ http://www.fedora.info/definitions/1/0/mets-fedora-ext1-1.xsd"><br />
<METS:fileSec><br />
<METS:fileGrp ID="DATASTREAMS"><br />
<METS:fileGrp ID="OBJ"><br />
<METS:file ID="OBJ.0"><br />
<METS:FLocat xlink:title="Cinderella_(1865).pdf" LOCTYPE="URL"<br />
xlink:href="http://localhost:8080/fedora/get/islandora:72/OBJ/2013-08-12T14:46:43.454Z" /><br />
</METS:file><br />
</METS:fileGrp><br />
</METS:fileGrp><br />
</METS:fileSec><br />
</METS:mets><br />
</pre><br />
<br />
Example Response:<br />
<pre><br />
201 Created<br />
Location: http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/<br />
<br />
<entry xmlns="http://www.w3.org/2005/Atom"<br />
xmlns:sword="http://purl.org/net/sword/"<br />
xmlns:dcterms="http://purl.org/dc/terms/"><br />
<br />
<title>Cinderella</title><br />
<id>91d4f258-0050-4914-9d0c-6a74815358d2</id><br />
<updated></updated><br />
<generator uri="https://www.archivematica.org" version="1.0"/><br />
<br />
<summary>A deposit was started.</summary><br />
<sword:treatment>A deposit directory was created and, optionally, asynchronous download of digital objects.</sword:treatment><br />
<br />
<link rel="alternate" href="http://www.swordserver.ac.uk/col1/mydeposit.html"/><br />
<link rel="edit-media" href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/media/"/><br />
<link rel="edit" href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/" /><br />
<link rel="http://purl.org/net/sword/terms/add" href="http://192.168.1.76:8000/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/" /><br />
<link rel="http://purl.org/net/sword/terms/statement" type="application/atom+xml;type=feed"<br />
href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/state/" /><br />
</entry><br />
</pre><br />
<br />
=== Add Files to a Transfer ===<br />
<br />
Posting file metadata (not yet implemented):<br />
* POST a METS file to the SE-IRI, listed below.<br />
* HTTP headers are required similar to Create Transfer call (above).<br />
* Body must include a valid Atom Entry document, that has METS embedded inside it.<br />
<br />
Posts file data:<br />
* It is possible to also POST the actual file to a deposit location's EM-IRI (/api/v1/location/[location UUID]/sword/media/)<br />
* The file should be posted as the request body and the filename specified using the Content-Disposition header (as per RFC 6266): for example "Content-Disposition: Attachment; filename=dog.jpg"<br />
* An MD5 checksum for an uploaded file can be provided via the Content-MD5 header (as per RFC 1544): for example "Content-MD5: Q2hlY2sgSW50ZWdyaXR5IQ=="<br />
* If only an Atom Entry Document is POST'ed, Archivematica will look for uri's in the file StructMap section of the METS file, and attempt to GET each file listed, to include in the Transfer. (not yet implemented)<br />
<br />
=== Finalize a Transfer ===<br />
* POST with no body to the SE-IRI<br />
* set In-Progress HTTP header to : false<br />
* This will tell Archivematica that no further content will be added or removed from the Transfer. <br />
* Archivematica will finish fetching any files that were added previously, and once they have all been downloaded, the Transfer will start through the Archivematica pipeline.<br />
<br />
'''Example'''<br />
<pre><br />
POST http://localhost/api/v1/location/55ce8053-113a-4954-8aa3-fc9771da0bda/sword/ HTTP/1.1<br />
Host: localhost<br />
Authorization: Archivematica-API api_key="XXXXXXXXXXXXXXXXXXXX", username="timh"<br />
Content-Length: 0<br />
Content-Type: application/atom+xml;type=entry<br />
In-Progress: false<br />
</pre><br />
<br />
The response will be HTTP 200/OK or 400/Error (400 if the Transfer was already finalized). If the transfer doesn't exist the response will be HTTP 404.<br />
<br />
=== Get Status of Transfer ===<br />
To check Status:<br />
<br />
GET the State-IRI<br />
in this example:<br />
<br />
GET http://localhost/api/v1/location/09224ddb-4c7d-404c-9218-2f2e1b5a599e/sword/state/ HTTP/1.1<br />
<br />
response will include:<br />
<pre><atom:feed xmlns:sword="http://purl.org/net/sword/terms/" <br />
xmlns:atom="http://www.w3.org/2005/Atom"><br />
<br />
<atom:category scheme="http://purl.org/net/sword/terms/state"<br />
term="failed"<br />
label="State"><br />
Deposit initiation: Failed<br />
</atom:category><br />
<br />
</atom:feed></pre><br />
the list of possible descriptions is not finalized.<br />
<br />
The state term value will either be "processing" (asynchronous deposit still working), "complete" (ready to be finalized), or "failed" (asynchronous deposit encountered an error).<br />
<br />
== Additional Details == <br />
<br />
=== Transfer Details ===<br />
* redirect to Edit-IRI<br />
* used to get basic info about a Transfer with HTTP GET<br />
* can update basic info using HTTP PUT (not yet implemented)<br />
* can allow deletion with HTTP DELETE<br />
* follows the form: /api/v1/location/[deposit location UUID]/sword/<br />
* example: http://192.168.1.231:8000/api/v1/location/09224ddb-4c7d-404c-9218-2f2e1b5a599e/sword/<br />
<br />
=== EM-IRI ===<br />
* Edit-Media IRI <br />
* used to add new objects to an existing transfer<br />
* follows the form: [archivematica hostname]/api/v2/transfer/[uuid of transfer]/media<br />
* example: /api/v1/location/[deposit location UUID]/sword/media/<br />
<br />
An HTTP POST to the em-iri for a transfer should include a file as the body<br />
<br />
An HTTP GET should return a list of files in the transfer<br />
<br />
An HTTP DELETE to the em-iri will remove all digital objects from the Transfer. This is a valid operation only while the Transfer is being assembled. Once the Transfer has been finalized, attempting to DELETE will return an error.<br />
<br />
=== Edit-IRI ===<br />
The client can replace the metadata of a resource by performing an HTTP PUT of a new Atom Entry on the Edit-IRI. (not yet implemented)<br />
<br />
This would be used to update metadata about a transfer, such as the transfer name.<br />
<br />
* example: http://localhost/api/v2/transfer/1225c695-cfb8-4ebb-aaaa-80da344efa6a/edit<br />
<br />
=== SE-IRI ===<br />
* example: http://localhost/api/v2/transfer/add/1225c695-cfb8-4ebb-aaaa-80da344efa6a (not yet implemented)<br />
<br />
=== State-IRI ===<br />
* used to retrieve status of transfer<br />
* implemented as Atom document<br />
* example: /api/v1/location/[deposit location UUID]/sword/state/<br />
* should be able to subscribe like RSS feed<br />
<br />
=== Service document ===<br />
<br />
== Configuration ==<br />
<br />
When a transfer deposit is finalized, an Archivematica dashboard can be notified in the background, via a REST API, that the transfer should be approved for processing. In this way the SWORD API can be used to start transfers.<br />
<br />
Each SWORD collection space in a storage service is associated with an Archivematica dashboard. Both the Archivematica dashboard instance and the storage service, however, require configuration.<br />
<br />
On the Archivematica dashboard side, the IP or hostname of the storage service must be added to the REST API whitelist (click "Administration" in the Archivematica navigation bar then "REST API" in the administration sidebar to get to the whitelist page).<br />
<br />
Once you're whitelisted the storage service in the Archivematica dashboard, click "General" in the administration sidebar then note the dashboard UUID. In the storage service administration interface, click "Pipelines" in the navigation bar. Find the UUID matching the dashboard then click "Edit". In the "Remote name" field enter the IP or hostname of the Archivematica dashboard. In the "Api username" field enter an Archivematica dashboard username (click "Administration" in the Archivematica navigation bar then "Users" in the administration sidebar to access the user list). In the "Api key" field enter the user's API key (a user's API key can be found by clicking the "Edit" button corresponding to a specific user on the user list page).<br />
<br />
== Example session ==<br />
<br />
Below is an example session using curl to manipulate the API. In the example a deposit is created, a file is added to it, and it is finalized.<br />
<br />
NOTE: The SWORD API is in the process of being moved to the storage service. These URLs may not work.<br />
<br />
<pre># create new deposit<br />
curl -v -H "In-Progress: false" --data-binary @mets.xml --request POST http://localhost:8000/api/v1/space/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/<br />
# response XML includes endpoints for adding addition files, etc.<br />
<br />
# add another file to the transfer<br />
curl -v -H "Content-Disposition: attachment; filename=joke.jpg" --request POST \<br />
--data-binary "@joke.jpg" \<br />
http://127.0.0.1:8000/api/v1/location/9c8b4ac0-0407-4360-a10d-af6c62a48b69/sword/media/<br />
<br />
# finalize transfer and approve processing<br />
curl -v -H "In-Progress: false" --request POST http://127.0.0.1:8000/api/v1/location/149cc29d-6472-4bcf-bee8-f8223bf60580/sword/<br />
</pre><br />
<br />
You might, at some point, want to list the transfers that have been started. The following curl command will do so.<br />
<br />
<pre>curl -v http://localhost:8000/api/v1/location/52bbe770-3f96-4493-8d93-ded54c958c51/sword/collection/</pre><br />
<br />
If you're working on a transfer and want to list what files are included in it, the following curl command will list them.<br />
<br />
<pre># list files in transfer<br />
curl -v http://127.0.0.1:8000/api/v1/location/9c8b4ac0-0407-4360-a10d-af6c62a48b69/sword/media/</pre><br />
<br />
If you've started a deposit, but want to discard it, you can delete the deposit. The following curl command shows an example.<br />
<br />
<pre>curl -v -XDELETE http://127.0.0.1:8000/api/v1/location/149cc29d-6472-4bcf-bee8-f8223bf60580/sword/</pre><br />
<br />
== Synchronous Deposit Examples ==<br />
<br />
If you wanted to deposit a transfer then immediately finalize it you could use something like the following curl command.<br />
<br />
<pre>curl -v -H "In-Progress: false" --data-binary @mets.xml --request POST http://localhost:8000/api/v1/location/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/</pre></div>Mcantelonhttps://wiki.archivematica.org/index.php?title=Sword_API&diff=9174Sword API2013-11-29T23:55:14Z<p>Mcantelon: /* Example session */</p>
<hr />
<div><br />
== Overview ==<br />
<br />
One of the 1.1 release features is a sponsored project to integrate Archivematica with Islandora. This integration will be accomplished by creating a [http://swordapp.org Sword] 2.0 API for the Archivematica [https://www.archivematica.org/wiki/Administrator_manual_1.0#Storage_service storage service]. Islandora development work will add functionality to Islandora to use this API to deposit digital objects into Archviematica.<br />
<br />
As described [[Overview|elsewhere]] on this wiki, ''"the primary function of Archivematica is to process digital transfers (accessioned digital objects), turn them into SIPs, apply format policies and create high-quality, repository-independent Archival Information Packages (AIP)"''.<br />
<br />
The Archivematica Sword API allows 3rd party applications to automate the process of creating Transfers. <br />
#Create Transfer - set the name and other metadata about a Transfer<br />
#Populate Transfer - add/edit/update digital objects in a Transfer, and associated metadata<br />
#Finalize Transfer - indicates that the Transfer is ready to start processing.<br />
<br />
After content has been deposited, if users have access to the deposit directory they can also manually manipulate the deposit directory aside from any manipulation using the API.<br />
<br />
Once a Transfer has been created, populated and finalized, Archivematica will begin processing that Transfer.<br />
<br />
== Endpoints ==<br />
<br />
=== Service document ===<br />
<br />
The SWORD service document provides information about the SWORD provider's capacities and lists SWORD collections. Archivematica currently includes one SWORD collection to which SWORD deposits can be made: transfers.<br />
<br />
The SWORD service document endpoint is located at /api/v1/sword.<br />
<br />
=== List existing transfers ===<br />
* HTTP Get to the Collection IRI (defined by default as: /api/v1/space/[space UUID]/sword/collection/)<br />
* Transfers are listed as an Atom feed<br />
* Each Atom feed entry contains an "atom:link" element whose href attribute contains the URL needed to get details about the transfer<br />
* optional filters via get parameters (not yet implemented)<br />
<br />
=== Create a new transfer ===<br />
* used to start a new transfer in Archivematica<br />
* HTTP POST of an Atom Entry Document to the Collection IRI (defined by default as: /api/v1/space/[space UUID]/sword/collection/)<br />
<br />
'''Possible HTTP Response Codes'''<br />
* HTTP 200 OK - transfer already exists (not yet implemented)<br />
* HTTP 201 Created - transfer has been accepted<br />
* HTTP 412 Precondition Failed - required metadata missing or invalid<br />
<br />
Valid requests will receive a Sword Deposit Receipt in the body of the response.<br />
<br />
'''Required HTTP Headers'''<br />
The HTTP POST must include certain specific http headers. <br />
<br />
Required by http 1.1 specification:<br />
* Host: Must be set to archivematica host name.<br />
* Content-Length: Must be set to the length of the atom entry document.<br />
* Content-Type: Must be set to "application/atom+xml;type=entry".<br />
<br />
Required by Archivematica. <br />
* Authorization: Must include the api key and username assigned by Archivematica.<br />
<br />
Required by SWORD 2.0 protocol:<br />
* In-Progress: Must be set to "true"<br />
<br />
Optional in SWORD 2.0 protocol:<br />
* On-Behalf-Of: not implemented by Archivematica<br />
* Slug: not implemented by Archivematica<br />
<br />
'''Required in Body'''<br />
The Body of the request must be a valid METS Document. The required fields in an Atom Entry Document are:<br />
* LABEL: used as the transfer name<br />
* id: used as an accession id (not yet implemented)<br />
* author: used as the source of acquisition (not yet implemented)<br />
* summary: not implemented yet. Could be used in the future as a description for the Transfer<br />
* updated: should be set to the current timestamp. <br />
<br />
'''Example'''<br />
Example HTTP POST request:<br />
<pre><br />
POST /api/v1/space/96606387-cc70-4b09-b422-a7220606488d/sword/collection/ HTTP/1.1<br />
Host: localhost<br />
Authorization: Archivematica-API api_key="XXXXXXXXXXXXXXXXXXXX", username="timh"<br />
Content-Length: 213<br />
Content-Type: application/atom+xml;type=entry<br />
In-Progress: true<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<METS:mets EXT_VERSION="1.1" OBJID="islandora:72" LABEL="Cinderella"<br />
xmlns:METS="http://www.loc.gov/METS/"<br />
xmlns:xlink="http://www.w3.org/1999/xlink"<br />
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"<br />
xsi:schemaLocation="http://www.loc.gov/METS/ http://www.fedora.info/definitions/1/0/mets-fedora-ext1-1.xsd"><br />
<METS:fileSec><br />
<METS:fileGrp ID="DATASTREAMS"><br />
<METS:fileGrp ID="OBJ"><br />
<METS:file ID="OBJ.0"><br />
<METS:FLocat xlink:title="Cinderella_(1865).pdf" LOCTYPE="URL"<br />
xlink:href="http://localhost:8080/fedora/get/islandora:72/OBJ/2013-08-12T14:46:43.454Z" /><br />
</METS:file><br />
</METS:fileGrp><br />
</METS:fileGrp><br />
</METS:fileSec><br />
</METS:mets><br />
</pre><br />
<br />
Example Response:<br />
<pre><br />
201 Created<br />
Location: http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/<br />
<br />
<entry xmlns="http://www.w3.org/2005/Atom"<br />
xmlns:sword="http://purl.org/net/sword/"<br />
xmlns:dcterms="http://purl.org/dc/terms/"><br />
<br />
<title>Cinderella</title><br />
<id>91d4f258-0050-4914-9d0c-6a74815358d2</id><br />
<updated></updated><br />
<generator uri="https://www.archivematica.org" version="1.0"/><br />
<br />
<summary>A deposit was started.</summary><br />
<sword:treatment>A deposit directory was created and, optionally, asynchronous download of digital objects.</sword:treatment><br />
<br />
<link rel="alternate" href="http://www.swordserver.ac.uk/col1/mydeposit.html"/><br />
<link rel="edit-media" href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/media/"/><br />
<link rel="edit" href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/" /><br />
<link rel="http://purl.org/net/sword/terms/add" href="http://192.168.1.76:8000/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/" /><br />
<link rel="http://purl.org/net/sword/terms/statement" type="application/atom+xml;type=feed"<br />
href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/state/" /><br />
</entry><br />
</pre><br />
<br />
=== Add Files to a Transfer ===<br />
<br />
Posting file metadata (not yet implemented):<br />
* POST a METS file to the SE-IRI, listed below.<br />
* HTTP headers are required similar to Create Transfer call (above).<br />
* Body must include a valid Atom Entry document, that has METS embedded inside it.<br />
<br />
Posts file data:<br />
* It is possible to also POST the actual file to a deposit location's EM-IRI (/api/v1/location/[location UUID]/sword/media/)<br />
* The file should be posted as the request body and the filename specified using the Content-Disposition header (as per RFC 6266): for example "Content-Disposition: Attachment; filename=dog.jpg"<br />
* An MD5 checksum for an uploaded file can be provided via the Content-MD5 header (as per RFC 1544): for example "Content-MD5: Q2hlY2sgSW50ZWdyaXR5IQ=="<br />
* If only an Atom Entry Document is POST'ed, Archivematica will look for uri's in the file StructMap section of the METS file, and attempt to GET each file listed, to include in the Transfer. (not yet implemented)<br />
<br />
=== Finalize a Transfer ===<br />
* POST with no body to the SE-IRI<br />
* set In-Progress HTTP header to : false<br />
* This will tell Archivematica that no further content will be added or removed from the Transfer. <br />
* Archivematica will finish fetching any files that were added previously, and once they have all been downloaded, the Transfer will start through the Archivematica pipeline.<br />
<br />
'''Example'''<br />
<pre><br />
POST http://localhost/api/v1/location/55ce8053-113a-4954-8aa3-fc9771da0bda/sword/ HTTP/1.1<br />
Host: localhost<br />
Authorization: Archivematica-API api_key="XXXXXXXXXXXXXXXXXXXX", username="timh"<br />
Content-Length: 0<br />
Content-Type: application/atom+xml;type=entry<br />
In-Progress: false<br />
</pre><br />
<br />
The response will be HTTP 200/OK or 400/Error (400 if the Transfer was already finalized). If the transfer doesn't exist the response will be HTTP 404.<br />
<br />
=== Get Status of Transfer ===<br />
To check Status:<br />
<br />
GET the State-IRI<br />
in this example:<br />
<br />
GET http://localhost/api/v1/location/09224ddb-4c7d-404c-9218-2f2e1b5a599e/sword/state/ HTTP/1.1<br />
<br />
response will include:<br />
<pre><atom:feed xmlns:sword="http://purl.org/net/sword/terms/" <br />
xmlns:atom="http://www.w3.org/2005/Atom"><br />
<br />
<atom:category scheme="http://purl.org/net/sword/terms/state"<br />
term="failed"<br />
label="State"><br />
Deposit initiation: Failed<br />
</atom:category><br />
<br />
</atom:feed></pre><br />
the list of possible descriptions is not finalized.<br />
<br />
The state term value will either be "processing" (asynchronous deposit still working), "complete" (ready to be finalized), or "failed" (asynchronous deposit encountered an error).<br />
<br />
== Additional Details == <br />
<br />
=== Transfer Details ===<br />
* redirect to Edit-IRI<br />
* used to get basic info about a Transfer with HTTP GET<br />
* can update basic info using HTTP PUT (not yet implemented)<br />
* can allow deletion with HTTP DELETE<br />
* follows the form: /api/v1/location/[deposit location UUID]/sword/<br />
* example: http://192.168.1.231:8000/api/v1/location/09224ddb-4c7d-404c-9218-2f2e1b5a599e/sword/<br />
<br />
=== EM-IRI ===<br />
* Edit-Media IRI <br />
* used to add new objects to an existing transfer<br />
* follows the form: [archivematica hostname]/api/v2/transfer/[uuid of transfer]/media<br />
* example: /api/v1/location/[deposit location UUID]/sword/media/<br />
<br />
An HTTP POST to the em-iri for a transfer should include a file as the body<br />
<br />
An HTTP GET should return a list of files in the transfer<br />
<br />
An HTTP DELETE to the em-iri will remove all digital objects from the Transfer. This is a valid operation only while the Transfer is being assembled. Once the Transfer has been finalized, attempting to DELETE will return an error.<br />
<br />
=== Edit-IRI ===<br />
The client can replace the metadata of a resource by performing an HTTP PUT of a new Atom Entry on the Edit-IRI. (not yet implemented)<br />
<br />
This would be used to update metadata about a transfer, such as the transfer name.<br />
<br />
* example: http://localhost/api/v2/transfer/1225c695-cfb8-4ebb-aaaa-80da344efa6a/edit<br />
<br />
=== SE-IRI ===<br />
* example: http://localhost/api/v2/transfer/add/1225c695-cfb8-4ebb-aaaa-80da344efa6a (not yet implemented)<br />
<br />
=== State-IRI ===<br />
* used to retrieve status of transfer<br />
* implemented as Atom document<br />
* example: /api/v1/location/[deposit location UUID]/sword/state/<br />
* should be able to subscribe like RSS feed<br />
<br />
=== Service document ===<br />
<br />
== Configuration ==<br />
<br />
When a transfer deposit is finalized, an Archivematica dashboard can be notified in the background, via a REST API, that the transfer should be approved for processing. In this way the SWORD API can be used to start transfers.<br />
<br />
Each SWORD collection space in a storage service is associated with an Archivematica dashboard. Both the Archivematica dashboard instance and the storage service, however, require configuration.<br />
<br />
On the Archivematica dashboard side, the IP or hostname of the storage service must be added to the REST API whitelist (click "Administration" in the Archivematica navigation bar then "REST API" in the administration sidebar to get to the whitelist page).<br />
<br />
Once you're whitelisted the storage service in the Archivematica dashboard, click "General" in the administration sidebar then note the dashboard UUID. In the storage service administration interface, click "Pipelines" in the navigation bar. Find the UUID matching the dashboard then click "Edit". In the "Remote name" field enter the IP or hostname of the Archivematica dashboard. In the "Api username" field enter an Archivematica dashboard username (click "Administration" in the Archivematica navigation bar then "Users" in the administration sidebar to access the user list). In the "Api key" field enter the user's API key (a user's API key can be found by clicking the "Edit" button corresponding to a specific user on the user list page).<br />
<br />
== Example session ==<br />
<br />
Below is an example session using curl to manipulate the API. In the example a deposit is created, a file is added to it, and it is finalized.<br />
<br />
NOTE: The SWORD API is in the process of being moved to the storage service. These URLs may not work.<br />
<br />
<pre># create new deposit<br />
curl -v -H "In-Progress: false" --data-binary @mets.xml --request POST http://localhost:8000/api/v1/space/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/<br />
# response XML includes endpoints for adding addition files, etc.<br />
<br />
# add another file to the transfer<br />
curl -v -H "Content-Disposition: attachment; filename=joke.jpg" --request POST \<br />
--data-binary "@joke.jpg" \<br />
http://127.0.0.1:8000/api/v1/location/9c8b4ac0-0407-4360-a10d-af6c62a48b69/sword/media/<br />
<br />
# finalize transfer and approve processing<br />
curl -v -H "In-Progress: false" --request POST http://127.0.0.1:8000/api/v1/location/149cc29d-6472-4bcf-bee8-f8223bf60580/sword/<br />
</pre><br />
<br />
You might, at some point, want to list the transfers that have been started. The following curl command will do so.<br />
<br />
<pre>curl -v http://localhost:8000/api/v1/location/52bbe770-3f96-4493-8d93-ded54c958c51/sword/collection/</pre><br />
<br />
If you're working on a transfer and want to list what files are included in it, the following curl command will list them.<br />
<br />
<pre># list files in transfer<br />
curl -v http://127.0.0.1:8000/api/v1/location/9c8b4ac0-0407-4360-a10d-af6c62a48b69/sword/media/</pre><br />
<br />
If you've started a deposit, but want to discard it, you can delete the deposit. The following curl command shows an example.<br />
<br />
<pre>curl -v -XDELETE http://localhost:8000/api/v1/deposit/8e1cba3c-f133-48b2-afef-e42505a7bdc8/sword/</pre><br />
<br />
== Synchronous Deposit Examples ==<br />
<br />
If you wanted to deposit a transfer then immediately finalize it you could use something like the following curl command.<br />
<br />
<pre>curl -v -H "In-Progress: false" --data-binary @mets.xml --request POST http://localhost:8000/api/v1/location/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/</pre></div>Mcantelonhttps://wiki.archivematica.org/index.php?title=Sword_API&diff=9173Sword API2013-11-29T23:54:14Z<p>Mcantelon: /* Example session */</p>
<hr />
<div><br />
== Overview ==<br />
<br />
One of the 1.1 release features is a sponsored project to integrate Archivematica with Islandora. This integration will be accomplished by creating a [http://swordapp.org Sword] 2.0 API for the Archivematica [https://www.archivematica.org/wiki/Administrator_manual_1.0#Storage_service storage service]. Islandora development work will add functionality to Islandora to use this API to deposit digital objects into Archviematica.<br />
<br />
As described [[Overview|elsewhere]] on this wiki, ''"the primary function of Archivematica is to process digital transfers (accessioned digital objects), turn them into SIPs, apply format policies and create high-quality, repository-independent Archival Information Packages (AIP)"''.<br />
<br />
The Archivematica Sword API allows 3rd party applications to automate the process of creating Transfers. <br />
#Create Transfer - set the name and other metadata about a Transfer<br />
#Populate Transfer - add/edit/update digital objects in a Transfer, and associated metadata<br />
#Finalize Transfer - indicates that the Transfer is ready to start processing.<br />
<br />
After content has been deposited, if users have access to the deposit directory they can also manually manipulate the deposit directory aside from any manipulation using the API.<br />
<br />
Once a Transfer has been created, populated and finalized, Archivematica will begin processing that Transfer.<br />
<br />
== Endpoints ==<br />
<br />
=== Service document ===<br />
<br />
The SWORD service document provides information about the SWORD provider's capacities and lists SWORD collections. Archivematica currently includes one SWORD collection to which SWORD deposits can be made: transfers.<br />
<br />
The SWORD service document endpoint is located at /api/v1/sword.<br />
<br />
=== List existing transfers ===<br />
* HTTP Get to the Collection IRI (defined by default as: /api/v1/space/[space UUID]/sword/collection/)<br />
* Transfers are listed as an Atom feed<br />
* Each Atom feed entry contains an "atom:link" element whose href attribute contains the URL needed to get details about the transfer<br />
* optional filters via get parameters (not yet implemented)<br />
<br />
=== Create a new transfer ===<br />
* used to start a new transfer in Archivematica<br />
* HTTP POST of an Atom Entry Document to the Collection IRI (defined by default as: /api/v1/space/[space UUID]/sword/collection/)<br />
<br />
'''Possible HTTP Response Codes'''<br />
* HTTP 200 OK - transfer already exists (not yet implemented)<br />
* HTTP 201 Created - transfer has been accepted<br />
* HTTP 412 Precondition Failed - required metadata missing or invalid<br />
<br />
Valid requests will receive a Sword Deposit Receipt in the body of the response.<br />
<br />
'''Required HTTP Headers'''<br />
The HTTP POST must include certain specific http headers. <br />
<br />
Required by http 1.1 specification:<br />
* Host: Must be set to archivematica host name.<br />
* Content-Length: Must be set to the length of the atom entry document.<br />
* Content-Type: Must be set to "application/atom+xml;type=entry".<br />
<br />
Required by Archivematica. <br />
* Authorization: Must include the api key and username assigned by Archivematica.<br />
<br />
Required by SWORD 2.0 protocol:<br />
* In-Progress: Must be set to "true"<br />
<br />
Optional in SWORD 2.0 protocol:<br />
* On-Behalf-Of: not implemented by Archivematica<br />
* Slug: not implemented by Archivematica<br />
<br />
'''Required in Body'''<br />
The Body of the request must be a valid METS Document. The required fields in an Atom Entry Document are:<br />
* LABEL: used as the transfer name<br />
* id: used as an accession id (not yet implemented)<br />
* author: used as the source of acquisition (not yet implemented)<br />
* summary: not implemented yet. Could be used in the future as a description for the Transfer<br />
* updated: should be set to the current timestamp. <br />
<br />
'''Example'''<br />
Example HTTP POST request:<br />
<pre><br />
POST /api/v1/space/96606387-cc70-4b09-b422-a7220606488d/sword/collection/ HTTP/1.1<br />
Host: localhost<br />
Authorization: Archivematica-API api_key="XXXXXXXXXXXXXXXXXXXX", username="timh"<br />
Content-Length: 213<br />
Content-Type: application/atom+xml;type=entry<br />
In-Progress: true<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<METS:mets EXT_VERSION="1.1" OBJID="islandora:72" LABEL="Cinderella"<br />
xmlns:METS="http://www.loc.gov/METS/"<br />
xmlns:xlink="http://www.w3.org/1999/xlink"<br />
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"<br />
xsi:schemaLocation="http://www.loc.gov/METS/ http://www.fedora.info/definitions/1/0/mets-fedora-ext1-1.xsd"><br />
<METS:fileSec><br />
<METS:fileGrp ID="DATASTREAMS"><br />
<METS:fileGrp ID="OBJ"><br />
<METS:file ID="OBJ.0"><br />
<METS:FLocat xlink:title="Cinderella_(1865).pdf" LOCTYPE="URL"<br />
xlink:href="http://localhost:8080/fedora/get/islandora:72/OBJ/2013-08-12T14:46:43.454Z" /><br />
</METS:file><br />
</METS:fileGrp><br />
</METS:fileGrp><br />
</METS:fileSec><br />
</METS:mets><br />
</pre><br />
<br />
Example Response:<br />
<pre><br />
201 Created<br />
Location: http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/<br />
<br />
<entry xmlns="http://www.w3.org/2005/Atom"<br />
xmlns:sword="http://purl.org/net/sword/"<br />
xmlns:dcterms="http://purl.org/dc/terms/"><br />
<br />
<title>Cinderella</title><br />
<id>91d4f258-0050-4914-9d0c-6a74815358d2</id><br />
<updated></updated><br />
<generator uri="https://www.archivematica.org" version="1.0"/><br />
<br />
<summary>A deposit was started.</summary><br />
<sword:treatment>A deposit directory was created and, optionally, asynchronous download of digital objects.</sword:treatment><br />
<br />
<link rel="alternate" href="http://www.swordserver.ac.uk/col1/mydeposit.html"/><br />
<link rel="edit-media" href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/media/"/><br />
<link rel="edit" href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/" /><br />
<link rel="http://purl.org/net/sword/terms/add" href="http://192.168.1.76:8000/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/" /><br />
<link rel="http://purl.org/net/sword/terms/statement" type="application/atom+xml;type=feed"<br />
href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/state/" /><br />
</entry><br />
</pre><br />
<br />
=== Add Files to a Transfer ===<br />
<br />
Posting file metadata (not yet implemented):<br />
* POST a METS file to the SE-IRI, listed below.<br />
* HTTP headers are required similar to Create Transfer call (above).<br />
* Body must include a valid Atom Entry document, that has METS embedded inside it.<br />
<br />
Posts file data:<br />
* It is possible to also POST the actual file to a deposit location's EM-IRI (/api/v1/location/[location UUID]/sword/media/)<br />
* The file should be posted as the request body and the filename specified using the Content-Disposition header (as per RFC 6266): for example "Content-Disposition: Attachment; filename=dog.jpg"<br />
* An MD5 checksum for an uploaded file can be provided via the Content-MD5 header (as per RFC 1544): for example "Content-MD5: Q2hlY2sgSW50ZWdyaXR5IQ=="<br />
* If only an Atom Entry Document is POST'ed, Archivematica will look for uri's in the file StructMap section of the METS file, and attempt to GET each file listed, to include in the Transfer. (not yet implemented)<br />
<br />
=== Finalize a Transfer ===<br />
* POST with no body to the SE-IRI<br />
* set In-Progress HTTP header to : false<br />
* This will tell Archivematica that no further content will be added or removed from the Transfer. <br />
* Archivematica will finish fetching any files that were added previously, and once they have all been downloaded, the Transfer will start through the Archivematica pipeline.<br />
<br />
'''Example'''<br />
<pre><br />
POST http://localhost/api/v1/location/55ce8053-113a-4954-8aa3-fc9771da0bda/sword/ HTTP/1.1<br />
Host: localhost<br />
Authorization: Archivematica-API api_key="XXXXXXXXXXXXXXXXXXXX", username="timh"<br />
Content-Length: 0<br />
Content-Type: application/atom+xml;type=entry<br />
In-Progress: false<br />
</pre><br />
<br />
The response will be HTTP 200/OK or 400/Error (400 if the Transfer was already finalized). If the transfer doesn't exist the response will be HTTP 404.<br />
<br />
=== Get Status of Transfer ===<br />
To check Status:<br />
<br />
GET the State-IRI<br />
in this example:<br />
<br />
GET http://localhost/api/v1/location/09224ddb-4c7d-404c-9218-2f2e1b5a599e/sword/state/ HTTP/1.1<br />
<br />
response will include:<br />
<pre><atom:feed xmlns:sword="http://purl.org/net/sword/terms/" <br />
xmlns:atom="http://www.w3.org/2005/Atom"><br />
<br />
<atom:category scheme="http://purl.org/net/sword/terms/state"<br />
term="failed"<br />
label="State"><br />
Deposit initiation: Failed<br />
</atom:category><br />
<br />
</atom:feed></pre><br />
the list of possible descriptions is not finalized.<br />
<br />
The state term value will either be "processing" (asynchronous deposit still working), "complete" (ready to be finalized), or "failed" (asynchronous deposit encountered an error).<br />
<br />
== Additional Details == <br />
<br />
=== Transfer Details ===<br />
* redirect to Edit-IRI<br />
* used to get basic info about a Transfer with HTTP GET<br />
* can update basic info using HTTP PUT (not yet implemented)<br />
* can allow deletion with HTTP DELETE<br />
* follows the form: /api/v1/location/[deposit location UUID]/sword/<br />
* example: http://192.168.1.231:8000/api/v1/location/09224ddb-4c7d-404c-9218-2f2e1b5a599e/sword/<br />
<br />
=== EM-IRI ===<br />
* Edit-Media IRI <br />
* used to add new objects to an existing transfer<br />
* follows the form: [archivematica hostname]/api/v2/transfer/[uuid of transfer]/media<br />
* example: /api/v1/location/[deposit location UUID]/sword/media/<br />
<br />
An HTTP POST to the em-iri for a transfer should include a file as the body<br />
<br />
An HTTP GET should return a list of files in the transfer<br />
<br />
An HTTP DELETE to the em-iri will remove all digital objects from the Transfer. This is a valid operation only while the Transfer is being assembled. Once the Transfer has been finalized, attempting to DELETE will return an error.<br />
<br />
=== Edit-IRI ===<br />
The client can replace the metadata of a resource by performing an HTTP PUT of a new Atom Entry on the Edit-IRI. (not yet implemented)<br />
<br />
This would be used to update metadata about a transfer, such as the transfer name.<br />
<br />
* example: http://localhost/api/v2/transfer/1225c695-cfb8-4ebb-aaaa-80da344efa6a/edit<br />
<br />
=== SE-IRI ===<br />
* example: http://localhost/api/v2/transfer/add/1225c695-cfb8-4ebb-aaaa-80da344efa6a (not yet implemented)<br />
<br />
=== State-IRI ===<br />
* used to retrieve status of transfer<br />
* implemented as Atom document<br />
* example: /api/v1/location/[deposit location UUID]/sword/state/<br />
* should be able to subscribe like RSS feed<br />
<br />
=== Service document ===<br />
<br />
== Configuration ==<br />
<br />
When a transfer deposit is finalized, an Archivematica dashboard can be notified in the background, via a REST API, that the transfer should be approved for processing. In this way the SWORD API can be used to start transfers.<br />
<br />
Each SWORD collection space in a storage service is associated with an Archivematica dashboard. Both the Archivematica dashboard instance and the storage service, however, require configuration.<br />
<br />
On the Archivematica dashboard side, the IP or hostname of the storage service must be added to the REST API whitelist (click "Administration" in the Archivematica navigation bar then "REST API" in the administration sidebar to get to the whitelist page).<br />
<br />
Once you're whitelisted the storage service in the Archivematica dashboard, click "General" in the administration sidebar then note the dashboard UUID. In the storage service administration interface, click "Pipelines" in the navigation bar. Find the UUID matching the dashboard then click "Edit". In the "Remote name" field enter the IP or hostname of the Archivematica dashboard. In the "Api username" field enter an Archivematica dashboard username (click "Administration" in the Archivematica navigation bar then "Users" in the administration sidebar to access the user list). In the "Api key" field enter the user's API key (a user's API key can be found by clicking the "Edit" button corresponding to a specific user on the user list page).<br />
<br />
== Example session ==<br />
<br />
Below is an example session using curl to manipulate the API. In the example a deposit is created, a file is added to it, and it is finalized.<br />
<br />
NOTE: The SWORD API is in the process of being moved to the storage service. These URLs may not work.<br />
<br />
<pre># create new deposit<br />
curl -v -H "In-Progress: false" --data-binary @mets.xml --request POST http://localhost:8000/api/v1/space/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/<br />
# response XML includes endpoints for adding addition files, etc.<br />
<br />
# add another file to the transfer<br />
curl -v -H "Content-Disposition: attachment; filename=joke.jpg" --request POST \<br />
--data-binary "@joke.jpg" \<br />
http://127.0.0.1:8000/api/v1/location/9c8b4ac0-0407-4360-a10d-af6c62a48b69/sword/media/<br />
<br />
# finalize transfer and approve processing<br />
curl -v -H "In-Progress: false" --request POST http://127.0.0.1:8000/api/v1/location/149cc29d-6472-4bcf-bee8-f8223bf60580/sword/<br />
</pre><br />
<br />
You might, at some point, want to list the transfers that have been started. The following curl command will do so.<br />
<br />
<pre>curl -v http://localhost:8000/api/v1/location/52bbe770-3f96-4493-8d93-ded54c958c51/sword/collection/</pre><br />
<br />
If you're working on a transfer and want to list what files are included in it, the following curl command will list them.<br />
<br />
<pre># list files in transfer<br />
curl -v http://192.168.1.231:8000/api/v1/deposit/8e1cba3c-f133-48b2-bdc8/sword/media/</pre><br />
<br />
If you've started a deposit, but want to discard it, you can delete the deposit. The following curl command shows an example.<br />
<br />
<pre>curl -v -XDELETE http://localhost:8000/api/v1/deposit/8e1cba3c-f133-48b2-afef-e42505a7bdc8/sword/</pre><br />
<br />
== Synchronous Deposit Examples ==<br />
<br />
If you wanted to deposit a transfer then immediately finalize it you could use something like the following curl command.<br />
<br />
<pre>curl -v -H "In-Progress: false" --data-binary @mets.xml --request POST http://localhost:8000/api/v1/location/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/</pre></div>Mcantelonhttps://wiki.archivematica.org/index.php?title=Sword_API&diff=9172Sword API2013-11-29T23:13:36Z<p>Mcantelon: </p>
<hr />
<div><br />
== Overview ==<br />
<br />
One of the 1.1 release features is a sponsored project to integrate Archivematica with Islandora. This integration will be accomplished by creating a [http://swordapp.org Sword] 2.0 API for the Archivematica [https://www.archivematica.org/wiki/Administrator_manual_1.0#Storage_service storage service]. Islandora development work will add functionality to Islandora to use this API to deposit digital objects into Archviematica.<br />
<br />
As described [[Overview|elsewhere]] on this wiki, ''"the primary function of Archivematica is to process digital transfers (accessioned digital objects), turn them into SIPs, apply format policies and create high-quality, repository-independent Archival Information Packages (AIP)"''.<br />
<br />
The Archivematica Sword API allows 3rd party applications to automate the process of creating Transfers. <br />
#Create Transfer - set the name and other metadata about a Transfer<br />
#Populate Transfer - add/edit/update digital objects in a Transfer, and associated metadata<br />
#Finalize Transfer - indicates that the Transfer is ready to start processing.<br />
<br />
After content has been deposited, if users have access to the deposit directory they can also manually manipulate the deposit directory aside from any manipulation using the API.<br />
<br />
Once a Transfer has been created, populated and finalized, Archivematica will begin processing that Transfer.<br />
<br />
== Endpoints ==<br />
<br />
=== Service document ===<br />
<br />
The SWORD service document provides information about the SWORD provider's capacities and lists SWORD collections. Archivematica currently includes one SWORD collection to which SWORD deposits can be made: transfers.<br />
<br />
The SWORD service document endpoint is located at /api/v1/sword.<br />
<br />
=== List existing transfers ===<br />
* HTTP Get to the Collection IRI (defined by default as: /api/v1/space/[space UUID]/sword/collection/)<br />
* Transfers are listed as an Atom feed<br />
* Each Atom feed entry contains an "atom:link" element whose href attribute contains the URL needed to get details about the transfer<br />
* optional filters via get parameters (not yet implemented)<br />
<br />
=== Create a new transfer ===<br />
* used to start a new transfer in Archivematica<br />
* HTTP POST of an Atom Entry Document to the Collection IRI (defined by default as: /api/v1/space/[space UUID]/sword/collection/)<br />
<br />
'''Possible HTTP Response Codes'''<br />
* HTTP 200 OK - transfer already exists (not yet implemented)<br />
* HTTP 201 Created - transfer has been accepted<br />
* HTTP 412 Precondition Failed - required metadata missing or invalid<br />
<br />
Valid requests will receive a Sword Deposit Receipt in the body of the response.<br />
<br />
'''Required HTTP Headers'''<br />
The HTTP POST must include certain specific http headers. <br />
<br />
Required by http 1.1 specification:<br />
* Host: Must be set to archivematica host name.<br />
* Content-Length: Must be set to the length of the atom entry document.<br />
* Content-Type: Must be set to "application/atom+xml;type=entry".<br />
<br />
Required by Archivematica. <br />
* Authorization: Must include the api key and username assigned by Archivematica.<br />
<br />
Required by SWORD 2.0 protocol:<br />
* In-Progress: Must be set to "true"<br />
<br />
Optional in SWORD 2.0 protocol:<br />
* On-Behalf-Of: not implemented by Archivematica<br />
* Slug: not implemented by Archivematica<br />
<br />
'''Required in Body'''<br />
The Body of the request must be a valid METS Document. The required fields in an Atom Entry Document are:<br />
* LABEL: used as the transfer name<br />
* id: used as an accession id (not yet implemented)<br />
* author: used as the source of acquisition (not yet implemented)<br />
* summary: not implemented yet. Could be used in the future as a description for the Transfer<br />
* updated: should be set to the current timestamp. <br />
<br />
'''Example'''<br />
Example HTTP POST request:<br />
<pre><br />
POST /api/v1/space/96606387-cc70-4b09-b422-a7220606488d/sword/collection/ HTTP/1.1<br />
Host: localhost<br />
Authorization: Archivematica-API api_key="XXXXXXXXXXXXXXXXXXXX", username="timh"<br />
Content-Length: 213<br />
Content-Type: application/atom+xml;type=entry<br />
In-Progress: true<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<METS:mets EXT_VERSION="1.1" OBJID="islandora:72" LABEL="Cinderella"<br />
xmlns:METS="http://www.loc.gov/METS/"<br />
xmlns:xlink="http://www.w3.org/1999/xlink"<br />
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"<br />
xsi:schemaLocation="http://www.loc.gov/METS/ http://www.fedora.info/definitions/1/0/mets-fedora-ext1-1.xsd"><br />
<METS:fileSec><br />
<METS:fileGrp ID="DATASTREAMS"><br />
<METS:fileGrp ID="OBJ"><br />
<METS:file ID="OBJ.0"><br />
<METS:FLocat xlink:title="Cinderella_(1865).pdf" LOCTYPE="URL"<br />
xlink:href="http://localhost:8080/fedora/get/islandora:72/OBJ/2013-08-12T14:46:43.454Z" /><br />
</METS:file><br />
</METS:fileGrp><br />
</METS:fileGrp><br />
</METS:fileSec><br />
</METS:mets><br />
</pre><br />
<br />
Example Response:<br />
<pre><br />
201 Created<br />
Location: http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/<br />
<br />
<entry xmlns="http://www.w3.org/2005/Atom"<br />
xmlns:sword="http://purl.org/net/sword/"<br />
xmlns:dcterms="http://purl.org/dc/terms/"><br />
<br />
<title>Cinderella</title><br />
<id>91d4f258-0050-4914-9d0c-6a74815358d2</id><br />
<updated></updated><br />
<generator uri="https://www.archivematica.org" version="1.0"/><br />
<br />
<summary>A deposit was started.</summary><br />
<sword:treatment>A deposit directory was created and, optionally, asynchronous download of digital objects.</sword:treatment><br />
<br />
<link rel="alternate" href="http://www.swordserver.ac.uk/col1/mydeposit.html"/><br />
<link rel="edit-media" href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/media/"/><br />
<link rel="edit" href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/" /><br />
<link rel="http://purl.org/net/sword/terms/add" href="http://192.168.1.76:8000/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/" /><br />
<link rel="http://purl.org/net/sword/terms/statement" type="application/atom+xml;type=feed"<br />
href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/state/" /><br />
</entry><br />
</pre><br />
<br />
=== Add Files to a Transfer ===<br />
<br />
Posting file metadata (not yet implemented):<br />
* POST a METS file to the SE-IRI, listed below.<br />
* HTTP headers are required similar to Create Transfer call (above).<br />
* Body must include a valid Atom Entry document, that has METS embedded inside it.<br />
<br />
Posts file data:<br />
* It is possible to also POST the actual file to a deposit location's EM-IRI (/api/v1/location/[location UUID]/sword/media/)<br />
* The file should be posted as the request body and the filename specified using the Content-Disposition header (as per RFC 6266): for example "Content-Disposition: Attachment; filename=dog.jpg"<br />
* An MD5 checksum for an uploaded file can be provided via the Content-MD5 header (as per RFC 1544): for example "Content-MD5: Q2hlY2sgSW50ZWdyaXR5IQ=="<br />
* If only an Atom Entry Document is POST'ed, Archivematica will look for uri's in the file StructMap section of the METS file, and attempt to GET each file listed, to include in the Transfer. (not yet implemented)<br />
<br />
=== Finalize a Transfer ===<br />
* POST with no body to the SE-IRI<br />
* set In-Progress HTTP header to : false<br />
* This will tell Archivematica that no further content will be added or removed from the Transfer. <br />
* Archivematica will finish fetching any files that were added previously, and once they have all been downloaded, the Transfer will start through the Archivematica pipeline.<br />
<br />
'''Example'''<br />
<pre><br />
POST http://localhost/api/v1/location/55ce8053-113a-4954-8aa3-fc9771da0bda/sword/ HTTP/1.1<br />
Host: localhost<br />
Authorization: Archivematica-API api_key="XXXXXXXXXXXXXXXXXXXX", username="timh"<br />
Content-Length: 0<br />
Content-Type: application/atom+xml;type=entry<br />
In-Progress: false<br />
</pre><br />
<br />
The response will be HTTP 200/OK or 400/Error (400 if the Transfer was already finalized). If the transfer doesn't exist the response will be HTTP 404.<br />
<br />
=== Get Status of Transfer ===<br />
To check Status:<br />
<br />
GET the State-IRI<br />
in this example:<br />
<br />
GET http://localhost/api/v1/location/09224ddb-4c7d-404c-9218-2f2e1b5a599e/sword/state/ HTTP/1.1<br />
<br />
response will include:<br />
<pre><atom:feed xmlns:sword="http://purl.org/net/sword/terms/" <br />
xmlns:atom="http://www.w3.org/2005/Atom"><br />
<br />
<atom:category scheme="http://purl.org/net/sword/terms/state"<br />
term="failed"<br />
label="State"><br />
Deposit initiation: Failed<br />
</atom:category><br />
<br />
</atom:feed></pre><br />
the list of possible descriptions is not finalized.<br />
<br />
The state term value will either be "processing" (asynchronous deposit still working), "complete" (ready to be finalized), or "failed" (asynchronous deposit encountered an error).<br />
<br />
== Additional Details == <br />
<br />
=== Transfer Details ===<br />
* redirect to Edit-IRI<br />
* used to get basic info about a Transfer with HTTP GET<br />
* can update basic info using HTTP PUT (not yet implemented)<br />
* can allow deletion with HTTP DELETE<br />
* follows the form: /api/v1/location/[deposit location UUID]/sword/<br />
* example: http://192.168.1.231:8000/api/v1/location/09224ddb-4c7d-404c-9218-2f2e1b5a599e/sword/<br />
<br />
=== EM-IRI ===<br />
* Edit-Media IRI <br />
* used to add new objects to an existing transfer<br />
* follows the form: [archivematica hostname]/api/v2/transfer/[uuid of transfer]/media<br />
* example: /api/v1/location/[deposit location UUID]/sword/media/<br />
<br />
An HTTP POST to the em-iri for a transfer should include a file as the body<br />
<br />
An HTTP GET should return a list of files in the transfer<br />
<br />
An HTTP DELETE to the em-iri will remove all digital objects from the Transfer. This is a valid operation only while the Transfer is being assembled. Once the Transfer has been finalized, attempting to DELETE will return an error.<br />
<br />
=== Edit-IRI ===<br />
The client can replace the metadata of a resource by performing an HTTP PUT of a new Atom Entry on the Edit-IRI. (not yet implemented)<br />
<br />
This would be used to update metadata about a transfer, such as the transfer name.<br />
<br />
* example: http://localhost/api/v2/transfer/1225c695-cfb8-4ebb-aaaa-80da344efa6a/edit<br />
<br />
=== SE-IRI ===<br />
* example: http://localhost/api/v2/transfer/add/1225c695-cfb8-4ebb-aaaa-80da344efa6a (not yet implemented)<br />
<br />
=== State-IRI ===<br />
* used to retrieve status of transfer<br />
* implemented as Atom document<br />
* example: /api/v1/location/[deposit location UUID]/sword/state/<br />
* should be able to subscribe like RSS feed<br />
<br />
=== Service document ===<br />
<br />
== Configuration ==<br />
<br />
When a transfer deposit is finalized, an Archivematica dashboard can be notified in the background, via a REST API, that the transfer should be approved for processing. In this way the SWORD API can be used to start transfers.<br />
<br />
Each SWORD collection space in a storage service is associated with an Archivematica dashboard. Both the Archivematica dashboard instance and the storage service, however, require configuration.<br />
<br />
On the Archivematica dashboard side, the IP or hostname of the storage service must be added to the REST API whitelist (click "Administration" in the Archivematica navigation bar then "REST API" in the administration sidebar to get to the whitelist page).<br />
<br />
Once you're whitelisted the storage service in the Archivematica dashboard, click "General" in the administration sidebar then note the dashboard UUID. In the storage service administration interface, click "Pipelines" in the navigation bar. Find the UUID matching the dashboard then click "Edit". In the "Remote name" field enter the IP or hostname of the Archivematica dashboard. In the "Api username" field enter an Archivematica dashboard username (click "Administration" in the Archivematica navigation bar then "Users" in the administration sidebar to access the user list). In the "Api key" field enter the user's API key (a user's API key can be found by clicking the "Edit" button corresponding to a specific user on the user list page).<br />
<br />
== Example session ==<br />
<br />
Below is an example session using curl to manipulate the API. In the example a deposit is created, a file is added to it, and it is finalized.<br />
<br />
NOTE: The SWORD API is in the process of being moved to the storage service. These URLs may not work.<br />
<br />
<pre># create new deposit<br />
curl -v -H "In-Progress: true" --data-binary @mets.xml --request POST http://localhost:8000/api/v1/location/52bbe770-3f96-4493-8d93-ded54c958c51/sword/collection/<br />
# response XML includes endpoints for adding addition files, etc.<br />
<br />
# add another file to the transfer<br />
curl -v -H "Content-Disposition: attachment; filename=joke.jpg" --request POST \<br />
--data-binary "@joke.jpg" \<br />
http://localhost:8000/api/v1/deposit/8e1cba3c-f133-48b2-afef-e42505a7bdc8/sword/media/<br />
<br />
# finalize transfer and approve processing<br />
curl -v -H "In-Progress: false" --request POST http://localhost:8000/api/v1/deposit/8e1cba3c-f133-48b2-afef-e42505a7bdc8/sword/</pre><br />
<br />
You might, at some point, want to list the transfers that have been started. The following curl command will do so.<br />
<br />
<pre>curl -v http://localhost:8000/api/v1/location/52bbe770-3f96-4493-8d93-ded54c958c51/sword/collection/</pre><br />
<br />
If you're working on a transfer and want to list what files are included in it, the following curl command will list them.<br />
<br />
<pre># list files in transfer<br />
curl -v http://192.168.1.231:8000/api/v1/deposit/8e1cba3c-f133-48b2-bdc8/sword/media/</pre><br />
<br />
If you've started a deposit, but want to discard it, you can delete the deposit. The following curl command shows an example.<br />
<br />
<pre>curl -v -XDELETE http://localhost:8000/api/v1/deposit/8e1cba3c-f133-48b2-afef-e42505a7bdc8/sword/</pre><br />
<br />
== Synchronous Deposit Examples ==<br />
<br />
If you wanted to deposit a transfer then immediately finalize it you could use something like the following curl command.<br />
<br />
<pre>curl -v -H "In-Progress: false" --data-binary @mets.xml --request POST http://localhost:8000/api/v1/location/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/</pre></div>Mcantelonhttps://wiki.archivematica.org/index.php?title=Sword_API&diff=9171Sword API2013-11-29T23:12:18Z<p>Mcantelon: /* Dashboard configuration */</p>
<hr />
<div><br />
== Overview ==<br />
<br />
One of the 1.1 release features is a sponsored project to integrate Archivematica with Islandora. This integration will be accomplished by creating a [http://swordapp.org Sword] 2.0 API for the Archivematica [https://www.archivematica.org/wiki/Administrator_manual_1.0#Storage_service storage service]. Islandora development work will add functionality to Islandora to use this API to deposit digital objects into Archviematica.<br />
<br />
As described [[Overview|elsewhere]] on this wiki, ''"the primary function of Archivematica is to process digital transfers (accessioned digital objects), turn them into SIPs, apply format policies and create high-quality, repository-independent Archival Information Packages (AIP)"''.<br />
<br />
The Archivematica Sword API allows 3rd party applications to automate the process of creating Transfers. <br />
#Create Transfer - set the name and other metadata about a Transfer<br />
#Populate Transfer - add/edit/update digital objects in a Transfer, and associated metadata<br />
#Finalize Transfer - indicates that the Transfer is ready to start processing.<br />
<br />
After content has been deposited, if users have access to the deposit directory they can also manually manipulate the deposit directory aside from any manipulation using the API.<br />
<br />
Once a Transfer has been created, populated and finalized, Archivematica will begin processing that Transfer.<br />
<br />
== Endpoints ==<br />
<br />
=== Service document ===<br />
<br />
The SWORD service document provides information about the SWORD provider's capacities and lists SWORD collections. Archivematica currently includes one SWORD collection to which SWORD deposits can be made: transfers.<br />
<br />
The SWORD service document endpoint is located at /api/v1/sword.<br />
<br />
=== List existing transfers ===<br />
* HTTP Get to the Collection IRI (defined by default as: /api/v1/space/[space UUID]/sword/collection/)<br />
* Transfers are listed as an Atom feed<br />
* Each Atom feed entry contains an "atom:link" element whose href attribute contains the URL needed to get details about the transfer<br />
* optional filters via get parameters (not yet implemented)<br />
<br />
=== Create a new transfer ===<br />
* used to start a new transfer in Archivematica<br />
* HTTP POST of an Atom Entry Document to the Collection IRI (defined by default as: /api/v1/space/[space UUID]/sword/collection/)<br />
<br />
'''Possible HTTP Response Codes'''<br />
* HTTP 200 OK - transfer already exists (not yet implemented)<br />
* HTTP 201 Created - transfer has been accepted<br />
* HTTP 412 Precondition Failed - required metadata missing or invalid<br />
<br />
Valid requests will receive a Sword Deposit Receipt in the body of the response.<br />
<br />
'''Required HTTP Headers'''<br />
The HTTP POST must include certain specific http headers. <br />
<br />
Required by http 1.1 specification:<br />
* Host: Must be set to archivematica host name.<br />
* Content-Length: Must be set to the length of the atom entry document.<br />
* Content-Type: Must be set to "application/atom+xml;type=entry".<br />
<br />
Required by Archivematica. <br />
* Authorization: Must include the api key and username assigned by Archivematica.<br />
<br />
Required by SWORD 2.0 protocol:<br />
* In-Progress: Must be set to "true"<br />
<br />
Optional in SWORD 2.0 protocol:<br />
* On-Behalf-Of: not implemented by Archivematica<br />
* Slug: not implemented by Archivematica<br />
<br />
'''Required in Body'''<br />
The Body of the request must be a valid METS Document. The required fields in an Atom Entry Document are:<br />
* LABEL: used as the transfer name<br />
* id: used as an accession id (not yet implemented)<br />
* author: used as the source of acquisition (not yet implemented)<br />
* summary: not implemented yet. Could be used in the future as a description for the Transfer<br />
* updated: should be set to the current timestamp. <br />
<br />
'''Example'''<br />
Example HTTP POST request:<br />
<pre><br />
POST /api/v1/space/96606387-cc70-4b09-b422-a7220606488d/sword/collection/ HTTP/1.1<br />
Host: localhost<br />
Authorization: Archivematica-API api_key="XXXXXXXXXXXXXXXXXXXX", username="timh"<br />
Content-Length: 213<br />
Content-Type: application/atom+xml;type=entry<br />
In-Progress: true<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<METS:mets EXT_VERSION="1.1" OBJID="islandora:72" LABEL="Cinderella"<br />
xmlns:METS="http://www.loc.gov/METS/"<br />
xmlns:xlink="http://www.w3.org/1999/xlink"<br />
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"<br />
xsi:schemaLocation="http://www.loc.gov/METS/ http://www.fedora.info/definitions/1/0/mets-fedora-ext1-1.xsd"><br />
<METS:fileSec><br />
<METS:fileGrp ID="DATASTREAMS"><br />
<METS:fileGrp ID="OBJ"><br />
<METS:file ID="OBJ.0"><br />
<METS:FLocat xlink:title="Cinderella_(1865).pdf" LOCTYPE="URL"<br />
xlink:href="http://localhost:8080/fedora/get/islandora:72/OBJ/2013-08-12T14:46:43.454Z" /><br />
</METS:file><br />
</METS:fileGrp><br />
</METS:fileGrp><br />
</METS:fileSec><br />
</METS:mets><br />
</pre><br />
<br />
Example Response:<br />
<pre><br />
201 Created<br />
Location: http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/<br />
<br />
<entry xmlns="http://www.w3.org/2005/Atom"<br />
xmlns:sword="http://purl.org/net/sword/"<br />
xmlns:dcterms="http://purl.org/dc/terms/"><br />
<br />
<title>Cinderella</title><br />
<id>91d4f258-0050-4914-9d0c-6a74815358d2</id><br />
<updated></updated><br />
<generator uri="https://www.archivematica.org" version="1.0"/><br />
<br />
<summary>A deposit was started.</summary><br />
<sword:treatment>A deposit directory was created and, optionally, asynchronous download of digital objects.</sword:treatment><br />
<br />
<link rel="alternate" href="http://www.swordserver.ac.uk/col1/mydeposit.html"/><br />
<link rel="edit-media" href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/media/"/><br />
<link rel="edit" href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/" /><br />
<link rel="http://purl.org/net/sword/terms/add" href="http://192.168.1.76:8000/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/" /><br />
<link rel="http://purl.org/net/sword/terms/statement" type="application/atom+xml;type=feed"<br />
href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/state/" /><br />
</entry><br />
</pre><br />
<br />
=== Add Files to a Transfer ===<br />
<br />
Posting file metadata (not yet implemented):<br />
* POST a METS file to the SE-IRI, listed below.<br />
* HTTP headers are required similar to Create Transfer call (above).<br />
* Body must include a valid Atom Entry document, that has METS embedded inside it.<br />
<br />
Posts file data:<br />
* It is possible to also POST the actual file to a deposit location's EM-IRI (/api/v1/location/[location UUID]/sword/media/)<br />
* The file should be posted as the request body and the filename specified using the Content-Disposition header (as per RFC 6266): for example "Content-Disposition: Attachment; filename=dog.jpg"<br />
* An MD5 checksum for an uploaded file can be provided via the Content-MD5 header (as per RFC 1544): for example "Content-MD5: Q2hlY2sgSW50ZWdyaXR5IQ=="<br />
* If only an Atom Entry Document is POST'ed, Archivematica will look for uri's in the file StructMap section of the METS file, and attempt to GET each file listed, to include in the Transfer. (not yet implemented)<br />
<br />
=== Finalize a Transfer ===<br />
* POST with no body to the SE-IRI<br />
* set In-Progress HTTP header to : false<br />
* This will tell Archivematica that no further content will be added or removed from the Transfer. <br />
* Archivematica will finish fetching any files that were added previously, and once they have all been downloaded, the Transfer will start through the Archivematica pipeline.<br />
<br />
'''Example'''<br />
<pre><br />
POST http://localhost/api/v1/location/55ce8053-113a-4954-8aa3-fc9771da0bda/sword/ HTTP/1.1<br />
Host: localhost<br />
Authorization: Archivematica-API api_key="XXXXXXXXXXXXXXXXXXXX", username="timh"<br />
Content-Length: 0<br />
Content-Type: application/atom+xml;type=entry<br />
In-Progress: false<br />
</pre><br />
<br />
The response will be HTTP 200/OK or 400/Error (400 if the Transfer was already finalized). If the transfer doesn't exist the response will be HTTP 404.<br />
<br />
=== Get Status of Transfer ===<br />
To check Status:<br />
<br />
GET the State-IRI<br />
in this example:<br />
<br />
GET http://localhost/api/v1/location/09224ddb-4c7d-404c-9218-2f2e1b5a599e/sword/state/ HTTP/1.1<br />
<br />
response will include:<br />
<pre><atom:feed xmlns:sword="http://purl.org/net/sword/terms/" <br />
xmlns:atom="http://www.w3.org/2005/Atom"><br />
<br />
<atom:category scheme="http://purl.org/net/sword/terms/state"<br />
term="failed"<br />
label="State"><br />
Deposit initiation: Failed<br />
</atom:category><br />
<br />
</atom:feed></pre><br />
the list of possible descriptions is not finalized.<br />
<br />
The state term value will either be "processing" (asynchronous deposit still working), "complete" (ready to be finalized), or "failed" (asynchronous deposit encountered an error).<br />
<br />
== Additional Details == <br />
<br />
=== Transfer Details ===<br />
* redirect to Edit-IRI<br />
* used to get basic info about a Transfer with HTTP GET<br />
* can update basic info using HTTP PUT (not yet implemented)<br />
* can allow deletion with HTTP DELETE<br />
* follows the form: /api/v1/location/[deposit location UUID]/sword/<br />
* example: http://192.168.1.231:8000/api/v1/location/09224ddb-4c7d-404c-9218-2f2e1b5a599e/sword/<br />
<br />
=== EM-IRI ===<br />
* Edit-Media IRI <br />
* used to add new objects to an existing transfer<br />
* follows the form: [archivematica hostname]/api/v2/transfer/[uuid of transfer]/media<br />
* example: /api/v1/location/[deposit location UUID]/sword/media/<br />
<br />
An HTTP POST to the em-iri for a transfer should include a file as the body<br />
<br />
An HTTP GET should return a list of files in the transfer<br />
<br />
An HTTP DELETE to the em-iri will remove all digital objects from the Transfer. This is a valid operation only while the Transfer is being assembled. Once the Transfer has been finalized, attempting to DELETE will return an error.<br />
<br />
=== Edit-IRI ===<br />
The client can replace the metadata of a resource by performing an HTTP PUT of a new Atom Entry on the Edit-IRI. (not yet implemented)<br />
<br />
This would be used to update metadata about a transfer, such as the transfer name.<br />
<br />
* example: http://localhost/api/v2/transfer/1225c695-cfb8-4ebb-aaaa-80da344efa6a/edit<br />
<br />
=== SE-IRI ===<br />
* example: http://localhost/api/v2/transfer/add/1225c695-cfb8-4ebb-aaaa-80da344efa6a (not yet implemented)<br />
<br />
=== State-IRI ===<br />
* used to retrieve status of transfer<br />
* implemented as Atom document<br />
* example: /api/v1/location/[deposit location UUID]/sword/state/<br />
* should be able to subscribe like RSS feed<br />
<br />
=== Service document ===<br />
<br />
== Dashboard configuration ==<br />
<br />
When a transfer deposit is finalized, an Archivematica dashboard can be notified in the background, via a REST API, that the transfer should be approved for processing. In this way the SWORD API can be used to start transfers.<br />
<br />
Each SWORD collection space in a storage service is associated with an Archivematica dashboard. Both the Archivematica dashboard instance and the storage service, however, require configuration.<br />
<br />
On the Archivematica dashboard side, the IP or hostname of the storage service must be added to the REST API whitelist (click "Administration" in the Archivematica navigation bar then "REST API" in the administration sidebar to get to the whitelist page).<br />
<br />
Once you're whitelisted the storage service in the Archivematica dashboard, click "General" in the administration sidebar then note the dashboard UUID. In the storage service administration interface, click "Pipelines" in the navigation bar. Find the UUID matching the dashboard then click "Edit". In the "Remote name" field enter the IP or hostname of the Archivematica dashboard. In the "Api username" field enter an Archivematica dashboard username (click "Administration" in the Archivematica navigation bar then "Users" in the administration sidebar to access the user list). In the "Api key" field enter the user's API key (a user's API key can be found by clicking the "Edit" button corresponding to a specific user on the user list page).<br />
<br />
== Example session ==<br />
<br />
Below is an example session using curl to manipulate the API. In the example a deposit is created, a file is added to it, and it is finalized.<br />
<br />
NOTE: The SWORD API is in the process of being moved to the storage service. These URLs may not work.<br />
<br />
<pre># create new deposit<br />
curl -v -H "In-Progress: true" --data-binary @mets.xml --request POST http://localhost:8000/api/v1/location/52bbe770-3f96-4493-8d93-ded54c958c51/sword/collection/<br />
# response XML includes endpoints for adding addition files, etc.<br />
<br />
# add another file to the transfer<br />
curl -v -H "Content-Disposition: attachment; filename=joke.jpg" --request POST \<br />
--data-binary "@joke.jpg" \<br />
http://localhost:8000/api/v1/deposit/8e1cba3c-f133-48b2-afef-e42505a7bdc8/sword/media/<br />
<br />
# finalize transfer and approve processing<br />
curl -v -H "In-Progress: false" --request POST http://localhost:8000/api/v1/deposit/8e1cba3c-f133-48b2-afef-e42505a7bdc8/sword/</pre><br />
<br />
You might, at some point, want to list the transfers that have been started. The following curl command will do so.<br />
<br />
<pre>curl -v http://localhost:8000/api/v1/location/52bbe770-3f96-4493-8d93-ded54c958c51/sword/collection/</pre><br />
<br />
If you're working on a transfer and want to list what files are included in it, the following curl command will list them.<br />
<br />
<pre># list files in transfer<br />
curl -v http://192.168.1.231:8000/api/v1/deposit/8e1cba3c-f133-48b2-bdc8/sword/media/</pre><br />
<br />
If you've started a deposit, but want to discard it, you can delete the deposit. The following curl command shows an example.<br />
<br />
<pre>curl -v -XDELETE http://localhost:8000/api/v1/deposit/8e1cba3c-f133-48b2-afef-e42505a7bdc8/sword/</pre><br />
<br />
== Synchronous Deposit Examples ==<br />
<br />
If you wanted to deposit a transfer then immediately finalize it you could use something like the following curl command.<br />
<br />
<pre>curl -v -H "In-Progress: false" --data-binary @mets.xml --request POST http://localhost:8000/api/v1/location/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/</pre></div>Mcantelonhttps://wiki.archivematica.org/index.php?title=Sword_API&diff=9170Sword API2013-11-29T23:08:34Z<p>Mcantelon: </p>
<hr />
<div><br />
== Overview ==<br />
<br />
One of the 1.1 release features is a sponsored project to integrate Archivematica with Islandora. This integration will be accomplished by creating a [http://swordapp.org Sword] 2.0 API for the Archivematica [https://www.archivematica.org/wiki/Administrator_manual_1.0#Storage_service storage service]. Islandora development work will add functionality to Islandora to use this API to deposit digital objects into Archviematica.<br />
<br />
As described [[Overview|elsewhere]] on this wiki, ''"the primary function of Archivematica is to process digital transfers (accessioned digital objects), turn them into SIPs, apply format policies and create high-quality, repository-independent Archival Information Packages (AIP)"''.<br />
<br />
The Archivematica Sword API allows 3rd party applications to automate the process of creating Transfers. <br />
#Create Transfer - set the name and other metadata about a Transfer<br />
#Populate Transfer - add/edit/update digital objects in a Transfer, and associated metadata<br />
#Finalize Transfer - indicates that the Transfer is ready to start processing.<br />
<br />
After content has been deposited, if users have access to the deposit directory they can also manually manipulate the deposit directory aside from any manipulation using the API.<br />
<br />
Once a Transfer has been created, populated and finalized, Archivematica will begin processing that Transfer.<br />
<br />
== Endpoints ==<br />
<br />
=== Service document ===<br />
<br />
The SWORD service document provides information about the SWORD provider's capacities and lists SWORD collections. Archivematica currently includes one SWORD collection to which SWORD deposits can be made: transfers.<br />
<br />
The SWORD service document endpoint is located at /api/v1/sword.<br />
<br />
=== List existing transfers ===<br />
* HTTP Get to the Collection IRI (defined by default as: /api/v1/space/[space UUID]/sword/collection/)<br />
* Transfers are listed as an Atom feed<br />
* Each Atom feed entry contains an "atom:link" element whose href attribute contains the URL needed to get details about the transfer<br />
* optional filters via get parameters (not yet implemented)<br />
<br />
=== Create a new transfer ===<br />
* used to start a new transfer in Archivematica<br />
* HTTP POST of an Atom Entry Document to the Collection IRI (defined by default as: /api/v1/space/[space UUID]/sword/collection/)<br />
<br />
'''Possible HTTP Response Codes'''<br />
* HTTP 200 OK - transfer already exists (not yet implemented)<br />
* HTTP 201 Created - transfer has been accepted<br />
* HTTP 412 Precondition Failed - required metadata missing or invalid<br />
<br />
Valid requests will receive a Sword Deposit Receipt in the body of the response.<br />
<br />
'''Required HTTP Headers'''<br />
The HTTP POST must include certain specific http headers. <br />
<br />
Required by http 1.1 specification:<br />
* Host: Must be set to archivematica host name.<br />
* Content-Length: Must be set to the length of the atom entry document.<br />
* Content-Type: Must be set to "application/atom+xml;type=entry".<br />
<br />
Required by Archivematica. <br />
* Authorization: Must include the api key and username assigned by Archivematica.<br />
<br />
Required by SWORD 2.0 protocol:<br />
* In-Progress: Must be set to "true"<br />
<br />
Optional in SWORD 2.0 protocol:<br />
* On-Behalf-Of: not implemented by Archivematica<br />
* Slug: not implemented by Archivematica<br />
<br />
'''Required in Body'''<br />
The Body of the request must be a valid METS Document. The required fields in an Atom Entry Document are:<br />
* LABEL: used as the transfer name<br />
* id: used as an accession id (not yet implemented)<br />
* author: used as the source of acquisition (not yet implemented)<br />
* summary: not implemented yet. Could be used in the future as a description for the Transfer<br />
* updated: should be set to the current timestamp. <br />
<br />
'''Example'''<br />
Example HTTP POST request:<br />
<pre><br />
POST /api/v1/space/96606387-cc70-4b09-b422-a7220606488d/sword/collection/ HTTP/1.1<br />
Host: localhost<br />
Authorization: Archivematica-API api_key="XXXXXXXXXXXXXXXXXXXX", username="timh"<br />
Content-Length: 213<br />
Content-Type: application/atom+xml;type=entry<br />
In-Progress: true<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<METS:mets EXT_VERSION="1.1" OBJID="islandora:72" LABEL="Cinderella"<br />
xmlns:METS="http://www.loc.gov/METS/"<br />
xmlns:xlink="http://www.w3.org/1999/xlink"<br />
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"<br />
xsi:schemaLocation="http://www.loc.gov/METS/ http://www.fedora.info/definitions/1/0/mets-fedora-ext1-1.xsd"><br />
<METS:fileSec><br />
<METS:fileGrp ID="DATASTREAMS"><br />
<METS:fileGrp ID="OBJ"><br />
<METS:file ID="OBJ.0"><br />
<METS:FLocat xlink:title="Cinderella_(1865).pdf" LOCTYPE="URL"<br />
xlink:href="http://localhost:8080/fedora/get/islandora:72/OBJ/2013-08-12T14:46:43.454Z" /><br />
</METS:file><br />
</METS:fileGrp><br />
</METS:fileGrp><br />
</METS:fileSec><br />
</METS:mets><br />
</pre><br />
<br />
Example Response:<br />
<pre><br />
201 Created<br />
Location: http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/<br />
<br />
<entry xmlns="http://www.w3.org/2005/Atom"<br />
xmlns:sword="http://purl.org/net/sword/"<br />
xmlns:dcterms="http://purl.org/dc/terms/"><br />
<br />
<title>Cinderella</title><br />
<id>91d4f258-0050-4914-9d0c-6a74815358d2</id><br />
<updated></updated><br />
<generator uri="https://www.archivematica.org" version="1.0"/><br />
<br />
<summary>A deposit was started.</summary><br />
<sword:treatment>A deposit directory was created and, optionally, asynchronous download of digital objects.</sword:treatment><br />
<br />
<link rel="alternate" href="http://www.swordserver.ac.uk/col1/mydeposit.html"/><br />
<link rel="edit-media" href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/media/"/><br />
<link rel="edit" href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/" /><br />
<link rel="http://purl.org/net/sword/terms/add" href="http://192.168.1.76:8000/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/" /><br />
<link rel="http://purl.org/net/sword/terms/statement" type="application/atom+xml;type=feed"<br />
href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/state/" /><br />
</entry><br />
</pre><br />
<br />
=== Add Files to a Transfer ===<br />
<br />
Posting file metadata (not yet implemented):<br />
* POST a METS file to the SE-IRI, listed below.<br />
* HTTP headers are required similar to Create Transfer call (above).<br />
* Body must include a valid Atom Entry document, that has METS embedded inside it.<br />
<br />
Posts file data:<br />
* It is possible to also POST the actual file to a deposit location's EM-IRI (/api/v1/location/[location UUID]/sword/media/)<br />
* The file should be posted as the request body and the filename specified using the Content-Disposition header (as per RFC 6266): for example "Content-Disposition: Attachment; filename=dog.jpg"<br />
* An MD5 checksum for an uploaded file can be provided via the Content-MD5 header (as per RFC 1544): for example "Content-MD5: Q2hlY2sgSW50ZWdyaXR5IQ=="<br />
* If only an Atom Entry Document is POST'ed, Archivematica will look for uri's in the file StructMap section of the METS file, and attempt to GET each file listed, to include in the Transfer. (not yet implemented)<br />
<br />
=== Finalize a Transfer ===<br />
* POST with no body to the SE-IRI<br />
* set In-Progress HTTP header to : false<br />
* This will tell Archivematica that no further content will be added or removed from the Transfer. <br />
* Archivematica will finish fetching any files that were added previously, and once they have all been downloaded, the Transfer will start through the Archivematica pipeline.<br />
<br />
'''Example'''<br />
<pre><br />
POST http://localhost/api/v1/location/55ce8053-113a-4954-8aa3-fc9771da0bda/sword/ HTTP/1.1<br />
Host: localhost<br />
Authorization: Archivematica-API api_key="XXXXXXXXXXXXXXXXXXXX", username="timh"<br />
Content-Length: 0<br />
Content-Type: application/atom+xml;type=entry<br />
In-Progress: false<br />
</pre><br />
<br />
The response will be HTTP 200/OK or 400/Error (400 if the Transfer was already finalized). If the transfer doesn't exist the response will be HTTP 404.<br />
<br />
=== Get Status of Transfer ===<br />
To check Status:<br />
<br />
GET the State-IRI<br />
in this example:<br />
<br />
GET http://localhost/api/v1/location/09224ddb-4c7d-404c-9218-2f2e1b5a599e/sword/state/ HTTP/1.1<br />
<br />
response will include:<br />
<pre><atom:feed xmlns:sword="http://purl.org/net/sword/terms/" <br />
xmlns:atom="http://www.w3.org/2005/Atom"><br />
<br />
<atom:category scheme="http://purl.org/net/sword/terms/state"<br />
term="failed"<br />
label="State"><br />
Deposit initiation: Failed<br />
</atom:category><br />
<br />
</atom:feed></pre><br />
the list of possible descriptions is not finalized.<br />
<br />
The state term value will either be "processing" (asynchronous deposit still working), "complete" (ready to be finalized), or "failed" (asynchronous deposit encountered an error).<br />
<br />
== Additional Details == <br />
<br />
=== Transfer Details ===<br />
* redirect to Edit-IRI<br />
* used to get basic info about a Transfer with HTTP GET<br />
* can update basic info using HTTP PUT (not yet implemented)<br />
* can allow deletion with HTTP DELETE<br />
* follows the form: /api/v1/location/[deposit location UUID]/sword/<br />
* example: http://192.168.1.231:8000/api/v1/location/09224ddb-4c7d-404c-9218-2f2e1b5a599e/sword/<br />
<br />
=== EM-IRI ===<br />
* Edit-Media IRI <br />
* used to add new objects to an existing transfer<br />
* follows the form: [archivematica hostname]/api/v2/transfer/[uuid of transfer]/media<br />
* example: /api/v1/location/[deposit location UUID]/sword/media/<br />
<br />
An HTTP POST to the em-iri for a transfer should include a file as the body<br />
<br />
An HTTP GET should return a list of files in the transfer<br />
<br />
An HTTP DELETE to the em-iri will remove all digital objects from the Transfer. This is a valid operation only while the Transfer is being assembled. Once the Transfer has been finalized, attempting to DELETE will return an error.<br />
<br />
=== Edit-IRI ===<br />
The client can replace the metadata of a resource by performing an HTTP PUT of a new Atom Entry on the Edit-IRI. (not yet implemented)<br />
<br />
This would be used to update metadata about a transfer, such as the transfer name.<br />
<br />
* example: http://localhost/api/v2/transfer/1225c695-cfb8-4ebb-aaaa-80da344efa6a/edit<br />
<br />
=== SE-IRI ===<br />
* example: http://localhost/api/v2/transfer/add/1225c695-cfb8-4ebb-aaaa-80da344efa6a (not yet implemented)<br />
<br />
=== State-IRI ===<br />
* used to retrieve status of transfer<br />
* implemented as Atom document<br />
* example: /api/v1/location/[deposit location UUID]/sword/state/<br />
* should be able to subscribe like RSS feed<br />
<br />
=== Service document ===<br />
<br />
== Dashboard configuration ==<br />
<br />
When a transfer deposit is finalized, an Archivematica instance can be notified in the background, via a REST API, that the transfer should be approved for processing. In this way the SWORD API can be used to start transfers.<br />
<br />
Each SWORD space in a storage service is associated with an Archivematica instance. Both the Archivematica instance and the storage service, however, require configuration.<br />
<br />
On the Archivematica dashboard side, the IP or hostname of the storage service must be added to the REST API whitelist (click "Administration" in the Archivematica navigation bar then "REST API" in the administration sidebar to get to the whitelist page).<br />
<br />
Once you're whitelisted the storage service in the Archivematica dashboard, click "General" in the administration sidebar then note the dashboard UUID. In the storage service administration interface, click "Pipelines" in the navigation bar. Find the UUID matching the dashboard then click "Edit". In the "Remote name" field enter the IP of the Archivematica dashboard. In the "Api username" field enter an Archivematica dashboard username (click "Administration" in the Archivematica navigation bar then "Users" in the administration sidebar to access the user list). In the "Api key" field enter a valid API key (a user's API key can be found by clicking the "Edit" button corresponding to a specific user on the user list page).<br />
<br />
== Example session ==<br />
<br />
Below is an example session using curl to manipulate the API. In the example a deposit is created, a file is added to it, and it is finalized.<br />
<br />
NOTE: The SWORD API is in the process of being moved to the storage service. These URLs may not work.<br />
<br />
<pre># create new deposit<br />
curl -v -H "In-Progress: true" --data-binary @mets.xml --request POST http://localhost:8000/api/v1/location/52bbe770-3f96-4493-8d93-ded54c958c51/sword/collection/<br />
# response XML includes endpoints for adding addition files, etc.<br />
<br />
# add another file to the transfer<br />
curl -v -H "Content-Disposition: attachment; filename=joke.jpg" --request POST \<br />
--data-binary "@joke.jpg" \<br />
http://localhost:8000/api/v1/deposit/8e1cba3c-f133-48b2-afef-e42505a7bdc8/sword/media/<br />
<br />
# finalize transfer and approve processing<br />
curl -v -H "In-Progress: false" --request POST http://localhost:8000/api/v1/deposit/8e1cba3c-f133-48b2-afef-e42505a7bdc8/sword/</pre><br />
<br />
You might, at some point, want to list the transfers that have been started. The following curl command will do so.<br />
<br />
<pre>curl -v http://localhost:8000/api/v1/location/52bbe770-3f96-4493-8d93-ded54c958c51/sword/collection/</pre><br />
<br />
If you're working on a transfer and want to list what files are included in it, the following curl command will list them.<br />
<br />
<pre># list files in transfer<br />
curl -v http://192.168.1.231:8000/api/v1/deposit/8e1cba3c-f133-48b2-bdc8/sword/media/</pre><br />
<br />
If you've started a deposit, but want to discard it, you can delete the deposit. The following curl command shows an example.<br />
<br />
<pre>curl -v -XDELETE http://localhost:8000/api/v1/deposit/8e1cba3c-f133-48b2-afef-e42505a7bdc8/sword/</pre><br />
<br />
== Synchronous Deposit Examples ==<br />
<br />
If you wanted to deposit a transfer then immediately finalize it you could use something like the following curl command.<br />
<br />
<pre>curl -v -H "In-Progress: false" --data-binary @mets.xml --request POST http://localhost:8000/api/v1/location/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/</pre></div>Mcantelonhttps://wiki.archivematica.org/index.php?title=Sword_API&diff=9169Sword API2013-11-29T23:08:02Z<p>Mcantelon: </p>
<hr />
<div><br />
== Overview ==<br />
<br />
One of the 1.1 release features is a sponsored project to integrate Archivematica with Islandora. This integration will be accomplished by creating a [http://swordapp.org Sword] 2.0 API for the Archivematica [https://www.archivematica.org/wiki/Administrator_manual_1.0#Storage_service storage service]. Islandora development work will add functionality to Islandora to use this API to deposit digital objects into Archviematica.<br />
<br />
As described [[Overview|elsewhere]] on this wiki, ''"the primary function of Archivematica is to process digital transfers (accessioned digital objects), turn them into SIPs, apply format policies and create high-quality, repository-independent Archival Information Packages (AIP)"''.<br />
<br />
The Archivematica Sword API allows 3rd party applications to automate the process of creating Transfers. <br />
#Create Transfer - set the name and other metadata about a Transfer<br />
#Populate Transfer - add/edit/update digital objects in a Transfer, and associated metadata<br />
#Finalize Transfer - indicates that the Transfer is ready to start processing.<br />
<br />
After content has been deposited, if users have access to the deposit directory they can also manually manipulate the deposit directory aside from any manipulation using the API.<br />
<br />
Once a Transfer has been created, populated and finalized, Archivematica will begin processing that Transfer.<br />
<br />
== Endpoints ==<br />
<br />
=== Service document ===<br />
<br />
The SWORD service document provides information about the SWORD provider's capacities and lists SWORD collections. Archivematica currently includes one SWORD collection to which SWORD deposits can be made: transfers.<br />
<br />
The SWORD service document endpoint is located at /api/v1/sword.<br />
<br />
=== List existing transfers ===<br />
* HTTP Get to the Collection IRI (defined by default as: /api/v1/space/[space UUID]/sword/collection/)<br />
* Transfers are listed as an Atom feed<br />
* Each Atom feed entry contains an "atom:link" element whose href attribute contains the URL needed to get details about the transfer<br />
* optional filters via get parameters (not yet implemented)<br />
<br />
=== Create a new transfer ===<br />
* used to start a new transfer in Archivematica<br />
* HTTP POST of an Atom Entry Document to the Collection IRI (defined by default as: /api/v1/space/[space UUID]/sword/collection/)<br />
<br />
'''Possible HTTP Response Codes'''<br />
* HTTP 200 OK - transfer already exists (not yet implemented)<br />
* HTTP 201 Created - transfer has been accepted<br />
* HTTP 412 Precondition Failed - required metadata missing or invalid<br />
<br />
Valid requests will receive a Sword Deposit Receipt in the body of the response.<br />
<br />
'''Required HTTP Headers'''<br />
The HTTP POST must include certain specific http headers. <br />
<br />
Required by http 1.1 specification:<br />
* Host: Must be set to archivematica host name.<br />
* Content-Length: Must be set to the length of the atom entry document.<br />
* Content-Type: Must be set to "application/atom+xml;type=entry".<br />
<br />
Required by Archivematica. <br />
* Authorization: Must include the api key and username assigned by Archivematica.<br />
<br />
Required by SWORD 2.0 protocol:<br />
* In-Progress: Must be set to "true"<br />
<br />
Optional in SWORD 2.0 protocol:<br />
* On-Behalf-Of: not implemented by Archivematica<br />
* Slug: not implemented by Archivematica<br />
<br />
'''Required in Body'''<br />
The Body of the request must be a valid METS Document. The required fields in an Atom Entry Document are:<br />
* LABEL: used as the transfer name<br />
* id: used as an accession id (not yet implemented)<br />
* author: used as the source of acquisition (not yet implemented)<br />
* summary: not implemented yet. Could be used in the future as a description for the Transfer<br />
* updated: should be set to the current timestamp. <br />
<br />
'''Example'''<br />
Example HTTP POST request:<br />
<pre><br />
POST /api/v1/space/96606387-cc70-4b09-b422-a7220606488d/sword/collection/ HTTP/1.1<br />
Host: localhost<br />
Authorization: Archivematica-API api_key="XXXXXXXXXXXXXXXXXXXX", username="timh"<br />
Content-Length: 213<br />
Content-Type: application/atom+xml;type=entry<br />
In-Progress: true<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<METS:mets EXT_VERSION="1.1" OBJID="islandora:72" LABEL="Cinderella"<br />
xmlns:METS="http://www.loc.gov/METS/"<br />
xmlns:xlink="http://www.w3.org/1999/xlink"<br />
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"<br />
xsi:schemaLocation="http://www.loc.gov/METS/ http://www.fedora.info/definitions/1/0/mets-fedora-ext1-1.xsd"><br />
<METS:fileSec><br />
<METS:fileGrp ID="DATASTREAMS"><br />
<METS:fileGrp ID="OBJ"><br />
<METS:file ID="OBJ.0"><br />
<METS:FLocat xlink:title="Cinderella_(1865).pdf" LOCTYPE="URL"<br />
xlink:href="http://localhost:8080/fedora/get/islandora:72/OBJ/2013-08-12T14:46:43.454Z" /><br />
</METS:file><br />
</METS:fileGrp><br />
</METS:fileGrp><br />
</METS:fileSec><br />
</METS:mets><br />
</pre><br />
<br />
Example Response:<br />
<pre><br />
201 Created<br />
Location: http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/<br />
<br />
<entry xmlns="http://www.w3.org/2005/Atom"<br />
xmlns:sword="http://purl.org/net/sword/"<br />
xmlns:dcterms="http://purl.org/dc/terms/"><br />
<br />
<title>Cinderella</title><br />
<id>91d4f258-0050-4914-9d0c-6a74815358d2</id><br />
<updated></updated><br />
<generator uri="https://www.archivematica.org" version="1.0"/><br />
<br />
<summary>A deposit was started.</summary><br />
<sword:treatment>A deposit directory was created and, optionally, asynchronous download of digital objects.</sword:treatment><br />
<br />
<link rel="alternate" href="http://www.swordserver.ac.uk/col1/mydeposit.html"/><br />
<link rel="edit-media" href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/media/"/><br />
<link rel="edit" href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/" /><br />
<link rel="http://purl.org/net/sword/terms/add" href="http://192.168.1.76:8000/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/" /><br />
<link rel="http://purl.org/net/sword/terms/statement" type="application/atom+xml;type=feed"<br />
href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/state/" /><br />
</entry><br />
</pre><br />
<br />
=== Add Files to a Transfer ===<br />
<br />
Posting file metadata (not yet implemented):<br />
* POST a METS file to the SE-IRI, listed below.<br />
* HTTP headers are required similar to Create Transfer call (above).<br />
* Body must include a valid Atom Entry document, that has METS embedded inside it.<br />
<br />
Posts file data:<br />
* It is possible to also POST the actual file to a deposit location's EM-IRI (/api/v1/location/[location UUID]/sword/media/)<br />
* The file should be posted as the request body and the filename specified using the Content-Disposition header (as per RFC 6266): for example "Content-Disposition: Attachment; filename=dog.jpg"<br />
* An MD5 checksum for an uploaded file can be provided via the Content-MD5 header (as per RFC 1544): for example "Content-MD5: Q2hlY2sgSW50ZWdyaXR5IQ=="<br />
* If only an Atom Entry Document is POST'ed, Archivematica will look for uri's in the file StructMap section of the METS file, and attempt to GET each file listed, to include in the Transfer. (not yet implemented)<br />
<br />
=== Finalize a Transfer ===<br />
* POST with no body to the SE-IRI<br />
* set In-Progress HTTP header to : false<br />
* This will tell Archivematica that no further content will be added or removed from the Transfer. <br />
* Archivematica will finish fetching any files that were added previously, and once they have all been downloaded, the Transfer will start through the Archivematica pipeline.<br />
<br />
'''Example'''<br />
<pre><br />
POST http://localhost/api/v1/location/55ce8053-113a-4954-8aa3-fc9771da0bda/sword/ HTTP/1.1<br />
Host: localhost<br />
Authorization: Archivematica-API api_key="XXXXXXXXXXXXXXXXXXXX", username="timh"<br />
Content-Length: 0<br />
Content-Type: application/atom+xml;type=entry<br />
In-Progress: false<br />
</pre><br />
<br />
The response will be HTTP 200/OK or 400/Error (400 if the Transfer was already finalized). If the transfer doesn't exist the response will be HTTP 404.<br />
<br />
=== Get Status of Transfer ===<br />
To check Status:<br />
<br />
GET the State-IRI<br />
in this example:<br />
<br />
GET http://localhost/api/v1/location/09224ddb-4c7d-404c-9218-2f2e1b5a599e/sword/state/ HTTP/1.1<br />
<br />
response will include:<br />
<pre><atom:feed xmlns:sword="http://purl.org/net/sword/terms/" <br />
xmlns:atom="http://www.w3.org/2005/Atom"><br />
<br />
<atom:category scheme="http://purl.org/net/sword/terms/state"<br />
term="failed"<br />
label="State"><br />
Deposit initiation: Failed<br />
</atom:category><br />
<br />
</atom:feed></pre><br />
the list of possible descriptions is not finalized.<br />
<br />
The state term value will either be "processing" (asynchronous deposit still working), "complete" (ready to be finalized), or "failed" (asynchronous deposit encountered an error).<br />
<br />
== Additional Details == <br />
<br />
=== Transfer Details ===<br />
* redirect to Edit-IRI<br />
* used to get basic info about a Transfer with HTTP GET<br />
* can update basic info using HTTP PUT (not yet implemented)<br />
* can allow deletion with HTTP DELETE<br />
* follows the form: /api/v1/location/[deposit location UUID]/sword/<br />
* example: http://192.168.1.231:8000/api/v1/location/09224ddb-4c7d-404c-9218-2f2e1b5a599e/sword/<br />
<br />
=== EM-IRI ===<br />
* Edit-Media IRI <br />
* used to add new objects to an existing transfer<br />
* follows the form: [archivematica hostname]/api/v2/transfer/[uuid of transfer]/media<br />
* example: /api/v1/location/[deposit location UUID]/sword/media/<br />
<br />
An HTTP POST to the em-iri for a transfer should include a file as the body<br />
<br />
An HTTP GET should return a list of files in the transfer<br />
<br />
An HTTP DELETE to the em-iri will remove all digital objects from the Transfer. This is a valid operation only while the Transfer is being assembled. Once the Transfer has been finalized, attempting to DELETE will return an error.<br />
<br />
=== Edit-IRI ===<br />
The client can replace the metadata of a resource by performing an HTTP PUT of a new Atom Entry on the Edit-IRI. (not yet implemented)<br />
<br />
This would be used to update metadata about a transfer, such as the transfer name.<br />
<br />
* example: http://localhost/api/v2/transfer/1225c695-cfb8-4ebb-aaaa-80da344efa6a/edit<br />
<br />
=== SE-IRI ===<br />
* example: http://localhost/api/v2/transfer/add/1225c695-cfb8-4ebb-aaaa-80da344efa6a (not yet implemented)<br />
<br />
=== State-IRI ===<br />
* used to retrieve status of transfer<br />
* implemented as Atom document<br />
* example: /api/v1/location/[deposit location UUID]/sword/state/<br />
* should be able to subscribe like RSS feed<br />
<br />
== Dashboard configuration ==<br />
<br />
When a transfer deposit is finalized, an Archivematica instance can be notified in the background, via a REST API, that the transfer should be approved for processing. In this way the SWORD API can be used to start transfers.<br />
<br />
Each SWORD space in a storage service is associated with an Archivematica instance. Both the Archivematica instance and the storage service, however, require configuration.<br />
<br />
On the Archivematica dashboard side, the IP or hostname of the storage service must be added to the REST API whitelist (click "Administration" in the Archivematica navigation bar then "REST API" in the administration sidebar to get to the whitelist page).<br />
<br />
Once you're whitelisted the storage service in the Archivematica dashboard, click "General" in the administration sidebar then note the dashboard UUID. In the storage service administration interface, click "Pipelines" in the navigation bar. Find the UUID matching the dashboard then click "Edit". In the "Remote name" field enter the IP of the Archivematica dashboard. In the "Api username" field enter an Archivematica dashboard username (click "Administration" in the Archivematica navigation bar then "Users" in the administration sidebar to access the user list). In the "Api key" field enter a valid API key (a user's API key can be found by clicking the "Edit" button corresponding to a specific user on the user list page).<br />
<br />
=== Service document ===<br />
<br />
<br />
== Example session ==<br />
<br />
Below is an example session using curl to manipulate the API. In the example a deposit is created, a file is added to it, and it is finalized.<br />
<br />
NOTE: The SWORD API is in the process of being moved to the storage service. These URLs may not work.<br />
<br />
<pre># create new deposit<br />
curl -v -H "In-Progress: true" --data-binary @mets.xml --request POST http://localhost:8000/api/v1/location/52bbe770-3f96-4493-8d93-ded54c958c51/sword/collection/<br />
# response XML includes endpoints for adding addition files, etc.<br />
<br />
# add another file to the transfer<br />
curl -v -H "Content-Disposition: attachment; filename=joke.jpg" --request POST \<br />
--data-binary "@joke.jpg" \<br />
http://localhost:8000/api/v1/deposit/8e1cba3c-f133-48b2-afef-e42505a7bdc8/sword/media/<br />
<br />
# finalize transfer and approve processing<br />
curl -v -H "In-Progress: false" --request POST http://localhost:8000/api/v1/deposit/8e1cba3c-f133-48b2-afef-e42505a7bdc8/sword/</pre><br />
<br />
You might, at some point, want to list the transfers that have been started. The following curl command will do so.<br />
<br />
<pre>curl -v http://localhost:8000/api/v1/location/52bbe770-3f96-4493-8d93-ded54c958c51/sword/collection/</pre><br />
<br />
If you're working on a transfer and want to list what files are included in it, the following curl command will list them.<br />
<br />
<pre># list files in transfer<br />
curl -v http://192.168.1.231:8000/api/v1/deposit/8e1cba3c-f133-48b2-bdc8/sword/media/</pre><br />
<br />
If you've started a deposit, but want to discard it, you can delete the deposit. The following curl command shows an example.<br />
<br />
<pre>curl -v -XDELETE http://localhost:8000/api/v1/deposit/8e1cba3c-f133-48b2-afef-e42505a7bdc8/sword/</pre><br />
<br />
== Synchronous Deposit Examples ==<br />
<br />
If you wanted to deposit a transfer then immediately finalize it you could use something like the following curl command.<br />
<br />
<pre>curl -v -H "In-Progress: false" --data-binary @mets.xml --request POST http://localhost:8000/api/v1/location/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/</pre></div>Mcantelonhttps://wiki.archivematica.org/index.php?title=Sword_API&diff=9165Sword API2013-11-29T01:33:03Z<p>Mcantelon: /* Synchronous Deposit Examples */</p>
<hr />
<div><br />
== Overview ==<br />
<br />
One of the 1.1 release features is a sponsored project to integrate Archivematica with Islandora. This integration will be accomplished by creating a [http://swordapp.org Sword] 2.0 API for the Archivematica [https://www.archivematica.org/wiki/Administrator_manual_1.0#Storage_service storage service]. Islandora development work will add functionality to Islandora to use this API to deposit digital objects into Archviematica.<br />
<br />
As described [[Overview|elsewhere]] on this wiki, ''"the primary function of Archivematica is to process digital transfers (accessioned digital objects), turn them into SIPs, apply format policies and create high-quality, repository-independent Archival Information Packages (AIP)"''.<br />
<br />
The Archivematica Sword API allows 3rd party applications to automate the process of creating Transfers. <br />
#Create Transfer - set the name and other metadata about a Transfer<br />
#Populate Transfer - add/edit/update digital objects in a Transfer, and associated metadata<br />
#Finalize Transfer - indicates that the Transfer is ready to start processing.<br />
<br />
After content has been deposited, if users have access to the deposit directory they can also manually manipulate the deposit directory aside from any manipulation using the API.<br />
<br />
Once a Transfer has been created, populated and finalized, Archivematica will begin processing that Transfer.<br />
<br />
== Endpoints ==<br />
<br />
=== Service document ===<br />
<br />
The SWORD service document provides information about the SWORD provider's capacities and lists SWORD collections. Archivematica currently includes one SWORD collection to which SWORD deposits can be made: transfers.<br />
<br />
The SWORD service document endpoint is located at /api/v1/sword.<br />
<br />
=== List existing transfers ===<br />
* HTTP Get to the Collection IRI (defined by default as: /api/v1/space/[space UUID]/sword/collection/)<br />
* Transfers are listed as an Atom feed<br />
* Each Atom feed entry contains an "atom:link" element whose href attribute contains the URL needed to get details about the transfer<br />
* optional filters via get parameters (not yet implemented)<br />
<br />
=== Create a new transfer ===<br />
* used to start a new transfer in Archivematica<br />
* HTTP POST of an Atom Entry Document to the Collection IRI (defined by default as: /api/v1/space/[space UUID]/sword/collection/)<br />
<br />
'''Possible HTTP Response Codes'''<br />
* HTTP 200 OK - transfer already exists (not yet implemented)<br />
* HTTP 201 Created - transfer has been accepted<br />
* HTTP 412 Precondition Failed - required metadata missing or invalid<br />
<br />
Valid requests will receive a Sword Deposit Receipt in the body of the response.<br />
<br />
'''Required HTTP Headers'''<br />
The HTTP POST must include certain specific http headers. <br />
<br />
Required by http 1.1 specification:<br />
* Host: Must be set to archivematica host name.<br />
* Content-Length: Must be set to the length of the atom entry document.<br />
* Content-Type: Must be set to "application/atom+xml;type=entry".<br />
<br />
Required by Archivematica. <br />
* Authorization: Must include the api key and username assigned by Archivematica.<br />
<br />
Required by SWORD 2.0 protocol:<br />
* In-Progress: Must be set to "true"<br />
<br />
Optional in SWORD 2.0 protocol:<br />
* On-Behalf-Of: not implemented by Archivematica<br />
* Slug: not implemented by Archivematica<br />
<br />
'''Required in Body'''<br />
The Body of the request must be a valid METS Document. The required fields in an Atom Entry Document are:<br />
* LABEL: used as the transfer name<br />
* id: used as an accession id (not yet implemented)<br />
* author: used as the source of acquisition (not yet implemented)<br />
* summary: not implemented yet. Could be used in the future as a description for the Transfer<br />
* updated: should be set to the current timestamp. <br />
<br />
'''Example'''<br />
Example HTTP POST request:<br />
<pre><br />
POST /api/v1/space/96606387-cc70-4b09-b422-a7220606488d/sword/collection/ HTTP/1.1<br />
Host: localhost<br />
Authorization: Archivematica-API api_key="XXXXXXXXXXXXXXXXXXXX", username="timh"<br />
Content-Length: 213<br />
Content-Type: application/atom+xml;type=entry<br />
In-Progress: true<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<METS:mets EXT_VERSION="1.1" OBJID="islandora:72" LABEL="Cinderella"<br />
xmlns:METS="http://www.loc.gov/METS/"<br />
xmlns:xlink="http://www.w3.org/1999/xlink"<br />
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"<br />
xsi:schemaLocation="http://www.loc.gov/METS/ http://www.fedora.info/definitions/1/0/mets-fedora-ext1-1.xsd"><br />
<METS:fileSec><br />
<METS:fileGrp ID="DATASTREAMS"><br />
<METS:fileGrp ID="OBJ"><br />
<METS:file ID="OBJ.0"><br />
<METS:FLocat xlink:title="Cinderella_(1865).pdf" LOCTYPE="URL"<br />
xlink:href="http://localhost:8080/fedora/get/islandora:72/OBJ/2013-08-12T14:46:43.454Z" /><br />
</METS:file><br />
</METS:fileGrp><br />
</METS:fileGrp><br />
</METS:fileSec><br />
</METS:mets><br />
</pre><br />
<br />
Example Response:<br />
<pre><br />
201 Created<br />
Location: http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/<br />
<br />
<entry xmlns="http://www.w3.org/2005/Atom"<br />
xmlns:sword="http://purl.org/net/sword/"<br />
xmlns:dcterms="http://purl.org/dc/terms/"><br />
<br />
<title>Cinderella</title><br />
<id>91d4f258-0050-4914-9d0c-6a74815358d2</id><br />
<updated></updated><br />
<generator uri="https://www.archivematica.org" version="1.0"/><br />
<br />
<summary>A deposit was started.</summary><br />
<sword:treatment>A deposit directory was created and, optionally, asynchronous download of digital objects.</sword:treatment><br />
<br />
<link rel="alternate" href="http://www.swordserver.ac.uk/col1/mydeposit.html"/><br />
<link rel="edit-media" href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/media/"/><br />
<link rel="edit" href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/" /><br />
<link rel="http://purl.org/net/sword/terms/add" href="http://192.168.1.76:8000/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/" /><br />
<link rel="http://purl.org/net/sword/terms/statement" type="application/atom+xml;type=feed"<br />
href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/state/" /><br />
</entry><br />
</pre><br />
<br />
=== Add Files to a Transfer ===<br />
<br />
Posting file metadata (not yet implemented):<br />
* POST a METS file to the SE-IRI, listed below.<br />
* HTTP headers are required similar to Create Transfer call (above).<br />
* Body must include a valid Atom Entry document, that has METS embedded inside it.<br />
<br />
Posts file data:<br />
* It is possible to also POST the actual file to a deposit location's EM-IRI (/api/v1/location/[location UUID]/sword/media/)<br />
* The file should be posted as the request body and the filename specified using the Content-Disposition header (as per RFC 6266): for example "Content-Disposition: Attachment; filename=dog.jpg"<br />
* An MD5 checksum for an uploaded file can be provided via the Content-MD5 header (as per RFC 1544): for example "Content-MD5: Q2hlY2sgSW50ZWdyaXR5IQ=="<br />
* If only an Atom Entry Document is POST'ed, Archivematica will look for uri's in the file StructMap section of the METS file, and attempt to GET each file listed, to include in the Transfer. (not yet implemented)<br />
<br />
=== Finalize a Transfer ===<br />
* POST with no body to the SE-IRI<br />
* set In-Progress HTTP header to : false<br />
* This will tell Archivematica that no further content will be added or removed from the Transfer. <br />
* Archivematica will finish fetching any files that were added previously, and once they have all been downloaded, the Transfer will start through the Archivematica pipeline.<br />
<br />
'''Example'''<br />
<pre><br />
POST http://localhost/api/v1/location/55ce8053-113a-4954-8aa3-fc9771da0bda/sword/ HTTP/1.1<br />
Host: localhost<br />
Authorization: Archivematica-API api_key="XXXXXXXXXXXXXXXXXXXX", username="timh"<br />
Content-Length: 0<br />
Content-Type: application/atom+xml;type=entry<br />
In-Progress: false<br />
</pre><br />
<br />
The response will be HTTP 200/OK or 400/Error (400 if the Transfer was already finalized). If the transfer doesn't exist the response will be HTTP 404.<br />
<br />
=== Get Status of Transfer ===<br />
To check Status:<br />
<br />
GET the State-IRI<br />
in this example:<br />
<br />
GET http://localhost/api/v1/location/09224ddb-4c7d-404c-9218-2f2e1b5a599e/sword/state/ HTTP/1.1<br />
<br />
response will include:<br />
<pre><atom:feed xmlns:sword="http://purl.org/net/sword/terms/" <br />
xmlns:atom="http://www.w3.org/2005/Atom"><br />
<br />
<atom:category scheme="http://purl.org/net/sword/terms/state"<br />
term="failed"<br />
label="State"><br />
Deposit initiation: Failed<br />
</atom:category><br />
<br />
</atom:feed></pre><br />
the list of possible descriptions is not finalized.<br />
<br />
The state term value will either be "processing" (asynchronous deposit still working), "complete" (ready to be finalized), or "failed" (asynchronous deposit encountered an error).<br />
<br />
== Additional Details == <br />
<br />
=== Transfer Details ===<br />
* redirect to Edit-IRI<br />
* used to get basic info about a Transfer with HTTP GET<br />
* can update basic info using HTTP PUT (not yet implemented)<br />
* can allow deletion with HTTP DELETE<br />
* follows the form: /api/v1/location/[deposit location UUID]/sword/<br />
* example: http://192.168.1.231:8000/api/v1/location/09224ddb-4c7d-404c-9218-2f2e1b5a599e/sword/<br />
<br />
=== EM-IRI ===<br />
* Edit-Media IRI <br />
* used to add new objects to an existing transfer<br />
* follows the form: [archivematica hostname]/api/v2/transfer/[uuid of transfer]/media<br />
* example: /api/v1/location/[deposit location UUID]/sword/media/<br />
<br />
An HTTP POST to the em-iri for a transfer should include a file as the body<br />
<br />
An HTTP GET should return a list of files in the transfer<br />
<br />
An HTTP DELETE to the em-iri will remove all digital objects from the Transfer. This is a valid operation only while the Transfer is being assembled. Once the Transfer has been finalized, attempting to DELETE will return an error.<br />
<br />
=== Edit-IRI ===<br />
The client can replace the metadata of a resource by performing an HTTP PUT of a new Atom Entry on the Edit-IRI. (not yet implemented)<br />
<br />
This would be used to update metadata about a transfer, such as the transfer name.<br />
<br />
* example: http://localhost/api/v2/transfer/1225c695-cfb8-4ebb-aaaa-80da344efa6a/edit<br />
<br />
=== SE-IRI ===<br />
* example: http://localhost/api/v2/transfer/add/1225c695-cfb8-4ebb-aaaa-80da344efa6a (not yet implemented)<br />
<br />
=== State-IRI ===<br />
* used to retrieve status of transfer<br />
* implemented as Atom document<br />
* example: /api/v1/location/[deposit location UUID]/sword/state/<br />
* should be able to subscribe like RSS feed<br />
<br />
== Example session ==<br />
<br />
Below is an example session using curl to manipulate the API. In the example a deposit is created, a file is added to it, and it is finalized.<br />
<br />
NOTE: The SWORD API is in the process of being moved to the storage service. These URLs may not work.<br />
<br />
<pre># create new deposit<br />
curl -v -H "In-Progress: true" --data-binary @mets.xml --request POST http://localhost:8000/api/v1/location/52bbe770-3f96-4493-8d93-ded54c958c51/sword/collection/<br />
# response XML includes endpoints for adding addition files, etc.<br />
<br />
# add another file to the transfer<br />
curl -v -H "Content-Disposition: attachment; filename=joke.jpg" --request POST \<br />
--data-binary "@joke.jpg" \<br />
http://localhost:8000/api/v1/deposit/8e1cba3c-f133-48b2-afef-e42505a7bdc8/sword/media/<br />
<br />
# finalize transfer and approve processing<br />
curl -v -H "In-Progress: false" --request POST http://localhost:8000/api/v1/deposit/8e1cba3c-f133-48b2-afef-e42505a7bdc8/sword/</pre><br />
<br />
You might, at some point, want to list the transfers that have been started. The following curl command will do so.<br />
<br />
<pre>curl -v http://localhost:8000/api/v1/location/52bbe770-3f96-4493-8d93-ded54c958c51/sword/collection/</pre><br />
<br />
If you're working on a transfer and want to list what files are included in it, the following curl command will list them.<br />
<br />
<pre># list files in transfer<br />
curl -v http://192.168.1.231:8000/api/v1/deposit/8e1cba3c-f133-48b2-bdc8/sword/media/</pre><br />
<br />
If you've started a deposit, but want to discard it, you can delete the deposit. The following curl command shows an example.<br />
<br />
<pre>curl -v -XDELETE http://localhost:8000/api/v1/deposit/8e1cba3c-f133-48b2-afef-e42505a7bdc8/sword/</pre><br />
<br />
== Synchronous Deposit Examples ==<br />
<br />
If you wanted to deposit a transfer then immediately finalize it you could use something like the following curl command.<br />
<br />
<pre>curl -v -H "In-Progress: false" --data-binary @mets.xml --request POST http://localhost:8000/api/v1/location/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/</pre></div>Mcantelonhttps://wiki.archivematica.org/index.php?title=Sword_API&diff=9164Sword API2013-11-29T01:32:32Z<p>Mcantelon: /* Finalize a Transfer */</p>
<hr />
<div><br />
== Overview ==<br />
<br />
One of the 1.1 release features is a sponsored project to integrate Archivematica with Islandora. This integration will be accomplished by creating a [http://swordapp.org Sword] 2.0 API for the Archivematica [https://www.archivematica.org/wiki/Administrator_manual_1.0#Storage_service storage service]. Islandora development work will add functionality to Islandora to use this API to deposit digital objects into Archviematica.<br />
<br />
As described [[Overview|elsewhere]] on this wiki, ''"the primary function of Archivematica is to process digital transfers (accessioned digital objects), turn them into SIPs, apply format policies and create high-quality, repository-independent Archival Information Packages (AIP)"''.<br />
<br />
The Archivematica Sword API allows 3rd party applications to automate the process of creating Transfers. <br />
#Create Transfer - set the name and other metadata about a Transfer<br />
#Populate Transfer - add/edit/update digital objects in a Transfer, and associated metadata<br />
#Finalize Transfer - indicates that the Transfer is ready to start processing.<br />
<br />
After content has been deposited, if users have access to the deposit directory they can also manually manipulate the deposit directory aside from any manipulation using the API.<br />
<br />
Once a Transfer has been created, populated and finalized, Archivematica will begin processing that Transfer.<br />
<br />
== Endpoints ==<br />
<br />
=== Service document ===<br />
<br />
The SWORD service document provides information about the SWORD provider's capacities and lists SWORD collections. Archivematica currently includes one SWORD collection to which SWORD deposits can be made: transfers.<br />
<br />
The SWORD service document endpoint is located at /api/v1/sword.<br />
<br />
=== List existing transfers ===<br />
* HTTP Get to the Collection IRI (defined by default as: /api/v1/space/[space UUID]/sword/collection/)<br />
* Transfers are listed as an Atom feed<br />
* Each Atom feed entry contains an "atom:link" element whose href attribute contains the URL needed to get details about the transfer<br />
* optional filters via get parameters (not yet implemented)<br />
<br />
=== Create a new transfer ===<br />
* used to start a new transfer in Archivematica<br />
* HTTP POST of an Atom Entry Document to the Collection IRI (defined by default as: /api/v1/space/[space UUID]/sword/collection/)<br />
<br />
'''Possible HTTP Response Codes'''<br />
* HTTP 200 OK - transfer already exists (not yet implemented)<br />
* HTTP 201 Created - transfer has been accepted<br />
* HTTP 412 Precondition Failed - required metadata missing or invalid<br />
<br />
Valid requests will receive a Sword Deposit Receipt in the body of the response.<br />
<br />
'''Required HTTP Headers'''<br />
The HTTP POST must include certain specific http headers. <br />
<br />
Required by http 1.1 specification:<br />
* Host: Must be set to archivematica host name.<br />
* Content-Length: Must be set to the length of the atom entry document.<br />
* Content-Type: Must be set to "application/atom+xml;type=entry".<br />
<br />
Required by Archivematica. <br />
* Authorization: Must include the api key and username assigned by Archivematica.<br />
<br />
Required by SWORD 2.0 protocol:<br />
* In-Progress: Must be set to "true"<br />
<br />
Optional in SWORD 2.0 protocol:<br />
* On-Behalf-Of: not implemented by Archivematica<br />
* Slug: not implemented by Archivematica<br />
<br />
'''Required in Body'''<br />
The Body of the request must be a valid METS Document. The required fields in an Atom Entry Document are:<br />
* LABEL: used as the transfer name<br />
* id: used as an accession id (not yet implemented)<br />
* author: used as the source of acquisition (not yet implemented)<br />
* summary: not implemented yet. Could be used in the future as a description for the Transfer<br />
* updated: should be set to the current timestamp. <br />
<br />
'''Example'''<br />
Example HTTP POST request:<br />
<pre><br />
POST /api/v1/space/96606387-cc70-4b09-b422-a7220606488d/sword/collection/ HTTP/1.1<br />
Host: localhost<br />
Authorization: Archivematica-API api_key="XXXXXXXXXXXXXXXXXXXX", username="timh"<br />
Content-Length: 213<br />
Content-Type: application/atom+xml;type=entry<br />
In-Progress: true<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<METS:mets EXT_VERSION="1.1" OBJID="islandora:72" LABEL="Cinderella"<br />
xmlns:METS="http://www.loc.gov/METS/"<br />
xmlns:xlink="http://www.w3.org/1999/xlink"<br />
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"<br />
xsi:schemaLocation="http://www.loc.gov/METS/ http://www.fedora.info/definitions/1/0/mets-fedora-ext1-1.xsd"><br />
<METS:fileSec><br />
<METS:fileGrp ID="DATASTREAMS"><br />
<METS:fileGrp ID="OBJ"><br />
<METS:file ID="OBJ.0"><br />
<METS:FLocat xlink:title="Cinderella_(1865).pdf" LOCTYPE="URL"<br />
xlink:href="http://localhost:8080/fedora/get/islandora:72/OBJ/2013-08-12T14:46:43.454Z" /><br />
</METS:file><br />
</METS:fileGrp><br />
</METS:fileGrp><br />
</METS:fileSec><br />
</METS:mets><br />
</pre><br />
<br />
Example Response:<br />
<pre><br />
201 Created<br />
Location: http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/<br />
<br />
<entry xmlns="http://www.w3.org/2005/Atom"<br />
xmlns:sword="http://purl.org/net/sword/"<br />
xmlns:dcterms="http://purl.org/dc/terms/"><br />
<br />
<title>Cinderella</title><br />
<id>91d4f258-0050-4914-9d0c-6a74815358d2</id><br />
<updated></updated><br />
<generator uri="https://www.archivematica.org" version="1.0"/><br />
<br />
<summary>A deposit was started.</summary><br />
<sword:treatment>A deposit directory was created and, optionally, asynchronous download of digital objects.</sword:treatment><br />
<br />
<link rel="alternate" href="http://www.swordserver.ac.uk/col1/mydeposit.html"/><br />
<link rel="edit-media" href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/media/"/><br />
<link rel="edit" href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/" /><br />
<link rel="http://purl.org/net/sword/terms/add" href="http://192.168.1.76:8000/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/" /><br />
<link rel="http://purl.org/net/sword/terms/statement" type="application/atom+xml;type=feed"<br />
href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/state/" /><br />
</entry><br />
</pre><br />
<br />
=== Add Files to a Transfer ===<br />
<br />
Posting file metadata (not yet implemented):<br />
* POST a METS file to the SE-IRI, listed below.<br />
* HTTP headers are required similar to Create Transfer call (above).<br />
* Body must include a valid Atom Entry document, that has METS embedded inside it.<br />
<br />
Posts file data:<br />
* It is possible to also POST the actual file to a deposit location's EM-IRI (/api/v1/location/[location UUID]/sword/media/)<br />
* The file should be posted as the request body and the filename specified using the Content-Disposition header (as per RFC 6266): for example "Content-Disposition: Attachment; filename=dog.jpg"<br />
* An MD5 checksum for an uploaded file can be provided via the Content-MD5 header (as per RFC 1544): for example "Content-MD5: Q2hlY2sgSW50ZWdyaXR5IQ=="<br />
* If only an Atom Entry Document is POST'ed, Archivematica will look for uri's in the file StructMap section of the METS file, and attempt to GET each file listed, to include in the Transfer. (not yet implemented)<br />
<br />
=== Finalize a Transfer ===<br />
* POST with no body to the SE-IRI<br />
* set In-Progress HTTP header to : false<br />
* This will tell Archivematica that no further content will be added or removed from the Transfer. <br />
* Archivematica will finish fetching any files that were added previously, and once they have all been downloaded, the Transfer will start through the Archivematica pipeline.<br />
<br />
'''Example'''<br />
<pre><br />
POST http://localhost/api/v1/location/55ce8053-113a-4954-8aa3-fc9771da0bda/sword/ HTTP/1.1<br />
Host: localhost<br />
Authorization: Archivematica-API api_key="XXXXXXXXXXXXXXXXXXXX", username="timh"<br />
Content-Length: 0<br />
Content-Type: application/atom+xml;type=entry<br />
In-Progress: false<br />
</pre><br />
<br />
The response will be HTTP 200/OK or 400/Error (400 if the Transfer was already finalized). If the transfer doesn't exist the response will be HTTP 404.<br />
<br />
=== Get Status of Transfer ===<br />
To check Status:<br />
<br />
GET the State-IRI<br />
in this example:<br />
<br />
GET http://localhost/api/v1/location/09224ddb-4c7d-404c-9218-2f2e1b5a599e/sword/state/ HTTP/1.1<br />
<br />
response will include:<br />
<pre><atom:feed xmlns:sword="http://purl.org/net/sword/terms/" <br />
xmlns:atom="http://www.w3.org/2005/Atom"><br />
<br />
<atom:category scheme="http://purl.org/net/sword/terms/state"<br />
term="failed"<br />
label="State"><br />
Deposit initiation: Failed<br />
</atom:category><br />
<br />
</atom:feed></pre><br />
the list of possible descriptions is not finalized.<br />
<br />
The state term value will either be "processing" (asynchronous deposit still working), "complete" (ready to be finalized), or "failed" (asynchronous deposit encountered an error).<br />
<br />
== Additional Details == <br />
<br />
=== Transfer Details ===<br />
* redirect to Edit-IRI<br />
* used to get basic info about a Transfer with HTTP GET<br />
* can update basic info using HTTP PUT (not yet implemented)<br />
* can allow deletion with HTTP DELETE<br />
* follows the form: /api/v1/location/[deposit location UUID]/sword/<br />
* example: http://192.168.1.231:8000/api/v1/location/09224ddb-4c7d-404c-9218-2f2e1b5a599e/sword/<br />
<br />
=== EM-IRI ===<br />
* Edit-Media IRI <br />
* used to add new objects to an existing transfer<br />
* follows the form: [archivematica hostname]/api/v2/transfer/[uuid of transfer]/media<br />
* example: /api/v1/location/[deposit location UUID]/sword/media/<br />
<br />
An HTTP POST to the em-iri for a transfer should include a file as the body<br />
<br />
An HTTP GET should return a list of files in the transfer<br />
<br />
An HTTP DELETE to the em-iri will remove all digital objects from the Transfer. This is a valid operation only while the Transfer is being assembled. Once the Transfer has been finalized, attempting to DELETE will return an error.<br />
<br />
=== Edit-IRI ===<br />
The client can replace the metadata of a resource by performing an HTTP PUT of a new Atom Entry on the Edit-IRI. (not yet implemented)<br />
<br />
This would be used to update metadata about a transfer, such as the transfer name.<br />
<br />
* example: http://localhost/api/v2/transfer/1225c695-cfb8-4ebb-aaaa-80da344efa6a/edit<br />
<br />
=== SE-IRI ===<br />
* example: http://localhost/api/v2/transfer/add/1225c695-cfb8-4ebb-aaaa-80da344efa6a (not yet implemented)<br />
<br />
=== State-IRI ===<br />
* used to retrieve status of transfer<br />
* implemented as Atom document<br />
* example: /api/v1/location/[deposit location UUID]/sword/state/<br />
* should be able to subscribe like RSS feed<br />
<br />
== Example session ==<br />
<br />
Below is an example session using curl to manipulate the API. In the example a deposit is created, a file is added to it, and it is finalized.<br />
<br />
NOTE: The SWORD API is in the process of being moved to the storage service. These URLs may not work.<br />
<br />
<pre># create new deposit<br />
curl -v -H "In-Progress: true" --data-binary @mets.xml --request POST http://localhost:8000/api/v1/location/52bbe770-3f96-4493-8d93-ded54c958c51/sword/collection/<br />
# response XML includes endpoints for adding addition files, etc.<br />
<br />
# add another file to the transfer<br />
curl -v -H "Content-Disposition: attachment; filename=joke.jpg" --request POST \<br />
--data-binary "@joke.jpg" \<br />
http://localhost:8000/api/v1/deposit/8e1cba3c-f133-48b2-afef-e42505a7bdc8/sword/media/<br />
<br />
# finalize transfer and approve processing<br />
curl -v -H "In-Progress: false" --request POST http://localhost:8000/api/v1/deposit/8e1cba3c-f133-48b2-afef-e42505a7bdc8/sword/</pre><br />
<br />
You might, at some point, want to list the transfers that have been started. The following curl command will do so.<br />
<br />
<pre>curl -v http://localhost:8000/api/v1/location/52bbe770-3f96-4493-8d93-ded54c958c51/sword/collection/</pre><br />
<br />
If you're working on a transfer and want to list what files are included in it, the following curl command will list them.<br />
<br />
<pre># list files in transfer<br />
curl -v http://192.168.1.231:8000/api/v1/deposit/8e1cba3c-f133-48b2-bdc8/sword/media/</pre><br />
<br />
If you've started a deposit, but want to discard it, you can delete the deposit. The following curl command shows an example.<br />
<br />
<pre>curl -v -XDELETE http://localhost:8000/api/v1/deposit/8e1cba3c-f133-48b2-afef-e42505a7bdc8/sword/</pre><br />
<br />
== Synchronous Deposit Examples ==<br />
<br />
If you wanted to deposit a transfer then immediately finalize it you could use something like the following curl command.<br />
<br />
<pre>curl -v -H "In-Progress: false" --data-binary @mets.xml --request POST http://localhost:8000/api/v1/location/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/</pre><br />
<br />
If you wanted to deposit a transfer, immediately finalize it, and have a pipeline automatically approve it you could use something like the following curl command.<br />
<br />
<pre>curl -v -H "In-Progress: false" --data-binary @mets.xml --request POST http://localhost:8000/api/v1/location/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/?approval_pipeline=41b57f04-9738-43d8-b80e-3fad88c75abc</pre></div>Mcantelonhttps://wiki.archivematica.org/index.php?title=Sword_API&diff=9159Sword API2013-11-25T21:56:14Z<p>Mcantelon: /* State-IRI */</p>
<hr />
<div><br />
== Overview ==<br />
<br />
One of the 1.1 release features is a sponsored project to integrate Archivematica with Islandora. This integration will be accomplished by creating a [http://swordapp.org Sword] 2.0 API for the Archivematica [https://www.archivematica.org/wiki/Administrator_manual_1.0#Storage_service storage service]. Islandora development work will add functionality to Islandora to use this API to deposit digital objects into Archviematica.<br />
<br />
As described [[Overview|elsewhere]] on this wiki, ''"the primary function of Archivematica is to process digital transfers (accessioned digital objects), turn them into SIPs, apply format policies and create high-quality, repository-independent Archival Information Packages (AIP)"''.<br />
<br />
The Archivematica Sword API allows 3rd party applications to automate the process of creating Transfers. <br />
#Create Transfer - set the name and other metadata about a Transfer<br />
#Populate Transfer - add/edit/update digital objects in a Transfer, and associated metadata<br />
#Finalize Transfer - indicates that the Transfer is ready to start processing.<br />
<br />
After content has been deposited, if users have access to the deposit directory they can also manually manipulate the deposit directory aside from any manipulation using the API.<br />
<br />
Once a Transfer has been created, populated and finalized, Archivematica will begin processing that Transfer.<br />
<br />
== Endpoints ==<br />
<br />
=== Service document ===<br />
<br />
The SWORD service document provides information about the SWORD provider's capacities and lists SWORD collections. Archivematica currently includes one SWORD collection to which SWORD deposits can be made: transfers.<br />
<br />
The SWORD service document endpoint is located at /api/v1/sword.<br />
<br />
=== List existing transfers ===<br />
* HTTP Get to the Collection IRI (defined by default as: /api/v1/space/[space UUID]/sword/collection/)<br />
* Transfers are listed as an Atom feed<br />
* Each Atom feed entry contains an "atom:link" element whose href attribute contains the URL needed to get details about the transfer<br />
* optional filters via get parameters (not yet implemented)<br />
<br />
=== Create a new transfer ===<br />
* used to start a new transfer in Archivematica<br />
* HTTP POST of an Atom Entry Document to the Collection IRI (defined by default as: /api/v1/space/[space UUID]/sword/collection/)<br />
<br />
'''Possible HTTP Response Codes'''<br />
* HTTP 200 OK - transfer already exists (not yet implemented)<br />
* HTTP 201 Created - transfer has been accepted<br />
* HTTP 412 Precondition Failed - required metadata missing or invalid<br />
<br />
Valid requests will receive a Sword Deposit Receipt in the body of the response.<br />
<br />
'''Required HTTP Headers'''<br />
The HTTP POST must include certain specific http headers. <br />
<br />
Required by http 1.1 specification:<br />
* Host: Must be set to archivematica host name.<br />
* Content-Length: Must be set to the length of the atom entry document.<br />
* Content-Type: Must be set to "application/atom+xml;type=entry".<br />
<br />
Required by Archivematica. <br />
* Authorization: Must include the api key and username assigned by Archivematica.<br />
<br />
Required by SWORD 2.0 protocol:<br />
* In-Progress: Must be set to "true"<br />
<br />
Optional in SWORD 2.0 protocol:<br />
* On-Behalf-Of: not implemented by Archivematica<br />
* Slug: not implemented by Archivematica<br />
<br />
'''Required in Body'''<br />
The Body of the request must be a valid METS Document. The required fields in an Atom Entry Document are:<br />
* LABEL: used as the transfer name<br />
* id: used as an accession id (not yet implemented)<br />
* author: used as the source of acquisition (not yet implemented)<br />
* summary: not implemented yet. Could be used in the future as a description for the Transfer<br />
* updated: should be set to the current timestamp. <br />
<br />
'''Example'''<br />
Example HTTP POST request:<br />
<pre><br />
POST /api/v1/space/96606387-cc70-4b09-b422-a7220606488d/sword/collection/ HTTP/1.1<br />
Host: localhost<br />
Authorization: Archivematica-API api_key="XXXXXXXXXXXXXXXXXXXX", username="timh"<br />
Content-Length: 213<br />
Content-Type: application/atom+xml;type=entry<br />
In-Progress: true<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<METS:mets EXT_VERSION="1.1" OBJID="islandora:72" LABEL="Cinderella"<br />
xmlns:METS="http://www.loc.gov/METS/"<br />
xmlns:xlink="http://www.w3.org/1999/xlink"<br />
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"<br />
xsi:schemaLocation="http://www.loc.gov/METS/ http://www.fedora.info/definitions/1/0/mets-fedora-ext1-1.xsd"><br />
<METS:fileSec><br />
<METS:fileGrp ID="DATASTREAMS"><br />
<METS:fileGrp ID="OBJ"><br />
<METS:file ID="OBJ.0"><br />
<METS:FLocat xlink:title="Cinderella_(1865).pdf" LOCTYPE="URL"<br />
xlink:href="http://localhost:8080/fedora/get/islandora:72/OBJ/2013-08-12T14:46:43.454Z" /><br />
</METS:file><br />
</METS:fileGrp><br />
</METS:fileGrp><br />
</METS:fileSec><br />
</METS:mets><br />
</pre><br />
<br />
Example Response:<br />
<pre><br />
201 Created<br />
Location: http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/<br />
<br />
<entry xmlns="http://www.w3.org/2005/Atom"<br />
xmlns:sword="http://purl.org/net/sword/"<br />
xmlns:dcterms="http://purl.org/dc/terms/"><br />
<br />
<title>Cinderella</title><br />
<id>91d4f258-0050-4914-9d0c-6a74815358d2</id><br />
<updated></updated><br />
<generator uri="https://www.archivematica.org" version="1.0"/><br />
<br />
<summary>A deposit was started.</summary><br />
<sword:treatment>A deposit directory was created and, optionally, asynchronous download of digital objects.</sword:treatment><br />
<br />
<link rel="alternate" href="http://www.swordserver.ac.uk/col1/mydeposit.html"/><br />
<link rel="edit-media" href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/media/"/><br />
<link rel="edit" href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/" /><br />
<link rel="http://purl.org/net/sword/terms/add" href="http://192.168.1.76:8000/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/" /><br />
<link rel="http://purl.org/net/sword/terms/statement" type="application/atom+xml;type=feed"<br />
href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/state/" /><br />
</entry><br />
</pre><br />
<br />
=== Add Files to a Transfer ===<br />
<br />
Posting file metadata (not yet implemented):<br />
* POST a METS file to the SE-IRI, listed below.<br />
* HTTP headers are required similar to Create Transfer call (above).<br />
* Body must include a valid Atom Entry document, that has METS embedded inside it.<br />
<br />
Posts file data:<br />
* It is possible to also POST the actual file to a deposit location's EM-IRI (/api/v1/location/[location UUID]/sword/media/)<br />
* The file should be posted as the request body and the filename specified using the Content-Disposition header (as per RFC 6266): for example "Content-Disposition: Attachment; filename=dog.jpg"<br />
* An MD5 checksum for an uploaded file can be provided via the Content-MD5 header (as per RFC 1544): for example "Content-MD5: Q2hlY2sgSW50ZWdyaXR5IQ=="<br />
* If only an Atom Entry Document is POST'ed, Archivematica will look for uri's in the file StructMap section of the METS file, and attempt to GET each file listed, to include in the Transfer. (not yet implemented)<br />
<br />
=== Finalize a Transfer ===<br />
* POST with no body to the SE-IRI<br />
* set In-Progress HTTP header to : false<br />
* This will tell Archivematica that no further content will be added or removed from the Transfer. <br />
* Archivematica will finish fetching any files that were added previously, and once they have all been downloaded, the Transfer will start through the Archivematica pipeline.<br />
<br />
'''Example'''<br />
<pre><br />
POST http://localhost/api/v1/location/55ce8053-113a-4954-8aa3-fc9771da0bda/sword/ HTTP/1.1<br />
Host: localhost<br />
Authorization: Archivematica-API api_key="XXXXXXXXXXXXXXXXXXXX", username="timh"<br />
Content-Length: 0<br />
Content-Type: application/atom+xml;type=entry<br />
In-Progress: false<br />
</pre><br />
<br />
The response will be HTTP 200/OK or 400/Error (400 if the Transfer was already finalized). If the transfer doesn't exist the response will be HTTP 404.<br />
<br />
If you add a URL parameter specifying the pipeline that should approve the transfer, for example adding "?approval_pipeline=3969b021-87d1-473e-93e0-50c8a2fa8329" to the URL, you can auto-approve the transfer.<br />
<br />
=== Get Status of Transfer ===<br />
To check Status:<br />
<br />
GET the State-IRI<br />
in this example:<br />
<br />
GET http://localhost/api/v1/location/09224ddb-4c7d-404c-9218-2f2e1b5a599e/sword/state/ HTTP/1.1<br />
<br />
response will include:<br />
<pre><atom:feed xmlns:sword="http://purl.org/net/sword/terms/" <br />
xmlns:atom="http://www.w3.org/2005/Atom"><br />
<br />
<atom:category scheme="http://purl.org/net/sword/terms/state"<br />
term="failed"<br />
label="State"><br />
Deposit initiation: Failed<br />
</atom:category><br />
<br />
</atom:feed></pre><br />
the list of possible descriptions is not finalized.<br />
<br />
The state term value will either be "processing" (asynchronous deposit still working), "complete" (ready to be finalized), or "failed" (asynchronous deposit encountered an error).<br />
<br />
== Additional Details == <br />
<br />
=== Transfer Details ===<br />
* redirect to Edit-IRI<br />
* used to get basic info about a Transfer with HTTP GET<br />
* can update basic info using HTTP PUT (not yet implemented)<br />
* can allow deletion with HTTP DELETE<br />
* follows the form: /api/v1/location/[deposit location UUID]/sword/<br />
* example: http://192.168.1.231:8000/api/v1/location/09224ddb-4c7d-404c-9218-2f2e1b5a599e/sword/<br />
<br />
=== EM-IRI ===<br />
* Edit-Media IRI <br />
* used to add new objects to an existing transfer<br />
* follows the form: [archivematica hostname]/api/v2/transfer/[uuid of transfer]/media<br />
* example: /api/v1/location/[deposit location UUID]/sword/media/<br />
<br />
An HTTP POST to the em-iri for a transfer should include a file as the body<br />
<br />
An HTTP GET should return a list of files in the transfer<br />
<br />
An HTTP DELETE to the em-iri will remove all digital objects from the Transfer. This is a valid operation only while the Transfer is being assembled. Once the Transfer has been finalized, attempting to DELETE will return an error.<br />
<br />
=== Edit-IRI ===<br />
The client can replace the metadata of a resource by performing an HTTP PUT of a new Atom Entry on the Edit-IRI. (not yet implemented)<br />
<br />
This would be used to update metadata about a transfer, such as the transfer name.<br />
<br />
* example: http://localhost/api/v2/transfer/1225c695-cfb8-4ebb-aaaa-80da344efa6a/edit<br />
<br />
=== SE-IRI ===<br />
* example: http://localhost/api/v2/transfer/add/1225c695-cfb8-4ebb-aaaa-80da344efa6a (not yet implemented)<br />
<br />
=== State-IRI ===<br />
* used to retrieve status of transfer<br />
* implemented as Atom document<br />
* example: /api/v1/location/[deposit location UUID]/sword/state/<br />
* should be able to subscribe like RSS feed<br />
<br />
== Example session ==<br />
<br />
Below is an example session using curl to manipulate the API. In the example a deposit is created, a file is added to it, and it is finalized.<br />
<br />
NOTE: The SWORD API is in the process of being moved to the storage service. These URLs may not work.<br />
<br />
<pre># create new deposit<br />
curl -v -H "In-Progress: true" --data-binary @mets.xml --request POST http://localhost:8000/api/v1/location/52bbe770-3f96-4493-8d93-ded54c958c51/sword/collection/<br />
# response XML includes endpoints for adding addition files, etc.<br />
<br />
# add another file to the transfer<br />
curl -v -H "Content-Disposition: attachment; filename=joke.jpg" --request POST \<br />
--data-binary "@joke.jpg" \<br />
http://localhost:8000/api/v1/deposit/8e1cba3c-f133-48b2-afef-e42505a7bdc8/sword/media/<br />
<br />
# finalize transfer and approve processing<br />
curl -v -H "In-Progress: false" --request POST http://localhost:8000/api/v1/deposit/8e1cba3c-f133-48b2-afef-e42505a7bdc8/sword/</pre><br />
<br />
You might, at some point, want to list the transfers that have been started. The following curl command will do so.<br />
<br />
<pre>curl -v http://localhost:8000/api/v1/location/52bbe770-3f96-4493-8d93-ded54c958c51/sword/collection/</pre><br />
<br />
If you're working on a transfer and want to list what files are included in it, the following curl command will list them.<br />
<br />
<pre># list files in transfer<br />
curl -v http://192.168.1.231:8000/api/v1/deposit/8e1cba3c-f133-48b2-bdc8/sword/media/</pre><br />
<br />
If you've started a deposit, but want to discard it, you can delete the deposit. The following curl command shows an example.<br />
<br />
<pre>curl -v -XDELETE http://localhost:8000/api/v1/deposit/8e1cba3c-f133-48b2-afef-e42505a7bdc8/sword/</pre><br />
<br />
== Synchronous Deposit Examples ==<br />
<br />
If you wanted to deposit a transfer then immediately finalize it you could use something like the following curl command.<br />
<br />
<pre>curl -v -H "In-Progress: false" --data-binary @mets.xml --request POST http://localhost:8000/api/v1/location/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/</pre><br />
<br />
If you wanted to deposit a transfer, immediately finalize it, and have a pipeline automatically approve it you could use something like the following curl command.<br />
<br />
<pre>curl -v -H "In-Progress: false" --data-binary @mets.xml --request POST http://localhost:8000/api/v1/location/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/?approval_pipeline=41b57f04-9738-43d8-b80e-3fad88c75abc</pre></div>Mcantelonhttps://wiki.archivematica.org/index.php?title=Sword_API&diff=9158Sword API2013-11-25T21:55:37Z<p>Mcantelon: /* SE-IRI */</p>
<hr />
<div><br />
== Overview ==<br />
<br />
One of the 1.1 release features is a sponsored project to integrate Archivematica with Islandora. This integration will be accomplished by creating a [http://swordapp.org Sword] 2.0 API for the Archivematica [https://www.archivematica.org/wiki/Administrator_manual_1.0#Storage_service storage service]. Islandora development work will add functionality to Islandora to use this API to deposit digital objects into Archviematica.<br />
<br />
As described [[Overview|elsewhere]] on this wiki, ''"the primary function of Archivematica is to process digital transfers (accessioned digital objects), turn them into SIPs, apply format policies and create high-quality, repository-independent Archival Information Packages (AIP)"''.<br />
<br />
The Archivematica Sword API allows 3rd party applications to automate the process of creating Transfers. <br />
#Create Transfer - set the name and other metadata about a Transfer<br />
#Populate Transfer - add/edit/update digital objects in a Transfer, and associated metadata<br />
#Finalize Transfer - indicates that the Transfer is ready to start processing.<br />
<br />
After content has been deposited, if users have access to the deposit directory they can also manually manipulate the deposit directory aside from any manipulation using the API.<br />
<br />
Once a Transfer has been created, populated and finalized, Archivematica will begin processing that Transfer.<br />
<br />
== Endpoints ==<br />
<br />
=== Service document ===<br />
<br />
The SWORD service document provides information about the SWORD provider's capacities and lists SWORD collections. Archivematica currently includes one SWORD collection to which SWORD deposits can be made: transfers.<br />
<br />
The SWORD service document endpoint is located at /api/v1/sword.<br />
<br />
=== List existing transfers ===<br />
* HTTP Get to the Collection IRI (defined by default as: /api/v1/space/[space UUID]/sword/collection/)<br />
* Transfers are listed as an Atom feed<br />
* Each Atom feed entry contains an "atom:link" element whose href attribute contains the URL needed to get details about the transfer<br />
* optional filters via get parameters (not yet implemented)<br />
<br />
=== Create a new transfer ===<br />
* used to start a new transfer in Archivematica<br />
* HTTP POST of an Atom Entry Document to the Collection IRI (defined by default as: /api/v1/space/[space UUID]/sword/collection/)<br />
<br />
'''Possible HTTP Response Codes'''<br />
* HTTP 200 OK - transfer already exists (not yet implemented)<br />
* HTTP 201 Created - transfer has been accepted<br />
* HTTP 412 Precondition Failed - required metadata missing or invalid<br />
<br />
Valid requests will receive a Sword Deposit Receipt in the body of the response.<br />
<br />
'''Required HTTP Headers'''<br />
The HTTP POST must include certain specific http headers. <br />
<br />
Required by http 1.1 specification:<br />
* Host: Must be set to archivematica host name.<br />
* Content-Length: Must be set to the length of the atom entry document.<br />
* Content-Type: Must be set to "application/atom+xml;type=entry".<br />
<br />
Required by Archivematica. <br />
* Authorization: Must include the api key and username assigned by Archivematica.<br />
<br />
Required by SWORD 2.0 protocol:<br />
* In-Progress: Must be set to "true"<br />
<br />
Optional in SWORD 2.0 protocol:<br />
* On-Behalf-Of: not implemented by Archivematica<br />
* Slug: not implemented by Archivematica<br />
<br />
'''Required in Body'''<br />
The Body of the request must be a valid METS Document. The required fields in an Atom Entry Document are:<br />
* LABEL: used as the transfer name<br />
* id: used as an accession id (not yet implemented)<br />
* author: used as the source of acquisition (not yet implemented)<br />
* summary: not implemented yet. Could be used in the future as a description for the Transfer<br />
* updated: should be set to the current timestamp. <br />
<br />
'''Example'''<br />
Example HTTP POST request:<br />
<pre><br />
POST /api/v1/space/96606387-cc70-4b09-b422-a7220606488d/sword/collection/ HTTP/1.1<br />
Host: localhost<br />
Authorization: Archivematica-API api_key="XXXXXXXXXXXXXXXXXXXX", username="timh"<br />
Content-Length: 213<br />
Content-Type: application/atom+xml;type=entry<br />
In-Progress: true<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<METS:mets EXT_VERSION="1.1" OBJID="islandora:72" LABEL="Cinderella"<br />
xmlns:METS="http://www.loc.gov/METS/"<br />
xmlns:xlink="http://www.w3.org/1999/xlink"<br />
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"<br />
xsi:schemaLocation="http://www.loc.gov/METS/ http://www.fedora.info/definitions/1/0/mets-fedora-ext1-1.xsd"><br />
<METS:fileSec><br />
<METS:fileGrp ID="DATASTREAMS"><br />
<METS:fileGrp ID="OBJ"><br />
<METS:file ID="OBJ.0"><br />
<METS:FLocat xlink:title="Cinderella_(1865).pdf" LOCTYPE="URL"<br />
xlink:href="http://localhost:8080/fedora/get/islandora:72/OBJ/2013-08-12T14:46:43.454Z" /><br />
</METS:file><br />
</METS:fileGrp><br />
</METS:fileGrp><br />
</METS:fileSec><br />
</METS:mets><br />
</pre><br />
<br />
Example Response:<br />
<pre><br />
201 Created<br />
Location: http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/<br />
<br />
<entry xmlns="http://www.w3.org/2005/Atom"<br />
xmlns:sword="http://purl.org/net/sword/"<br />
xmlns:dcterms="http://purl.org/dc/terms/"><br />
<br />
<title>Cinderella</title><br />
<id>91d4f258-0050-4914-9d0c-6a74815358d2</id><br />
<updated></updated><br />
<generator uri="https://www.archivematica.org" version="1.0"/><br />
<br />
<summary>A deposit was started.</summary><br />
<sword:treatment>A deposit directory was created and, optionally, asynchronous download of digital objects.</sword:treatment><br />
<br />
<link rel="alternate" href="http://www.swordserver.ac.uk/col1/mydeposit.html"/><br />
<link rel="edit-media" href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/media/"/><br />
<link rel="edit" href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/" /><br />
<link rel="http://purl.org/net/sword/terms/add" href="http://192.168.1.76:8000/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/" /><br />
<link rel="http://purl.org/net/sword/terms/statement" type="application/atom+xml;type=feed"<br />
href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/state/" /><br />
</entry><br />
</pre><br />
<br />
=== Add Files to a Transfer ===<br />
<br />
Posting file metadata (not yet implemented):<br />
* POST a METS file to the SE-IRI, listed below.<br />
* HTTP headers are required similar to Create Transfer call (above).<br />
* Body must include a valid Atom Entry document, that has METS embedded inside it.<br />
<br />
Posts file data:<br />
* It is possible to also POST the actual file to a deposit location's EM-IRI (/api/v1/location/[location UUID]/sword/media/)<br />
* The file should be posted as the request body and the filename specified using the Content-Disposition header (as per RFC 6266): for example "Content-Disposition: Attachment; filename=dog.jpg"<br />
* An MD5 checksum for an uploaded file can be provided via the Content-MD5 header (as per RFC 1544): for example "Content-MD5: Q2hlY2sgSW50ZWdyaXR5IQ=="<br />
* If only an Atom Entry Document is POST'ed, Archivematica will look for uri's in the file StructMap section of the METS file, and attempt to GET each file listed, to include in the Transfer. (not yet implemented)<br />
<br />
=== Finalize a Transfer ===<br />
* POST with no body to the SE-IRI<br />
* set In-Progress HTTP header to : false<br />
* This will tell Archivematica that no further content will be added or removed from the Transfer. <br />
* Archivematica will finish fetching any files that were added previously, and once they have all been downloaded, the Transfer will start through the Archivematica pipeline.<br />
<br />
'''Example'''<br />
<pre><br />
POST http://localhost/api/v1/location/55ce8053-113a-4954-8aa3-fc9771da0bda/sword/ HTTP/1.1<br />
Host: localhost<br />
Authorization: Archivematica-API api_key="XXXXXXXXXXXXXXXXXXXX", username="timh"<br />
Content-Length: 0<br />
Content-Type: application/atom+xml;type=entry<br />
In-Progress: false<br />
</pre><br />
<br />
The response will be HTTP 200/OK or 400/Error (400 if the Transfer was already finalized). If the transfer doesn't exist the response will be HTTP 404.<br />
<br />
If you add a URL parameter specifying the pipeline that should approve the transfer, for example adding "?approval_pipeline=3969b021-87d1-473e-93e0-50c8a2fa8329" to the URL, you can auto-approve the transfer.<br />
<br />
=== Get Status of Transfer ===<br />
To check Status:<br />
<br />
GET the State-IRI<br />
in this example:<br />
<br />
GET http://localhost/api/v1/location/09224ddb-4c7d-404c-9218-2f2e1b5a599e/sword/state/ HTTP/1.1<br />
<br />
response will include:<br />
<pre><atom:feed xmlns:sword="http://purl.org/net/sword/terms/" <br />
xmlns:atom="http://www.w3.org/2005/Atom"><br />
<br />
<atom:category scheme="http://purl.org/net/sword/terms/state"<br />
term="failed"<br />
label="State"><br />
Deposit initiation: Failed<br />
</atom:category><br />
<br />
</atom:feed></pre><br />
the list of possible descriptions is not finalized.<br />
<br />
The state term value will either be "processing" (asynchronous deposit still working), "complete" (ready to be finalized), or "failed" (asynchronous deposit encountered an error).<br />
<br />
== Additional Details == <br />
<br />
=== Transfer Details ===<br />
* redirect to Edit-IRI<br />
* used to get basic info about a Transfer with HTTP GET<br />
* can update basic info using HTTP PUT (not yet implemented)<br />
* can allow deletion with HTTP DELETE<br />
* follows the form: /api/v1/location/[deposit location UUID]/sword/<br />
* example: http://192.168.1.231:8000/api/v1/location/09224ddb-4c7d-404c-9218-2f2e1b5a599e/sword/<br />
<br />
=== EM-IRI ===<br />
* Edit-Media IRI <br />
* used to add new objects to an existing transfer<br />
* follows the form: [archivematica hostname]/api/v2/transfer/[uuid of transfer]/media<br />
* example: /api/v1/location/[deposit location UUID]/sword/media/<br />
<br />
An HTTP POST to the em-iri for a transfer should include a file as the body<br />
<br />
An HTTP GET should return a list of files in the transfer<br />
<br />
An HTTP DELETE to the em-iri will remove all digital objects from the Transfer. This is a valid operation only while the Transfer is being assembled. Once the Transfer has been finalized, attempting to DELETE will return an error.<br />
<br />
=== Edit-IRI ===<br />
The client can replace the metadata of a resource by performing an HTTP PUT of a new Atom Entry on the Edit-IRI. (not yet implemented)<br />
<br />
This would be used to update metadata about a transfer, such as the transfer name.<br />
<br />
* example: http://localhost/api/v2/transfer/1225c695-cfb8-4ebb-aaaa-80da344efa6a/edit<br />
<br />
=== SE-IRI ===<br />
* example: http://localhost/api/v2/transfer/add/1225c695-cfb8-4ebb-aaaa-80da344efa6a (not yet implemented)<br />
<br />
=== State-IRI ===<br />
* used to retrieve status of transfer<br />
* implemented as Atom document<br />
* example: http://localhost/api/v2/transfer/1225c695-cfb8-4ebb-aaaa-80da344efa6a/state<br />
* should be able to subscribe like RSS feed<br />
<br />
== Example session ==<br />
<br />
Below is an example session using curl to manipulate the API. In the example a deposit is created, a file is added to it, and it is finalized.<br />
<br />
NOTE: The SWORD API is in the process of being moved to the storage service. These URLs may not work.<br />
<br />
<pre># create new deposit<br />
curl -v -H "In-Progress: true" --data-binary @mets.xml --request POST http://localhost:8000/api/v1/location/52bbe770-3f96-4493-8d93-ded54c958c51/sword/collection/<br />
# response XML includes endpoints for adding addition files, etc.<br />
<br />
# add another file to the transfer<br />
curl -v -H "Content-Disposition: attachment; filename=joke.jpg" --request POST \<br />
--data-binary "@joke.jpg" \<br />
http://localhost:8000/api/v1/deposit/8e1cba3c-f133-48b2-afef-e42505a7bdc8/sword/media/<br />
<br />
# finalize transfer and approve processing<br />
curl -v -H "In-Progress: false" --request POST http://localhost:8000/api/v1/deposit/8e1cba3c-f133-48b2-afef-e42505a7bdc8/sword/</pre><br />
<br />
You might, at some point, want to list the transfers that have been started. The following curl command will do so.<br />
<br />
<pre>curl -v http://localhost:8000/api/v1/location/52bbe770-3f96-4493-8d93-ded54c958c51/sword/collection/</pre><br />
<br />
If you're working on a transfer and want to list what files are included in it, the following curl command will list them.<br />
<br />
<pre># list files in transfer<br />
curl -v http://192.168.1.231:8000/api/v1/deposit/8e1cba3c-f133-48b2-bdc8/sword/media/</pre><br />
<br />
If you've started a deposit, but want to discard it, you can delete the deposit. The following curl command shows an example.<br />
<br />
<pre>curl -v -XDELETE http://localhost:8000/api/v1/deposit/8e1cba3c-f133-48b2-afef-e42505a7bdc8/sword/</pre><br />
<br />
== Synchronous Deposit Examples ==<br />
<br />
If you wanted to deposit a transfer then immediately finalize it you could use something like the following curl command.<br />
<br />
<pre>curl -v -H "In-Progress: false" --data-binary @mets.xml --request POST http://localhost:8000/api/v1/location/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/</pre><br />
<br />
If you wanted to deposit a transfer, immediately finalize it, and have a pipeline automatically approve it you could use something like the following curl command.<br />
<br />
<pre>curl -v -H "In-Progress: false" --data-binary @mets.xml --request POST http://localhost:8000/api/v1/location/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/?approval_pipeline=41b57f04-9738-43d8-b80e-3fad88c75abc</pre></div>Mcantelonhttps://wiki.archivematica.org/index.php?title=Sword_API&diff=9157Sword API2013-11-25T21:55:15Z<p>Mcantelon: /* Edit-IRI */</p>
<hr />
<div><br />
== Overview ==<br />
<br />
One of the 1.1 release features is a sponsored project to integrate Archivematica with Islandora. This integration will be accomplished by creating a [http://swordapp.org Sword] 2.0 API for the Archivematica [https://www.archivematica.org/wiki/Administrator_manual_1.0#Storage_service storage service]. Islandora development work will add functionality to Islandora to use this API to deposit digital objects into Archviematica.<br />
<br />
As described [[Overview|elsewhere]] on this wiki, ''"the primary function of Archivematica is to process digital transfers (accessioned digital objects), turn them into SIPs, apply format policies and create high-quality, repository-independent Archival Information Packages (AIP)"''.<br />
<br />
The Archivematica Sword API allows 3rd party applications to automate the process of creating Transfers. <br />
#Create Transfer - set the name and other metadata about a Transfer<br />
#Populate Transfer - add/edit/update digital objects in a Transfer, and associated metadata<br />
#Finalize Transfer - indicates that the Transfer is ready to start processing.<br />
<br />
After content has been deposited, if users have access to the deposit directory they can also manually manipulate the deposit directory aside from any manipulation using the API.<br />
<br />
Once a Transfer has been created, populated and finalized, Archivematica will begin processing that Transfer.<br />
<br />
== Endpoints ==<br />
<br />
=== Service document ===<br />
<br />
The SWORD service document provides information about the SWORD provider's capacities and lists SWORD collections. Archivematica currently includes one SWORD collection to which SWORD deposits can be made: transfers.<br />
<br />
The SWORD service document endpoint is located at /api/v1/sword.<br />
<br />
=== List existing transfers ===<br />
* HTTP Get to the Collection IRI (defined by default as: /api/v1/space/[space UUID]/sword/collection/)<br />
* Transfers are listed as an Atom feed<br />
* Each Atom feed entry contains an "atom:link" element whose href attribute contains the URL needed to get details about the transfer<br />
* optional filters via get parameters (not yet implemented)<br />
<br />
=== Create a new transfer ===<br />
* used to start a new transfer in Archivematica<br />
* HTTP POST of an Atom Entry Document to the Collection IRI (defined by default as: /api/v1/space/[space UUID]/sword/collection/)<br />
<br />
'''Possible HTTP Response Codes'''<br />
* HTTP 200 OK - transfer already exists (not yet implemented)<br />
* HTTP 201 Created - transfer has been accepted<br />
* HTTP 412 Precondition Failed - required metadata missing or invalid<br />
<br />
Valid requests will receive a Sword Deposit Receipt in the body of the response.<br />
<br />
'''Required HTTP Headers'''<br />
The HTTP POST must include certain specific http headers. <br />
<br />
Required by http 1.1 specification:<br />
* Host: Must be set to archivematica host name.<br />
* Content-Length: Must be set to the length of the atom entry document.<br />
* Content-Type: Must be set to "application/atom+xml;type=entry".<br />
<br />
Required by Archivematica. <br />
* Authorization: Must include the api key and username assigned by Archivematica.<br />
<br />
Required by SWORD 2.0 protocol:<br />
* In-Progress: Must be set to "true"<br />
<br />
Optional in SWORD 2.0 protocol:<br />
* On-Behalf-Of: not implemented by Archivematica<br />
* Slug: not implemented by Archivematica<br />
<br />
'''Required in Body'''<br />
The Body of the request must be a valid METS Document. The required fields in an Atom Entry Document are:<br />
* LABEL: used as the transfer name<br />
* id: used as an accession id (not yet implemented)<br />
* author: used as the source of acquisition (not yet implemented)<br />
* summary: not implemented yet. Could be used in the future as a description for the Transfer<br />
* updated: should be set to the current timestamp. <br />
<br />
'''Example'''<br />
Example HTTP POST request:<br />
<pre><br />
POST /api/v1/space/96606387-cc70-4b09-b422-a7220606488d/sword/collection/ HTTP/1.1<br />
Host: localhost<br />
Authorization: Archivematica-API api_key="XXXXXXXXXXXXXXXXXXXX", username="timh"<br />
Content-Length: 213<br />
Content-Type: application/atom+xml;type=entry<br />
In-Progress: true<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<METS:mets EXT_VERSION="1.1" OBJID="islandora:72" LABEL="Cinderella"<br />
xmlns:METS="http://www.loc.gov/METS/"<br />
xmlns:xlink="http://www.w3.org/1999/xlink"<br />
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"<br />
xsi:schemaLocation="http://www.loc.gov/METS/ http://www.fedora.info/definitions/1/0/mets-fedora-ext1-1.xsd"><br />
<METS:fileSec><br />
<METS:fileGrp ID="DATASTREAMS"><br />
<METS:fileGrp ID="OBJ"><br />
<METS:file ID="OBJ.0"><br />
<METS:FLocat xlink:title="Cinderella_(1865).pdf" LOCTYPE="URL"<br />
xlink:href="http://localhost:8080/fedora/get/islandora:72/OBJ/2013-08-12T14:46:43.454Z" /><br />
</METS:file><br />
</METS:fileGrp><br />
</METS:fileGrp><br />
</METS:fileSec><br />
</METS:mets><br />
</pre><br />
<br />
Example Response:<br />
<pre><br />
201 Created<br />
Location: http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/<br />
<br />
<entry xmlns="http://www.w3.org/2005/Atom"<br />
xmlns:sword="http://purl.org/net/sword/"<br />
xmlns:dcterms="http://purl.org/dc/terms/"><br />
<br />
<title>Cinderella</title><br />
<id>91d4f258-0050-4914-9d0c-6a74815358d2</id><br />
<updated></updated><br />
<generator uri="https://www.archivematica.org" version="1.0"/><br />
<br />
<summary>A deposit was started.</summary><br />
<sword:treatment>A deposit directory was created and, optionally, asynchronous download of digital objects.</sword:treatment><br />
<br />
<link rel="alternate" href="http://www.swordserver.ac.uk/col1/mydeposit.html"/><br />
<link rel="edit-media" href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/media/"/><br />
<link rel="edit" href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/" /><br />
<link rel="http://purl.org/net/sword/terms/add" href="http://192.168.1.76:8000/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/" /><br />
<link rel="http://purl.org/net/sword/terms/statement" type="application/atom+xml;type=feed"<br />
href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/state/" /><br />
</entry><br />
</pre><br />
<br />
=== Add Files to a Transfer ===<br />
<br />
Posting file metadata (not yet implemented):<br />
* POST a METS file to the SE-IRI, listed below.<br />
* HTTP headers are required similar to Create Transfer call (above).<br />
* Body must include a valid Atom Entry document, that has METS embedded inside it.<br />
<br />
Posts file data:<br />
* It is possible to also POST the actual file to a deposit location's EM-IRI (/api/v1/location/[location UUID]/sword/media/)<br />
* The file should be posted as the request body and the filename specified using the Content-Disposition header (as per RFC 6266): for example "Content-Disposition: Attachment; filename=dog.jpg"<br />
* An MD5 checksum for an uploaded file can be provided via the Content-MD5 header (as per RFC 1544): for example "Content-MD5: Q2hlY2sgSW50ZWdyaXR5IQ=="<br />
* If only an Atom Entry Document is POST'ed, Archivematica will look for uri's in the file StructMap section of the METS file, and attempt to GET each file listed, to include in the Transfer. (not yet implemented)<br />
<br />
=== Finalize a Transfer ===<br />
* POST with no body to the SE-IRI<br />
* set In-Progress HTTP header to : false<br />
* This will tell Archivematica that no further content will be added or removed from the Transfer. <br />
* Archivematica will finish fetching any files that were added previously, and once they have all been downloaded, the Transfer will start through the Archivematica pipeline.<br />
<br />
'''Example'''<br />
<pre><br />
POST http://localhost/api/v1/location/55ce8053-113a-4954-8aa3-fc9771da0bda/sword/ HTTP/1.1<br />
Host: localhost<br />
Authorization: Archivematica-API api_key="XXXXXXXXXXXXXXXXXXXX", username="timh"<br />
Content-Length: 0<br />
Content-Type: application/atom+xml;type=entry<br />
In-Progress: false<br />
</pre><br />
<br />
The response will be HTTP 200/OK or 400/Error (400 if the Transfer was already finalized). If the transfer doesn't exist the response will be HTTP 404.<br />
<br />
If you add a URL parameter specifying the pipeline that should approve the transfer, for example adding "?approval_pipeline=3969b021-87d1-473e-93e0-50c8a2fa8329" to the URL, you can auto-approve the transfer.<br />
<br />
=== Get Status of Transfer ===<br />
To check Status:<br />
<br />
GET the State-IRI<br />
in this example:<br />
<br />
GET http://localhost/api/v1/location/09224ddb-4c7d-404c-9218-2f2e1b5a599e/sword/state/ HTTP/1.1<br />
<br />
response will include:<br />
<pre><atom:feed xmlns:sword="http://purl.org/net/sword/terms/" <br />
xmlns:atom="http://www.w3.org/2005/Atom"><br />
<br />
<atom:category scheme="http://purl.org/net/sword/terms/state"<br />
term="failed"<br />
label="State"><br />
Deposit initiation: Failed<br />
</atom:category><br />
<br />
</atom:feed></pre><br />
the list of possible descriptions is not finalized.<br />
<br />
The state term value will either be "processing" (asynchronous deposit still working), "complete" (ready to be finalized), or "failed" (asynchronous deposit encountered an error).<br />
<br />
== Additional Details == <br />
<br />
=== Transfer Details ===<br />
* redirect to Edit-IRI<br />
* used to get basic info about a Transfer with HTTP GET<br />
* can update basic info using HTTP PUT (not yet implemented)<br />
* can allow deletion with HTTP DELETE<br />
* follows the form: /api/v1/location/[deposit location UUID]/sword/<br />
* example: http://192.168.1.231:8000/api/v1/location/09224ddb-4c7d-404c-9218-2f2e1b5a599e/sword/<br />
<br />
=== EM-IRI ===<br />
* Edit-Media IRI <br />
* used to add new objects to an existing transfer<br />
* follows the form: [archivematica hostname]/api/v2/transfer/[uuid of transfer]/media<br />
* example: /api/v1/location/[deposit location UUID]/sword/media/<br />
<br />
An HTTP POST to the em-iri for a transfer should include a file as the body<br />
<br />
An HTTP GET should return a list of files in the transfer<br />
<br />
An HTTP DELETE to the em-iri will remove all digital objects from the Transfer. This is a valid operation only while the Transfer is being assembled. Once the Transfer has been finalized, attempting to DELETE will return an error.<br />
<br />
=== Edit-IRI ===<br />
The client can replace the metadata of a resource by performing an HTTP PUT of a new Atom Entry on the Edit-IRI. (not yet implemented)<br />
<br />
This would be used to update metadata about a transfer, such as the transfer name.<br />
<br />
* example: http://localhost/api/v2/transfer/1225c695-cfb8-4ebb-aaaa-80da344efa6a/edit<br />
<br />
=== SE-IRI ===<br />
* example: http://localhost/api/v2/transfer/add/1225c695-cfb8-4ebb-aaaa-80da344efa6a<br />
<br />
=== State-IRI ===<br />
* used to retrieve status of transfer<br />
* implemented as Atom document<br />
* example: http://localhost/api/v2/transfer/1225c695-cfb8-4ebb-aaaa-80da344efa6a/state<br />
* should be able to subscribe like RSS feed<br />
<br />
== Example session ==<br />
<br />
Below is an example session using curl to manipulate the API. In the example a deposit is created, a file is added to it, and it is finalized.<br />
<br />
NOTE: The SWORD API is in the process of being moved to the storage service. These URLs may not work.<br />
<br />
<pre># create new deposit<br />
curl -v -H "In-Progress: true" --data-binary @mets.xml --request POST http://localhost:8000/api/v1/location/52bbe770-3f96-4493-8d93-ded54c958c51/sword/collection/<br />
# response XML includes endpoints for adding addition files, etc.<br />
<br />
# add another file to the transfer<br />
curl -v -H "Content-Disposition: attachment; filename=joke.jpg" --request POST \<br />
--data-binary "@joke.jpg" \<br />
http://localhost:8000/api/v1/deposit/8e1cba3c-f133-48b2-afef-e42505a7bdc8/sword/media/<br />
<br />
# finalize transfer and approve processing<br />
curl -v -H "In-Progress: false" --request POST http://localhost:8000/api/v1/deposit/8e1cba3c-f133-48b2-afef-e42505a7bdc8/sword/</pre><br />
<br />
You might, at some point, want to list the transfers that have been started. The following curl command will do so.<br />
<br />
<pre>curl -v http://localhost:8000/api/v1/location/52bbe770-3f96-4493-8d93-ded54c958c51/sword/collection/</pre><br />
<br />
If you're working on a transfer and want to list what files are included in it, the following curl command will list them.<br />
<br />
<pre># list files in transfer<br />
curl -v http://192.168.1.231:8000/api/v1/deposit/8e1cba3c-f133-48b2-bdc8/sword/media/</pre><br />
<br />
If you've started a deposit, but want to discard it, you can delete the deposit. The following curl command shows an example.<br />
<br />
<pre>curl -v -XDELETE http://localhost:8000/api/v1/deposit/8e1cba3c-f133-48b2-afef-e42505a7bdc8/sword/</pre><br />
<br />
== Synchronous Deposit Examples ==<br />
<br />
If you wanted to deposit a transfer then immediately finalize it you could use something like the following curl command.<br />
<br />
<pre>curl -v -H "In-Progress: false" --data-binary @mets.xml --request POST http://localhost:8000/api/v1/location/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/</pre><br />
<br />
If you wanted to deposit a transfer, immediately finalize it, and have a pipeline automatically approve it you could use something like the following curl command.<br />
<br />
<pre>curl -v -H "In-Progress: false" --data-binary @mets.xml --request POST http://localhost:8000/api/v1/location/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/?approval_pipeline=41b57f04-9738-43d8-b80e-3fad88c75abc</pre></div>Mcantelonhttps://wiki.archivematica.org/index.php?title=Sword_API&diff=9156Sword API2013-11-25T21:54:55Z<p>Mcantelon: /* EM-IRI */</p>
<hr />
<div><br />
== Overview ==<br />
<br />
One of the 1.1 release features is a sponsored project to integrate Archivematica with Islandora. This integration will be accomplished by creating a [http://swordapp.org Sword] 2.0 API for the Archivematica [https://www.archivematica.org/wiki/Administrator_manual_1.0#Storage_service storage service]. Islandora development work will add functionality to Islandora to use this API to deposit digital objects into Archviematica.<br />
<br />
As described [[Overview|elsewhere]] on this wiki, ''"the primary function of Archivematica is to process digital transfers (accessioned digital objects), turn them into SIPs, apply format policies and create high-quality, repository-independent Archival Information Packages (AIP)"''.<br />
<br />
The Archivematica Sword API allows 3rd party applications to automate the process of creating Transfers. <br />
#Create Transfer - set the name and other metadata about a Transfer<br />
#Populate Transfer - add/edit/update digital objects in a Transfer, and associated metadata<br />
#Finalize Transfer - indicates that the Transfer is ready to start processing.<br />
<br />
After content has been deposited, if users have access to the deposit directory they can also manually manipulate the deposit directory aside from any manipulation using the API.<br />
<br />
Once a Transfer has been created, populated and finalized, Archivematica will begin processing that Transfer.<br />
<br />
== Endpoints ==<br />
<br />
=== Service document ===<br />
<br />
The SWORD service document provides information about the SWORD provider's capacities and lists SWORD collections. Archivematica currently includes one SWORD collection to which SWORD deposits can be made: transfers.<br />
<br />
The SWORD service document endpoint is located at /api/v1/sword.<br />
<br />
=== List existing transfers ===<br />
* HTTP Get to the Collection IRI (defined by default as: /api/v1/space/[space UUID]/sword/collection/)<br />
* Transfers are listed as an Atom feed<br />
* Each Atom feed entry contains an "atom:link" element whose href attribute contains the URL needed to get details about the transfer<br />
* optional filters via get parameters (not yet implemented)<br />
<br />
=== Create a new transfer ===<br />
* used to start a new transfer in Archivematica<br />
* HTTP POST of an Atom Entry Document to the Collection IRI (defined by default as: /api/v1/space/[space UUID]/sword/collection/)<br />
<br />
'''Possible HTTP Response Codes'''<br />
* HTTP 200 OK - transfer already exists (not yet implemented)<br />
* HTTP 201 Created - transfer has been accepted<br />
* HTTP 412 Precondition Failed - required metadata missing or invalid<br />
<br />
Valid requests will receive a Sword Deposit Receipt in the body of the response.<br />
<br />
'''Required HTTP Headers'''<br />
The HTTP POST must include certain specific http headers. <br />
<br />
Required by http 1.1 specification:<br />
* Host: Must be set to archivematica host name.<br />
* Content-Length: Must be set to the length of the atom entry document.<br />
* Content-Type: Must be set to "application/atom+xml;type=entry".<br />
<br />
Required by Archivematica. <br />
* Authorization: Must include the api key and username assigned by Archivematica.<br />
<br />
Required by SWORD 2.0 protocol:<br />
* In-Progress: Must be set to "true"<br />
<br />
Optional in SWORD 2.0 protocol:<br />
* On-Behalf-Of: not implemented by Archivematica<br />
* Slug: not implemented by Archivematica<br />
<br />
'''Required in Body'''<br />
The Body of the request must be a valid METS Document. The required fields in an Atom Entry Document are:<br />
* LABEL: used as the transfer name<br />
* id: used as an accession id (not yet implemented)<br />
* author: used as the source of acquisition (not yet implemented)<br />
* summary: not implemented yet. Could be used in the future as a description for the Transfer<br />
* updated: should be set to the current timestamp. <br />
<br />
'''Example'''<br />
Example HTTP POST request:<br />
<pre><br />
POST /api/v1/space/96606387-cc70-4b09-b422-a7220606488d/sword/collection/ HTTP/1.1<br />
Host: localhost<br />
Authorization: Archivematica-API api_key="XXXXXXXXXXXXXXXXXXXX", username="timh"<br />
Content-Length: 213<br />
Content-Type: application/atom+xml;type=entry<br />
In-Progress: true<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<METS:mets EXT_VERSION="1.1" OBJID="islandora:72" LABEL="Cinderella"<br />
xmlns:METS="http://www.loc.gov/METS/"<br />
xmlns:xlink="http://www.w3.org/1999/xlink"<br />
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"<br />
xsi:schemaLocation="http://www.loc.gov/METS/ http://www.fedora.info/definitions/1/0/mets-fedora-ext1-1.xsd"><br />
<METS:fileSec><br />
<METS:fileGrp ID="DATASTREAMS"><br />
<METS:fileGrp ID="OBJ"><br />
<METS:file ID="OBJ.0"><br />
<METS:FLocat xlink:title="Cinderella_(1865).pdf" LOCTYPE="URL"<br />
xlink:href="http://localhost:8080/fedora/get/islandora:72/OBJ/2013-08-12T14:46:43.454Z" /><br />
</METS:file><br />
</METS:fileGrp><br />
</METS:fileGrp><br />
</METS:fileSec><br />
</METS:mets><br />
</pre><br />
<br />
Example Response:<br />
<pre><br />
201 Created<br />
Location: http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/<br />
<br />
<entry xmlns="http://www.w3.org/2005/Atom"<br />
xmlns:sword="http://purl.org/net/sword/"<br />
xmlns:dcterms="http://purl.org/dc/terms/"><br />
<br />
<title>Cinderella</title><br />
<id>91d4f258-0050-4914-9d0c-6a74815358d2</id><br />
<updated></updated><br />
<generator uri="https://www.archivematica.org" version="1.0"/><br />
<br />
<summary>A deposit was started.</summary><br />
<sword:treatment>A deposit directory was created and, optionally, asynchronous download of digital objects.</sword:treatment><br />
<br />
<link rel="alternate" href="http://www.swordserver.ac.uk/col1/mydeposit.html"/><br />
<link rel="edit-media" href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/media/"/><br />
<link rel="edit" href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/" /><br />
<link rel="http://purl.org/net/sword/terms/add" href="http://192.168.1.76:8000/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/" /><br />
<link rel="http://purl.org/net/sword/terms/statement" type="application/atom+xml;type=feed"<br />
href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/state/" /><br />
</entry><br />
</pre><br />
<br />
=== Add Files to a Transfer ===<br />
<br />
Posting file metadata (not yet implemented):<br />
* POST a METS file to the SE-IRI, listed below.<br />
* HTTP headers are required similar to Create Transfer call (above).<br />
* Body must include a valid Atom Entry document, that has METS embedded inside it.<br />
<br />
Posts file data:<br />
* It is possible to also POST the actual file to a deposit location's EM-IRI (/api/v1/location/[location UUID]/sword/media/)<br />
* The file should be posted as the request body and the filename specified using the Content-Disposition header (as per RFC 6266): for example "Content-Disposition: Attachment; filename=dog.jpg"<br />
* An MD5 checksum for an uploaded file can be provided via the Content-MD5 header (as per RFC 1544): for example "Content-MD5: Q2hlY2sgSW50ZWdyaXR5IQ=="<br />
* If only an Atom Entry Document is POST'ed, Archivematica will look for uri's in the file StructMap section of the METS file, and attempt to GET each file listed, to include in the Transfer. (not yet implemented)<br />
<br />
=== Finalize a Transfer ===<br />
* POST with no body to the SE-IRI<br />
* set In-Progress HTTP header to : false<br />
* This will tell Archivematica that no further content will be added or removed from the Transfer. <br />
* Archivematica will finish fetching any files that were added previously, and once they have all been downloaded, the Transfer will start through the Archivematica pipeline.<br />
<br />
'''Example'''<br />
<pre><br />
POST http://localhost/api/v1/location/55ce8053-113a-4954-8aa3-fc9771da0bda/sword/ HTTP/1.1<br />
Host: localhost<br />
Authorization: Archivematica-API api_key="XXXXXXXXXXXXXXXXXXXX", username="timh"<br />
Content-Length: 0<br />
Content-Type: application/atom+xml;type=entry<br />
In-Progress: false<br />
</pre><br />
<br />
The response will be HTTP 200/OK or 400/Error (400 if the Transfer was already finalized). If the transfer doesn't exist the response will be HTTP 404.<br />
<br />
If you add a URL parameter specifying the pipeline that should approve the transfer, for example adding "?approval_pipeline=3969b021-87d1-473e-93e0-50c8a2fa8329" to the URL, you can auto-approve the transfer.<br />
<br />
=== Get Status of Transfer ===<br />
To check Status:<br />
<br />
GET the State-IRI<br />
in this example:<br />
<br />
GET http://localhost/api/v1/location/09224ddb-4c7d-404c-9218-2f2e1b5a599e/sword/state/ HTTP/1.1<br />
<br />
response will include:<br />
<pre><atom:feed xmlns:sword="http://purl.org/net/sword/terms/" <br />
xmlns:atom="http://www.w3.org/2005/Atom"><br />
<br />
<atom:category scheme="http://purl.org/net/sword/terms/state"<br />
term="failed"<br />
label="State"><br />
Deposit initiation: Failed<br />
</atom:category><br />
<br />
</atom:feed></pre><br />
the list of possible descriptions is not finalized.<br />
<br />
The state term value will either be "processing" (asynchronous deposit still working), "complete" (ready to be finalized), or "failed" (asynchronous deposit encountered an error).<br />
<br />
== Additional Details == <br />
<br />
=== Transfer Details ===<br />
* redirect to Edit-IRI<br />
* used to get basic info about a Transfer with HTTP GET<br />
* can update basic info using HTTP PUT (not yet implemented)<br />
* can allow deletion with HTTP DELETE<br />
* follows the form: /api/v1/location/[deposit location UUID]/sword/<br />
* example: http://192.168.1.231:8000/api/v1/location/09224ddb-4c7d-404c-9218-2f2e1b5a599e/sword/<br />
<br />
=== EM-IRI ===<br />
* Edit-Media IRI <br />
* used to add new objects to an existing transfer<br />
* follows the form: [archivematica hostname]/api/v2/transfer/[uuid of transfer]/media<br />
* example: /api/v1/location/[deposit location UUID]/sword/media/<br />
<br />
An HTTP POST to the em-iri for a transfer should include a file as the body<br />
<br />
An HTTP GET should return a list of files in the transfer<br />
<br />
An HTTP DELETE to the em-iri will remove all digital objects from the Transfer. This is a valid operation only while the Transfer is being assembled. Once the Transfer has been finalized, attempting to DELETE will return an error.<br />
<br />
=== Edit-IRI ===<br />
The client can replace the metadata of a resource by performing an HTTP PUT of a new Atom Entry on the Edit-IRI.<br />
<br />
This would be used to update metadata about a transfer, such as the transfer name.<br />
<br />
* example: http://localhost/api/v2/transfer/1225c695-cfb8-4ebb-aaaa-80da344efa6a/edit<br />
<br />
=== SE-IRI ===<br />
* example: http://localhost/api/v2/transfer/add/1225c695-cfb8-4ebb-aaaa-80da344efa6a<br />
<br />
=== State-IRI ===<br />
* used to retrieve status of transfer<br />
* implemented as Atom document<br />
* example: http://localhost/api/v2/transfer/1225c695-cfb8-4ebb-aaaa-80da344efa6a/state<br />
* should be able to subscribe like RSS feed<br />
<br />
== Example session ==<br />
<br />
Below is an example session using curl to manipulate the API. In the example a deposit is created, a file is added to it, and it is finalized.<br />
<br />
NOTE: The SWORD API is in the process of being moved to the storage service. These URLs may not work.<br />
<br />
<pre># create new deposit<br />
curl -v -H "In-Progress: true" --data-binary @mets.xml --request POST http://localhost:8000/api/v1/location/52bbe770-3f96-4493-8d93-ded54c958c51/sword/collection/<br />
# response XML includes endpoints for adding addition files, etc.<br />
<br />
# add another file to the transfer<br />
curl -v -H "Content-Disposition: attachment; filename=joke.jpg" --request POST \<br />
--data-binary "@joke.jpg" \<br />
http://localhost:8000/api/v1/deposit/8e1cba3c-f133-48b2-afef-e42505a7bdc8/sword/media/<br />
<br />
# finalize transfer and approve processing<br />
curl -v -H "In-Progress: false" --request POST http://localhost:8000/api/v1/deposit/8e1cba3c-f133-48b2-afef-e42505a7bdc8/sword/</pre><br />
<br />
You might, at some point, want to list the transfers that have been started. The following curl command will do so.<br />
<br />
<pre>curl -v http://localhost:8000/api/v1/location/52bbe770-3f96-4493-8d93-ded54c958c51/sword/collection/</pre><br />
<br />
If you're working on a transfer and want to list what files are included in it, the following curl command will list them.<br />
<br />
<pre># list files in transfer<br />
curl -v http://192.168.1.231:8000/api/v1/deposit/8e1cba3c-f133-48b2-bdc8/sword/media/</pre><br />
<br />
If you've started a deposit, but want to discard it, you can delete the deposit. The following curl command shows an example.<br />
<br />
<pre>curl -v -XDELETE http://localhost:8000/api/v1/deposit/8e1cba3c-f133-48b2-afef-e42505a7bdc8/sword/</pre><br />
<br />
== Synchronous Deposit Examples ==<br />
<br />
If you wanted to deposit a transfer then immediately finalize it you could use something like the following curl command.<br />
<br />
<pre>curl -v -H "In-Progress: false" --data-binary @mets.xml --request POST http://localhost:8000/api/v1/location/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/</pre><br />
<br />
If you wanted to deposit a transfer, immediately finalize it, and have a pipeline automatically approve it you could use something like the following curl command.<br />
<br />
<pre>curl -v -H "In-Progress: false" --data-binary @mets.xml --request POST http://localhost:8000/api/v1/location/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/?approval_pipeline=41b57f04-9738-43d8-b80e-3fad88c75abc</pre></div>Mcantelonhttps://wiki.archivematica.org/index.php?title=Sword_API&diff=9155Sword API2013-11-25T21:53:35Z<p>Mcantelon: /* Transfer Details */</p>
<hr />
<div><br />
== Overview ==<br />
<br />
One of the 1.1 release features is a sponsored project to integrate Archivematica with Islandora. This integration will be accomplished by creating a [http://swordapp.org Sword] 2.0 API for the Archivematica [https://www.archivematica.org/wiki/Administrator_manual_1.0#Storage_service storage service]. Islandora development work will add functionality to Islandora to use this API to deposit digital objects into Archviematica.<br />
<br />
As described [[Overview|elsewhere]] on this wiki, ''"the primary function of Archivematica is to process digital transfers (accessioned digital objects), turn them into SIPs, apply format policies and create high-quality, repository-independent Archival Information Packages (AIP)"''.<br />
<br />
The Archivematica Sword API allows 3rd party applications to automate the process of creating Transfers. <br />
#Create Transfer - set the name and other metadata about a Transfer<br />
#Populate Transfer - add/edit/update digital objects in a Transfer, and associated metadata<br />
#Finalize Transfer - indicates that the Transfer is ready to start processing.<br />
<br />
After content has been deposited, if users have access to the deposit directory they can also manually manipulate the deposit directory aside from any manipulation using the API.<br />
<br />
Once a Transfer has been created, populated and finalized, Archivematica will begin processing that Transfer.<br />
<br />
== Endpoints ==<br />
<br />
=== Service document ===<br />
<br />
The SWORD service document provides information about the SWORD provider's capacities and lists SWORD collections. Archivematica currently includes one SWORD collection to which SWORD deposits can be made: transfers.<br />
<br />
The SWORD service document endpoint is located at /api/v1/sword.<br />
<br />
=== List existing transfers ===<br />
* HTTP Get to the Collection IRI (defined by default as: /api/v1/space/[space UUID]/sword/collection/)<br />
* Transfers are listed as an Atom feed<br />
* Each Atom feed entry contains an "atom:link" element whose href attribute contains the URL needed to get details about the transfer<br />
* optional filters via get parameters (not yet implemented)<br />
<br />
=== Create a new transfer ===<br />
* used to start a new transfer in Archivematica<br />
* HTTP POST of an Atom Entry Document to the Collection IRI (defined by default as: /api/v1/space/[space UUID]/sword/collection/)<br />
<br />
'''Possible HTTP Response Codes'''<br />
* HTTP 200 OK - transfer already exists (not yet implemented)<br />
* HTTP 201 Created - transfer has been accepted<br />
* HTTP 412 Precondition Failed - required metadata missing or invalid<br />
<br />
Valid requests will receive a Sword Deposit Receipt in the body of the response.<br />
<br />
'''Required HTTP Headers'''<br />
The HTTP POST must include certain specific http headers. <br />
<br />
Required by http 1.1 specification:<br />
* Host: Must be set to archivematica host name.<br />
* Content-Length: Must be set to the length of the atom entry document.<br />
* Content-Type: Must be set to "application/atom+xml;type=entry".<br />
<br />
Required by Archivematica. <br />
* Authorization: Must include the api key and username assigned by Archivematica.<br />
<br />
Required by SWORD 2.0 protocol:<br />
* In-Progress: Must be set to "true"<br />
<br />
Optional in SWORD 2.0 protocol:<br />
* On-Behalf-Of: not implemented by Archivematica<br />
* Slug: not implemented by Archivematica<br />
<br />
'''Required in Body'''<br />
The Body of the request must be a valid METS Document. The required fields in an Atom Entry Document are:<br />
* LABEL: used as the transfer name<br />
* id: used as an accession id (not yet implemented)<br />
* author: used as the source of acquisition (not yet implemented)<br />
* summary: not implemented yet. Could be used in the future as a description for the Transfer<br />
* updated: should be set to the current timestamp. <br />
<br />
'''Example'''<br />
Example HTTP POST request:<br />
<pre><br />
POST /api/v1/space/96606387-cc70-4b09-b422-a7220606488d/sword/collection/ HTTP/1.1<br />
Host: localhost<br />
Authorization: Archivematica-API api_key="XXXXXXXXXXXXXXXXXXXX", username="timh"<br />
Content-Length: 213<br />
Content-Type: application/atom+xml;type=entry<br />
In-Progress: true<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<METS:mets EXT_VERSION="1.1" OBJID="islandora:72" LABEL="Cinderella"<br />
xmlns:METS="http://www.loc.gov/METS/"<br />
xmlns:xlink="http://www.w3.org/1999/xlink"<br />
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"<br />
xsi:schemaLocation="http://www.loc.gov/METS/ http://www.fedora.info/definitions/1/0/mets-fedora-ext1-1.xsd"><br />
<METS:fileSec><br />
<METS:fileGrp ID="DATASTREAMS"><br />
<METS:fileGrp ID="OBJ"><br />
<METS:file ID="OBJ.0"><br />
<METS:FLocat xlink:title="Cinderella_(1865).pdf" LOCTYPE="URL"<br />
xlink:href="http://localhost:8080/fedora/get/islandora:72/OBJ/2013-08-12T14:46:43.454Z" /><br />
</METS:file><br />
</METS:fileGrp><br />
</METS:fileGrp><br />
</METS:fileSec><br />
</METS:mets><br />
</pre><br />
<br />
Example Response:<br />
<pre><br />
201 Created<br />
Location: http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/<br />
<br />
<entry xmlns="http://www.w3.org/2005/Atom"<br />
xmlns:sword="http://purl.org/net/sword/"<br />
xmlns:dcterms="http://purl.org/dc/terms/"><br />
<br />
<title>Cinderella</title><br />
<id>91d4f258-0050-4914-9d0c-6a74815358d2</id><br />
<updated></updated><br />
<generator uri="https://www.archivematica.org" version="1.0"/><br />
<br />
<summary>A deposit was started.</summary><br />
<sword:treatment>A deposit directory was created and, optionally, asynchronous download of digital objects.</sword:treatment><br />
<br />
<link rel="alternate" href="http://www.swordserver.ac.uk/col1/mydeposit.html"/><br />
<link rel="edit-media" href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/media/"/><br />
<link rel="edit" href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/" /><br />
<link rel="http://purl.org/net/sword/terms/add" href="http://192.168.1.76:8000/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/" /><br />
<link rel="http://purl.org/net/sword/terms/statement" type="application/atom+xml;type=feed"<br />
href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/state/" /><br />
</entry><br />
</pre><br />
<br />
=== Add Files to a Transfer ===<br />
<br />
Posting file metadata (not yet implemented):<br />
* POST a METS file to the SE-IRI, listed below.<br />
* HTTP headers are required similar to Create Transfer call (above).<br />
* Body must include a valid Atom Entry document, that has METS embedded inside it.<br />
<br />
Posts file data:<br />
* It is possible to also POST the actual file to a deposit location's EM-IRI (/api/v1/location/[location UUID]/sword/media/)<br />
* The file should be posted as the request body and the filename specified using the Content-Disposition header (as per RFC 6266): for example "Content-Disposition: Attachment; filename=dog.jpg"<br />
* An MD5 checksum for an uploaded file can be provided via the Content-MD5 header (as per RFC 1544): for example "Content-MD5: Q2hlY2sgSW50ZWdyaXR5IQ=="<br />
* If only an Atom Entry Document is POST'ed, Archivematica will look for uri's in the file StructMap section of the METS file, and attempt to GET each file listed, to include in the Transfer. (not yet implemented)<br />
<br />
=== Finalize a Transfer ===<br />
* POST with no body to the SE-IRI<br />
* set In-Progress HTTP header to : false<br />
* This will tell Archivematica that no further content will be added or removed from the Transfer. <br />
* Archivematica will finish fetching any files that were added previously, and once they have all been downloaded, the Transfer will start through the Archivematica pipeline.<br />
<br />
'''Example'''<br />
<pre><br />
POST http://localhost/api/v1/location/55ce8053-113a-4954-8aa3-fc9771da0bda/sword/ HTTP/1.1<br />
Host: localhost<br />
Authorization: Archivematica-API api_key="XXXXXXXXXXXXXXXXXXXX", username="timh"<br />
Content-Length: 0<br />
Content-Type: application/atom+xml;type=entry<br />
In-Progress: false<br />
</pre><br />
<br />
The response will be HTTP 200/OK or 400/Error (400 if the Transfer was already finalized). If the transfer doesn't exist the response will be HTTP 404.<br />
<br />
If you add a URL parameter specifying the pipeline that should approve the transfer, for example adding "?approval_pipeline=3969b021-87d1-473e-93e0-50c8a2fa8329" to the URL, you can auto-approve the transfer.<br />
<br />
=== Get Status of Transfer ===<br />
To check Status:<br />
<br />
GET the State-IRI<br />
in this example:<br />
<br />
GET http://localhost/api/v1/location/09224ddb-4c7d-404c-9218-2f2e1b5a599e/sword/state/ HTTP/1.1<br />
<br />
response will include:<br />
<pre><atom:feed xmlns:sword="http://purl.org/net/sword/terms/" <br />
xmlns:atom="http://www.w3.org/2005/Atom"><br />
<br />
<atom:category scheme="http://purl.org/net/sword/terms/state"<br />
term="failed"<br />
label="State"><br />
Deposit initiation: Failed<br />
</atom:category><br />
<br />
</atom:feed></pre><br />
the list of possible descriptions is not finalized.<br />
<br />
The state term value will either be "processing" (asynchronous deposit still working), "complete" (ready to be finalized), or "failed" (asynchronous deposit encountered an error).<br />
<br />
== Additional Details == <br />
<br />
=== Transfer Details ===<br />
* redirect to Edit-IRI<br />
* used to get basic info about a Transfer with HTTP GET<br />
* can update basic info using HTTP PUT (not yet implemented)<br />
* can allow deletion with HTTP DELETE<br />
* follows the form: /api/v1/location/[deposit location UUID]/sword/<br />
* example: http://192.168.1.231:8000/api/v1/location/09224ddb-4c7d-404c-9218-2f2e1b5a599e/sword/<br />
<br />
=== EM-IRI ===<br />
* Edit-Media IRI <br />
* used to add new objects to an existing transfer<br />
* follows the form: [archivematica hostname]/api/v2/transfer/[uuid of transfer]/media<br />
* example: http://localhost/api/v2/transfer/1225c695-cfb8-4ebb-aaaa-80da344efa6a/media<br />
<br />
An HTTP POST to the em-iri for a transfer should include a file as the body (may not be supported in v2, return "not supported" HTTP status)<br />
<br />
An HTTP GET should return a list of files in the transfer<br />
<br />
An HTTP DELETE to the em-iri will remove all digital objects from the Transfer. This is a valid operation only while the Transfer is being assembled. Once the Transfer has been finalized, attempting to DELETE will return an error.<br />
<br />
=== Edit-IRI ===<br />
The client can replace the metadata of a resource by performing an HTTP PUT of a new Atom Entry on the Edit-IRI.<br />
<br />
This would be used to update metadata about a transfer, such as the transfer name.<br />
<br />
* example: http://localhost/api/v2/transfer/1225c695-cfb8-4ebb-aaaa-80da344efa6a/edit<br />
<br />
=== SE-IRI ===<br />
* example: http://localhost/api/v2/transfer/add/1225c695-cfb8-4ebb-aaaa-80da344efa6a<br />
<br />
=== State-IRI ===<br />
* used to retrieve status of transfer<br />
* implemented as Atom document<br />
* example: http://localhost/api/v2/transfer/1225c695-cfb8-4ebb-aaaa-80da344efa6a/state<br />
* should be able to subscribe like RSS feed<br />
<br />
== Example session ==<br />
<br />
Below is an example session using curl to manipulate the API. In the example a deposit is created, a file is added to it, and it is finalized.<br />
<br />
NOTE: The SWORD API is in the process of being moved to the storage service. These URLs may not work.<br />
<br />
<pre># create new deposit<br />
curl -v -H "In-Progress: true" --data-binary @mets.xml --request POST http://localhost:8000/api/v1/location/52bbe770-3f96-4493-8d93-ded54c958c51/sword/collection/<br />
# response XML includes endpoints for adding addition files, etc.<br />
<br />
# add another file to the transfer<br />
curl -v -H "Content-Disposition: attachment; filename=joke.jpg" --request POST \<br />
--data-binary "@joke.jpg" \<br />
http://localhost:8000/api/v1/deposit/8e1cba3c-f133-48b2-afef-e42505a7bdc8/sword/media/<br />
<br />
# finalize transfer and approve processing<br />
curl -v -H "In-Progress: false" --request POST http://localhost:8000/api/v1/deposit/8e1cba3c-f133-48b2-afef-e42505a7bdc8/sword/</pre><br />
<br />
You might, at some point, want to list the transfers that have been started. The following curl command will do so.<br />
<br />
<pre>curl -v http://localhost:8000/api/v1/location/52bbe770-3f96-4493-8d93-ded54c958c51/sword/collection/</pre><br />
<br />
If you're working on a transfer and want to list what files are included in it, the following curl command will list them.<br />
<br />
<pre># list files in transfer<br />
curl -v http://192.168.1.231:8000/api/v1/deposit/8e1cba3c-f133-48b2-bdc8/sword/media/</pre><br />
<br />
If you've started a deposit, but want to discard it, you can delete the deposit. The following curl command shows an example.<br />
<br />
<pre>curl -v -XDELETE http://localhost:8000/api/v1/deposit/8e1cba3c-f133-48b2-afef-e42505a7bdc8/sword/</pre><br />
<br />
== Synchronous Deposit Examples ==<br />
<br />
If you wanted to deposit a transfer then immediately finalize it you could use something like the following curl command.<br />
<br />
<pre>curl -v -H "In-Progress: false" --data-binary @mets.xml --request POST http://localhost:8000/api/v1/location/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/</pre><br />
<br />
If you wanted to deposit a transfer, immediately finalize it, and have a pipeline automatically approve it you could use something like the following curl command.<br />
<br />
<pre>curl -v -H "In-Progress: false" --data-binary @mets.xml --request POST http://localhost:8000/api/v1/location/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/?approval_pipeline=41b57f04-9738-43d8-b80e-3fad88c75abc</pre></div>Mcantelonhttps://wiki.archivematica.org/index.php?title=Sword_API&diff=9154Sword API2013-11-25T21:52:15Z<p>Mcantelon: /* Get Status of Transfer */</p>
<hr />
<div><br />
== Overview ==<br />
<br />
One of the 1.1 release features is a sponsored project to integrate Archivematica with Islandora. This integration will be accomplished by creating a [http://swordapp.org Sword] 2.0 API for the Archivematica [https://www.archivematica.org/wiki/Administrator_manual_1.0#Storage_service storage service]. Islandora development work will add functionality to Islandora to use this API to deposit digital objects into Archviematica.<br />
<br />
As described [[Overview|elsewhere]] on this wiki, ''"the primary function of Archivematica is to process digital transfers (accessioned digital objects), turn them into SIPs, apply format policies and create high-quality, repository-independent Archival Information Packages (AIP)"''.<br />
<br />
The Archivematica Sword API allows 3rd party applications to automate the process of creating Transfers. <br />
#Create Transfer - set the name and other metadata about a Transfer<br />
#Populate Transfer - add/edit/update digital objects in a Transfer, and associated metadata<br />
#Finalize Transfer - indicates that the Transfer is ready to start processing.<br />
<br />
After content has been deposited, if users have access to the deposit directory they can also manually manipulate the deposit directory aside from any manipulation using the API.<br />
<br />
Once a Transfer has been created, populated and finalized, Archivematica will begin processing that Transfer.<br />
<br />
== Endpoints ==<br />
<br />
=== Service document ===<br />
<br />
The SWORD service document provides information about the SWORD provider's capacities and lists SWORD collections. Archivematica currently includes one SWORD collection to which SWORD deposits can be made: transfers.<br />
<br />
The SWORD service document endpoint is located at /api/v1/sword.<br />
<br />
=== List existing transfers ===<br />
* HTTP Get to the Collection IRI (defined by default as: /api/v1/space/[space UUID]/sword/collection/)<br />
* Transfers are listed as an Atom feed<br />
* Each Atom feed entry contains an "atom:link" element whose href attribute contains the URL needed to get details about the transfer<br />
* optional filters via get parameters (not yet implemented)<br />
<br />
=== Create a new transfer ===<br />
* used to start a new transfer in Archivematica<br />
* HTTP POST of an Atom Entry Document to the Collection IRI (defined by default as: /api/v1/space/[space UUID]/sword/collection/)<br />
<br />
'''Possible HTTP Response Codes'''<br />
* HTTP 200 OK - transfer already exists (not yet implemented)<br />
* HTTP 201 Created - transfer has been accepted<br />
* HTTP 412 Precondition Failed - required metadata missing or invalid<br />
<br />
Valid requests will receive a Sword Deposit Receipt in the body of the response.<br />
<br />
'''Required HTTP Headers'''<br />
The HTTP POST must include certain specific http headers. <br />
<br />
Required by http 1.1 specification:<br />
* Host: Must be set to archivematica host name.<br />
* Content-Length: Must be set to the length of the atom entry document.<br />
* Content-Type: Must be set to "application/atom+xml;type=entry".<br />
<br />
Required by Archivematica. <br />
* Authorization: Must include the api key and username assigned by Archivematica.<br />
<br />
Required by SWORD 2.0 protocol:<br />
* In-Progress: Must be set to "true"<br />
<br />
Optional in SWORD 2.0 protocol:<br />
* On-Behalf-Of: not implemented by Archivematica<br />
* Slug: not implemented by Archivematica<br />
<br />
'''Required in Body'''<br />
The Body of the request must be a valid METS Document. The required fields in an Atom Entry Document are:<br />
* LABEL: used as the transfer name<br />
* id: used as an accession id (not yet implemented)<br />
* author: used as the source of acquisition (not yet implemented)<br />
* summary: not implemented yet. Could be used in the future as a description for the Transfer<br />
* updated: should be set to the current timestamp. <br />
<br />
'''Example'''<br />
Example HTTP POST request:<br />
<pre><br />
POST /api/v1/space/96606387-cc70-4b09-b422-a7220606488d/sword/collection/ HTTP/1.1<br />
Host: localhost<br />
Authorization: Archivematica-API api_key="XXXXXXXXXXXXXXXXXXXX", username="timh"<br />
Content-Length: 213<br />
Content-Type: application/atom+xml;type=entry<br />
In-Progress: true<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<METS:mets EXT_VERSION="1.1" OBJID="islandora:72" LABEL="Cinderella"<br />
xmlns:METS="http://www.loc.gov/METS/"<br />
xmlns:xlink="http://www.w3.org/1999/xlink"<br />
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"<br />
xsi:schemaLocation="http://www.loc.gov/METS/ http://www.fedora.info/definitions/1/0/mets-fedora-ext1-1.xsd"><br />
<METS:fileSec><br />
<METS:fileGrp ID="DATASTREAMS"><br />
<METS:fileGrp ID="OBJ"><br />
<METS:file ID="OBJ.0"><br />
<METS:FLocat xlink:title="Cinderella_(1865).pdf" LOCTYPE="URL"<br />
xlink:href="http://localhost:8080/fedora/get/islandora:72/OBJ/2013-08-12T14:46:43.454Z" /><br />
</METS:file><br />
</METS:fileGrp><br />
</METS:fileGrp><br />
</METS:fileSec><br />
</METS:mets><br />
</pre><br />
<br />
Example Response:<br />
<pre><br />
201 Created<br />
Location: http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/<br />
<br />
<entry xmlns="http://www.w3.org/2005/Atom"<br />
xmlns:sword="http://purl.org/net/sword/"<br />
xmlns:dcterms="http://purl.org/dc/terms/"><br />
<br />
<title>Cinderella</title><br />
<id>91d4f258-0050-4914-9d0c-6a74815358d2</id><br />
<updated></updated><br />
<generator uri="https://www.archivematica.org" version="1.0"/><br />
<br />
<summary>A deposit was started.</summary><br />
<sword:treatment>A deposit directory was created and, optionally, asynchronous download of digital objects.</sword:treatment><br />
<br />
<link rel="alternate" href="http://www.swordserver.ac.uk/col1/mydeposit.html"/><br />
<link rel="edit-media" href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/media/"/><br />
<link rel="edit" href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/" /><br />
<link rel="http://purl.org/net/sword/terms/add" href="http://192.168.1.76:8000/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/" /><br />
<link rel="http://purl.org/net/sword/terms/statement" type="application/atom+xml;type=feed"<br />
href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/state/" /><br />
</entry><br />
</pre><br />
<br />
=== Add Files to a Transfer ===<br />
<br />
Posting file metadata (not yet implemented):<br />
* POST a METS file to the SE-IRI, listed below.<br />
* HTTP headers are required similar to Create Transfer call (above).<br />
* Body must include a valid Atom Entry document, that has METS embedded inside it.<br />
<br />
Posts file data:<br />
* It is possible to also POST the actual file to a deposit location's EM-IRI (/api/v1/location/[location UUID]/sword/media/)<br />
* The file should be posted as the request body and the filename specified using the Content-Disposition header (as per RFC 6266): for example "Content-Disposition: Attachment; filename=dog.jpg"<br />
* An MD5 checksum for an uploaded file can be provided via the Content-MD5 header (as per RFC 1544): for example "Content-MD5: Q2hlY2sgSW50ZWdyaXR5IQ=="<br />
* If only an Atom Entry Document is POST'ed, Archivematica will look for uri's in the file StructMap section of the METS file, and attempt to GET each file listed, to include in the Transfer. (not yet implemented)<br />
<br />
=== Finalize a Transfer ===<br />
* POST with no body to the SE-IRI<br />
* set In-Progress HTTP header to : false<br />
* This will tell Archivematica that no further content will be added or removed from the Transfer. <br />
* Archivematica will finish fetching any files that were added previously, and once they have all been downloaded, the Transfer will start through the Archivematica pipeline.<br />
<br />
'''Example'''<br />
<pre><br />
POST http://localhost/api/v1/location/55ce8053-113a-4954-8aa3-fc9771da0bda/sword/ HTTP/1.1<br />
Host: localhost<br />
Authorization: Archivematica-API api_key="XXXXXXXXXXXXXXXXXXXX", username="timh"<br />
Content-Length: 0<br />
Content-Type: application/atom+xml;type=entry<br />
In-Progress: false<br />
</pre><br />
<br />
The response will be HTTP 200/OK or 400/Error (400 if the Transfer was already finalized). If the transfer doesn't exist the response will be HTTP 404.<br />
<br />
If you add a URL parameter specifying the pipeline that should approve the transfer, for example adding "?approval_pipeline=3969b021-87d1-473e-93e0-50c8a2fa8329" to the URL, you can auto-approve the transfer.<br />
<br />
=== Get Status of Transfer ===<br />
To check Status:<br />
<br />
GET the State-IRI<br />
in this example:<br />
<br />
GET http://localhost/api/v1/location/09224ddb-4c7d-404c-9218-2f2e1b5a599e/sword/state/ HTTP/1.1<br />
<br />
response will include:<br />
<pre><atom:feed xmlns:sword="http://purl.org/net/sword/terms/" <br />
xmlns:atom="http://www.w3.org/2005/Atom"><br />
<br />
<atom:category scheme="http://purl.org/net/sword/terms/state"<br />
term="failed"<br />
label="State"><br />
Deposit initiation: Failed<br />
</atom:category><br />
<br />
</atom:feed></pre><br />
the list of possible descriptions is not finalized.<br />
<br />
The state term value will either be "processing" (asynchronous deposit still working), "complete" (ready to be finalized), or "failed" (asynchronous deposit encountered an error).<br />
<br />
== Additional Details == <br />
<br />
=== Transfer Details ===<br />
* redirect to Edit-IRI<br />
* used to get basic info about a Transfer with HTTP GET<br />
* can update basic info using HTTP PUT (not yet implemented)<br />
* can allow deletion with HTTP DELETE<br />
* follows the form: [archivematica hostname]/api/v2/transfer/[uuid of transfer]<br />
* example: http://localhost/api/v2/transfer/1225c695-cfb8-4ebb-aaaa-80da344efa6a<br />
<br />
=== EM-IRI ===<br />
* Edit-Media IRI <br />
* used to add new objects to an existing transfer<br />
* follows the form: [archivematica hostname]/api/v2/transfer/[uuid of transfer]/media<br />
* example: http://localhost/api/v2/transfer/1225c695-cfb8-4ebb-aaaa-80da344efa6a/media<br />
<br />
An HTTP POST to the em-iri for a transfer should include a file as the body (may not be supported in v2, return "not supported" HTTP status)<br />
<br />
An HTTP GET should return a list of files in the transfer<br />
<br />
An HTTP DELETE to the em-iri will remove all digital objects from the Transfer. This is a valid operation only while the Transfer is being assembled. Once the Transfer has been finalized, attempting to DELETE will return an error.<br />
<br />
=== Edit-IRI ===<br />
The client can replace the metadata of a resource by performing an HTTP PUT of a new Atom Entry on the Edit-IRI.<br />
<br />
This would be used to update metadata about a transfer, such as the transfer name.<br />
<br />
* example: http://localhost/api/v2/transfer/1225c695-cfb8-4ebb-aaaa-80da344efa6a/edit<br />
<br />
=== SE-IRI ===<br />
* example: http://localhost/api/v2/transfer/add/1225c695-cfb8-4ebb-aaaa-80da344efa6a<br />
<br />
=== State-IRI ===<br />
* used to retrieve status of transfer<br />
* implemented as Atom document<br />
* example: http://localhost/api/v2/transfer/1225c695-cfb8-4ebb-aaaa-80da344efa6a/state<br />
* should be able to subscribe like RSS feed<br />
<br />
== Example session ==<br />
<br />
Below is an example session using curl to manipulate the API. In the example a deposit is created, a file is added to it, and it is finalized.<br />
<br />
NOTE: The SWORD API is in the process of being moved to the storage service. These URLs may not work.<br />
<br />
<pre># create new deposit<br />
curl -v -H "In-Progress: true" --data-binary @mets.xml --request POST http://localhost:8000/api/v1/location/52bbe770-3f96-4493-8d93-ded54c958c51/sword/collection/<br />
# response XML includes endpoints for adding addition files, etc.<br />
<br />
# add another file to the transfer<br />
curl -v -H "Content-Disposition: attachment; filename=joke.jpg" --request POST \<br />
--data-binary "@joke.jpg" \<br />
http://localhost:8000/api/v1/deposit/8e1cba3c-f133-48b2-afef-e42505a7bdc8/sword/media/<br />
<br />
# finalize transfer and approve processing<br />
curl -v -H "In-Progress: false" --request POST http://localhost:8000/api/v1/deposit/8e1cba3c-f133-48b2-afef-e42505a7bdc8/sword/</pre><br />
<br />
You might, at some point, want to list the transfers that have been started. The following curl command will do so.<br />
<br />
<pre>curl -v http://localhost:8000/api/v1/location/52bbe770-3f96-4493-8d93-ded54c958c51/sword/collection/</pre><br />
<br />
If you're working on a transfer and want to list what files are included in it, the following curl command will list them.<br />
<br />
<pre># list files in transfer<br />
curl -v http://192.168.1.231:8000/api/v1/deposit/8e1cba3c-f133-48b2-bdc8/sword/media/</pre><br />
<br />
If you've started a deposit, but want to discard it, you can delete the deposit. The following curl command shows an example.<br />
<br />
<pre>curl -v -XDELETE http://localhost:8000/api/v1/deposit/8e1cba3c-f133-48b2-afef-e42505a7bdc8/sword/</pre><br />
<br />
== Synchronous Deposit Examples ==<br />
<br />
If you wanted to deposit a transfer then immediately finalize it you could use something like the following curl command.<br />
<br />
<pre>curl -v -H "In-Progress: false" --data-binary @mets.xml --request POST http://localhost:8000/api/v1/location/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/</pre><br />
<br />
If you wanted to deposit a transfer, immediately finalize it, and have a pipeline automatically approve it you could use something like the following curl command.<br />
<br />
<pre>curl -v -H "In-Progress: false" --data-binary @mets.xml --request POST http://localhost:8000/api/v1/location/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/?approval_pipeline=41b57f04-9738-43d8-b80e-3fad88c75abc</pre></div>Mcantelonhttps://wiki.archivematica.org/index.php?title=Sword_API&diff=9153Sword API2013-11-25T21:48:13Z<p>Mcantelon: /* Finalize a Transfer */</p>
<hr />
<div><br />
== Overview ==<br />
<br />
One of the 1.1 release features is a sponsored project to integrate Archivematica with Islandora. This integration will be accomplished by creating a [http://swordapp.org Sword] 2.0 API for the Archivematica [https://www.archivematica.org/wiki/Administrator_manual_1.0#Storage_service storage service]. Islandora development work will add functionality to Islandora to use this API to deposit digital objects into Archviematica.<br />
<br />
As described [[Overview|elsewhere]] on this wiki, ''"the primary function of Archivematica is to process digital transfers (accessioned digital objects), turn them into SIPs, apply format policies and create high-quality, repository-independent Archival Information Packages (AIP)"''.<br />
<br />
The Archivematica Sword API allows 3rd party applications to automate the process of creating Transfers. <br />
#Create Transfer - set the name and other metadata about a Transfer<br />
#Populate Transfer - add/edit/update digital objects in a Transfer, and associated metadata<br />
#Finalize Transfer - indicates that the Transfer is ready to start processing.<br />
<br />
After content has been deposited, if users have access to the deposit directory they can also manually manipulate the deposit directory aside from any manipulation using the API.<br />
<br />
Once a Transfer has been created, populated and finalized, Archivematica will begin processing that Transfer.<br />
<br />
== Endpoints ==<br />
<br />
=== Service document ===<br />
<br />
The SWORD service document provides information about the SWORD provider's capacities and lists SWORD collections. Archivematica currently includes one SWORD collection to which SWORD deposits can be made: transfers.<br />
<br />
The SWORD service document endpoint is located at /api/v1/sword.<br />
<br />
=== List existing transfers ===<br />
* HTTP Get to the Collection IRI (defined by default as: /api/v1/space/[space UUID]/sword/collection/)<br />
* Transfers are listed as an Atom feed<br />
* Each Atom feed entry contains an "atom:link" element whose href attribute contains the URL needed to get details about the transfer<br />
* optional filters via get parameters (not yet implemented)<br />
<br />
=== Create a new transfer ===<br />
* used to start a new transfer in Archivematica<br />
* HTTP POST of an Atom Entry Document to the Collection IRI (defined by default as: /api/v1/space/[space UUID]/sword/collection/)<br />
<br />
'''Possible HTTP Response Codes'''<br />
* HTTP 200 OK - transfer already exists (not yet implemented)<br />
* HTTP 201 Created - transfer has been accepted<br />
* HTTP 412 Precondition Failed - required metadata missing or invalid<br />
<br />
Valid requests will receive a Sword Deposit Receipt in the body of the response.<br />
<br />
'''Required HTTP Headers'''<br />
The HTTP POST must include certain specific http headers. <br />
<br />
Required by http 1.1 specification:<br />
* Host: Must be set to archivematica host name.<br />
* Content-Length: Must be set to the length of the atom entry document.<br />
* Content-Type: Must be set to "application/atom+xml;type=entry".<br />
<br />
Required by Archivematica. <br />
* Authorization: Must include the api key and username assigned by Archivematica.<br />
<br />
Required by SWORD 2.0 protocol:<br />
* In-Progress: Must be set to "true"<br />
<br />
Optional in SWORD 2.0 protocol:<br />
* On-Behalf-Of: not implemented by Archivematica<br />
* Slug: not implemented by Archivematica<br />
<br />
'''Required in Body'''<br />
The Body of the request must be a valid METS Document. The required fields in an Atom Entry Document are:<br />
* LABEL: used as the transfer name<br />
* id: used as an accession id (not yet implemented)<br />
* author: used as the source of acquisition (not yet implemented)<br />
* summary: not implemented yet. Could be used in the future as a description for the Transfer<br />
* updated: should be set to the current timestamp. <br />
<br />
'''Example'''<br />
Example HTTP POST request:<br />
<pre><br />
POST /api/v1/space/96606387-cc70-4b09-b422-a7220606488d/sword/collection/ HTTP/1.1<br />
Host: localhost<br />
Authorization: Archivematica-API api_key="XXXXXXXXXXXXXXXXXXXX", username="timh"<br />
Content-Length: 213<br />
Content-Type: application/atom+xml;type=entry<br />
In-Progress: true<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<METS:mets EXT_VERSION="1.1" OBJID="islandora:72" LABEL="Cinderella"<br />
xmlns:METS="http://www.loc.gov/METS/"<br />
xmlns:xlink="http://www.w3.org/1999/xlink"<br />
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"<br />
xsi:schemaLocation="http://www.loc.gov/METS/ http://www.fedora.info/definitions/1/0/mets-fedora-ext1-1.xsd"><br />
<METS:fileSec><br />
<METS:fileGrp ID="DATASTREAMS"><br />
<METS:fileGrp ID="OBJ"><br />
<METS:file ID="OBJ.0"><br />
<METS:FLocat xlink:title="Cinderella_(1865).pdf" LOCTYPE="URL"<br />
xlink:href="http://localhost:8080/fedora/get/islandora:72/OBJ/2013-08-12T14:46:43.454Z" /><br />
</METS:file><br />
</METS:fileGrp><br />
</METS:fileGrp><br />
</METS:fileSec><br />
</METS:mets><br />
</pre><br />
<br />
Example Response:<br />
<pre><br />
201 Created<br />
Location: http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/<br />
<br />
<entry xmlns="http://www.w3.org/2005/Atom"<br />
xmlns:sword="http://purl.org/net/sword/"<br />
xmlns:dcterms="http://purl.org/dc/terms/"><br />
<br />
<title>Cinderella</title><br />
<id>91d4f258-0050-4914-9d0c-6a74815358d2</id><br />
<updated></updated><br />
<generator uri="https://www.archivematica.org" version="1.0"/><br />
<br />
<summary>A deposit was started.</summary><br />
<sword:treatment>A deposit directory was created and, optionally, asynchronous download of digital objects.</sword:treatment><br />
<br />
<link rel="alternate" href="http://www.swordserver.ac.uk/col1/mydeposit.html"/><br />
<link rel="edit-media" href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/media/"/><br />
<link rel="edit" href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/" /><br />
<link rel="http://purl.org/net/sword/terms/add" href="http://192.168.1.76:8000/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/" /><br />
<link rel="http://purl.org/net/sword/terms/statement" type="application/atom+xml;type=feed"<br />
href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/state/" /><br />
</entry><br />
</pre><br />
<br />
=== Add Files to a Transfer ===<br />
<br />
Posting file metadata (not yet implemented):<br />
* POST a METS file to the SE-IRI, listed below.<br />
* HTTP headers are required similar to Create Transfer call (above).<br />
* Body must include a valid Atom Entry document, that has METS embedded inside it.<br />
<br />
Posts file data:<br />
* It is possible to also POST the actual file to a deposit location's EM-IRI (/api/v1/location/[location UUID]/sword/media/)<br />
* The file should be posted as the request body and the filename specified using the Content-Disposition header (as per RFC 6266): for example "Content-Disposition: Attachment; filename=dog.jpg"<br />
* An MD5 checksum for an uploaded file can be provided via the Content-MD5 header (as per RFC 1544): for example "Content-MD5: Q2hlY2sgSW50ZWdyaXR5IQ=="<br />
* If only an Atom Entry Document is POST'ed, Archivematica will look for uri's in the file StructMap section of the METS file, and attempt to GET each file listed, to include in the Transfer. (not yet implemented)<br />
<br />
=== Finalize a Transfer ===<br />
* POST with no body to the SE-IRI<br />
* set In-Progress HTTP header to : false<br />
* This will tell Archivematica that no further content will be added or removed from the Transfer. <br />
* Archivematica will finish fetching any files that were added previously, and once they have all been downloaded, the Transfer will start through the Archivematica pipeline.<br />
<br />
'''Example'''<br />
<pre><br />
POST http://localhost/api/v1/location/55ce8053-113a-4954-8aa3-fc9771da0bda/sword/ HTTP/1.1<br />
Host: localhost<br />
Authorization: Archivematica-API api_key="XXXXXXXXXXXXXXXXXXXX", username="timh"<br />
Content-Length: 0<br />
Content-Type: application/atom+xml;type=entry<br />
In-Progress: false<br />
</pre><br />
<br />
The response will be HTTP 200/OK or 400/Error (400 if the Transfer was already finalized). If the transfer doesn't exist the response will be HTTP 404.<br />
<br />
If you add a URL parameter specifying the pipeline that should approve the transfer, for example adding "?approval_pipeline=3969b021-87d1-473e-93e0-50c8a2fa8329" to the URL, you can auto-approve the transfer.<br />
<br />
=== Get Status of Transfer ===<br />
To check Status:<br />
<br />
GET the State-IRI<br />
in this example:<br />
<br />
GET http://localhost/api/v2/transfer/sword/1225c695-cfb8-4ebb-aaaa-80da344efa6a/state HTTP/1.1<br />
<br />
response will include:<br />
<pre><atom:feed xmlns:sword="http://purl.org/net/sword/terms/" <br />
xmlns:atom="http://www.w3.org/2005/Atom"><br />
<br />
<atom:category scheme="http://purl.org/net/sword/terms/state"<br />
term="failed"<br />
label="State"><br />
Deposit initiation: Failed<br />
</atom:category><br />
<br />
</atom:feed></pre><br />
the list of possible descriptions is not finalized.<br />
<br />
The state term value will either be "processing" (asynchronous deposit still working), "complete" (ready to be finalized), or "failed" (asynchronous deposit encountered an error).<br />
<br />
== Additional Details == <br />
<br />
=== Transfer Details ===<br />
* redirect to Edit-IRI<br />
* used to get basic info about a Transfer with HTTP GET<br />
* can update basic info using HTTP PUT (not yet implemented)<br />
* can allow deletion with HTTP DELETE<br />
* follows the form: [archivematica hostname]/api/v2/transfer/[uuid of transfer]<br />
* example: http://localhost/api/v2/transfer/1225c695-cfb8-4ebb-aaaa-80da344efa6a<br />
<br />
=== EM-IRI ===<br />
* Edit-Media IRI <br />
* used to add new objects to an existing transfer<br />
* follows the form: [archivematica hostname]/api/v2/transfer/[uuid of transfer]/media<br />
* example: http://localhost/api/v2/transfer/1225c695-cfb8-4ebb-aaaa-80da344efa6a/media<br />
<br />
An HTTP POST to the em-iri for a transfer should include a file as the body (may not be supported in v2, return "not supported" HTTP status)<br />
<br />
An HTTP GET should return a list of files in the transfer<br />
<br />
An HTTP DELETE to the em-iri will remove all digital objects from the Transfer. This is a valid operation only while the Transfer is being assembled. Once the Transfer has been finalized, attempting to DELETE will return an error.<br />
<br />
=== Edit-IRI ===<br />
The client can replace the metadata of a resource by performing an HTTP PUT of a new Atom Entry on the Edit-IRI.<br />
<br />
This would be used to update metadata about a transfer, such as the transfer name.<br />
<br />
* example: http://localhost/api/v2/transfer/1225c695-cfb8-4ebb-aaaa-80da344efa6a/edit<br />
<br />
=== SE-IRI ===<br />
* example: http://localhost/api/v2/transfer/add/1225c695-cfb8-4ebb-aaaa-80da344efa6a<br />
<br />
=== State-IRI ===<br />
* used to retrieve status of transfer<br />
* implemented as Atom document<br />
* example: http://localhost/api/v2/transfer/1225c695-cfb8-4ebb-aaaa-80da344efa6a/state<br />
* should be able to subscribe like RSS feed<br />
<br />
== Example session ==<br />
<br />
Below is an example session using curl to manipulate the API. In the example a deposit is created, a file is added to it, and it is finalized.<br />
<br />
NOTE: The SWORD API is in the process of being moved to the storage service. These URLs may not work.<br />
<br />
<pre># create new deposit<br />
curl -v -H "In-Progress: true" --data-binary @mets.xml --request POST http://localhost:8000/api/v1/location/52bbe770-3f96-4493-8d93-ded54c958c51/sword/collection/<br />
# response XML includes endpoints for adding addition files, etc.<br />
<br />
# add another file to the transfer<br />
curl -v -H "Content-Disposition: attachment; filename=joke.jpg" --request POST \<br />
--data-binary "@joke.jpg" \<br />
http://localhost:8000/api/v1/deposit/8e1cba3c-f133-48b2-afef-e42505a7bdc8/sword/media/<br />
<br />
# finalize transfer and approve processing<br />
curl -v -H "In-Progress: false" --request POST http://localhost:8000/api/v1/deposit/8e1cba3c-f133-48b2-afef-e42505a7bdc8/sword/</pre><br />
<br />
You might, at some point, want to list the transfers that have been started. The following curl command will do so.<br />
<br />
<pre>curl -v http://localhost:8000/api/v1/location/52bbe770-3f96-4493-8d93-ded54c958c51/sword/collection/</pre><br />
<br />
If you're working on a transfer and want to list what files are included in it, the following curl command will list them.<br />
<br />
<pre># list files in transfer<br />
curl -v http://192.168.1.231:8000/api/v1/deposit/8e1cba3c-f133-48b2-bdc8/sword/media/</pre><br />
<br />
If you've started a deposit, but want to discard it, you can delete the deposit. The following curl command shows an example.<br />
<br />
<pre>curl -v -XDELETE http://localhost:8000/api/v1/deposit/8e1cba3c-f133-48b2-afef-e42505a7bdc8/sword/</pre><br />
<br />
== Synchronous Deposit Examples ==<br />
<br />
If you wanted to deposit a transfer then immediately finalize it you could use something like the following curl command.<br />
<br />
<pre>curl -v -H "In-Progress: false" --data-binary @mets.xml --request POST http://localhost:8000/api/v1/location/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/</pre><br />
<br />
If you wanted to deposit a transfer, immediately finalize it, and have a pipeline automatically approve it you could use something like the following curl command.<br />
<br />
<pre>curl -v -H "In-Progress: false" --data-binary @mets.xml --request POST http://localhost:8000/api/v1/location/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/?approval_pipeline=41b57f04-9738-43d8-b80e-3fad88c75abc</pre></div>Mcantelonhttps://wiki.archivematica.org/index.php?title=Sword_API&diff=9152Sword API2013-11-25T21:47:18Z<p>Mcantelon: /* Finalize a Transfer */</p>
<hr />
<div><br />
== Overview ==<br />
<br />
One of the 1.1 release features is a sponsored project to integrate Archivematica with Islandora. This integration will be accomplished by creating a [http://swordapp.org Sword] 2.0 API for the Archivematica [https://www.archivematica.org/wiki/Administrator_manual_1.0#Storage_service storage service]. Islandora development work will add functionality to Islandora to use this API to deposit digital objects into Archviematica.<br />
<br />
As described [[Overview|elsewhere]] on this wiki, ''"the primary function of Archivematica is to process digital transfers (accessioned digital objects), turn them into SIPs, apply format policies and create high-quality, repository-independent Archival Information Packages (AIP)"''.<br />
<br />
The Archivematica Sword API allows 3rd party applications to automate the process of creating Transfers. <br />
#Create Transfer - set the name and other metadata about a Transfer<br />
#Populate Transfer - add/edit/update digital objects in a Transfer, and associated metadata<br />
#Finalize Transfer - indicates that the Transfer is ready to start processing.<br />
<br />
After content has been deposited, if users have access to the deposit directory they can also manually manipulate the deposit directory aside from any manipulation using the API.<br />
<br />
Once a Transfer has been created, populated and finalized, Archivematica will begin processing that Transfer.<br />
<br />
== Endpoints ==<br />
<br />
=== Service document ===<br />
<br />
The SWORD service document provides information about the SWORD provider's capacities and lists SWORD collections. Archivematica currently includes one SWORD collection to which SWORD deposits can be made: transfers.<br />
<br />
The SWORD service document endpoint is located at /api/v1/sword.<br />
<br />
=== List existing transfers ===<br />
* HTTP Get to the Collection IRI (defined by default as: /api/v1/space/[space UUID]/sword/collection/)<br />
* Transfers are listed as an Atom feed<br />
* Each Atom feed entry contains an "atom:link" element whose href attribute contains the URL needed to get details about the transfer<br />
* optional filters via get parameters (not yet implemented)<br />
<br />
=== Create a new transfer ===<br />
* used to start a new transfer in Archivematica<br />
* HTTP POST of an Atom Entry Document to the Collection IRI (defined by default as: /api/v1/space/[space UUID]/sword/collection/)<br />
<br />
'''Possible HTTP Response Codes'''<br />
* HTTP 200 OK - transfer already exists (not yet implemented)<br />
* HTTP 201 Created - transfer has been accepted<br />
* HTTP 412 Precondition Failed - required metadata missing or invalid<br />
<br />
Valid requests will receive a Sword Deposit Receipt in the body of the response.<br />
<br />
'''Required HTTP Headers'''<br />
The HTTP POST must include certain specific http headers. <br />
<br />
Required by http 1.1 specification:<br />
* Host: Must be set to archivematica host name.<br />
* Content-Length: Must be set to the length of the atom entry document.<br />
* Content-Type: Must be set to "application/atom+xml;type=entry".<br />
<br />
Required by Archivematica. <br />
* Authorization: Must include the api key and username assigned by Archivematica.<br />
<br />
Required by SWORD 2.0 protocol:<br />
* In-Progress: Must be set to "true"<br />
<br />
Optional in SWORD 2.0 protocol:<br />
* On-Behalf-Of: not implemented by Archivematica<br />
* Slug: not implemented by Archivematica<br />
<br />
'''Required in Body'''<br />
The Body of the request must be a valid METS Document. The required fields in an Atom Entry Document are:<br />
* LABEL: used as the transfer name<br />
* id: used as an accession id (not yet implemented)<br />
* author: used as the source of acquisition (not yet implemented)<br />
* summary: not implemented yet. Could be used in the future as a description for the Transfer<br />
* updated: should be set to the current timestamp. <br />
<br />
'''Example'''<br />
Example HTTP POST request:<br />
<pre><br />
POST /api/v1/space/96606387-cc70-4b09-b422-a7220606488d/sword/collection/ HTTP/1.1<br />
Host: localhost<br />
Authorization: Archivematica-API api_key="XXXXXXXXXXXXXXXXXXXX", username="timh"<br />
Content-Length: 213<br />
Content-Type: application/atom+xml;type=entry<br />
In-Progress: true<br />
<br />
<?xml version="1.0" encoding="UTF-8"?><br />
<METS:mets EXT_VERSION="1.1" OBJID="islandora:72" LABEL="Cinderella"<br />
xmlns:METS="http://www.loc.gov/METS/"<br />
xmlns:xlink="http://www.w3.org/1999/xlink"<br />
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"<br />
xsi:schemaLocation="http://www.loc.gov/METS/ http://www.fedora.info/definitions/1/0/mets-fedora-ext1-1.xsd"><br />
<METS:fileSec><br />
<METS:fileGrp ID="DATASTREAMS"><br />
<METS:fileGrp ID="OBJ"><br />
<METS:file ID="OBJ.0"><br />
<METS:FLocat xlink:title="Cinderella_(1865).pdf" LOCTYPE="URL"<br />
xlink:href="http://localhost:8080/fedora/get/islandora:72/OBJ/2013-08-12T14:46:43.454Z" /><br />
</METS:file><br />
</METS:fileGrp><br />
</METS:fileGrp><br />
</METS:fileSec><br />
</METS:mets><br />
</pre><br />
<br />
Example Response:<br />
<pre><br />
201 Created<br />
Location: http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/<br />
<br />
<entry xmlns="http://www.w3.org/2005/Atom"<br />
xmlns:sword="http://purl.org/net/sword/"<br />
xmlns:dcterms="http://purl.org/dc/terms/"><br />
<br />
<title>Cinderella</title><br />
<id>91d4f258-0050-4914-9d0c-6a74815358d2</id><br />
<updated></updated><br />
<generator uri="https://www.archivematica.org" version="1.0"/><br />
<br />
<summary>A deposit was started.</summary><br />
<sword:treatment>A deposit directory was created and, optionally, asynchronous download of digital objects.</sword:treatment><br />
<br />
<link rel="alternate" href="http://www.swordserver.ac.uk/col1/mydeposit.html"/><br />
<link rel="edit-media" href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/media/"/><br />
<link rel="edit" href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/" /><br />
<link rel="http://purl.org/net/sword/terms/add" href="http://192.168.1.76:8000/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/" /><br />
<link rel="http://purl.org/net/sword/terms/statement" type="application/atom+xml;type=feed"<br />
href="http://localhost/api/v1/location/91d4f258-0050-4914-9d0c-6a74815358d2/sword/state/" /><br />
</entry><br />
</pre><br />
<br />
=== Add Files to a Transfer ===<br />
<br />
Posting file metadata (not yet implemented):<br />
* POST a METS file to the SE-IRI, listed below.<br />
* HTTP headers are required similar to Create Transfer call (above).<br />
* Body must include a valid Atom Entry document, that has METS embedded inside it.<br />
<br />
Posts file data:<br />
* It is possible to also POST the actual file to a deposit location's EM-IRI (/api/v1/location/[location UUID]/sword/media/)<br />
* The file should be posted as the request body and the filename specified using the Content-Disposition header (as per RFC 6266): for example "Content-Disposition: Attachment; filename=dog.jpg"<br />
* An MD5 checksum for an uploaded file can be provided via the Content-MD5 header (as per RFC 1544): for example "Content-MD5: Q2hlY2sgSW50ZWdyaXR5IQ=="<br />
* If only an Atom Entry Document is POST'ed, Archivematica will look for uri's in the file StructMap section of the METS file, and attempt to GET each file listed, to include in the Transfer. (not yet implemented)<br />
<br />
=== Finalize a Transfer ===<br />
* POST with no body to the SE-IRI<br />
* set In-Progress HTTP header to : false<br />
* This will tell Archivematica that no further content will be added or removed from the Transfer. <br />
* Archivematica will finish fetching any files that were added previously, and once they have all been downloaded, the Transfer will start through the Archivematica pipeline.<br />
<br />
'''Example'''<br />
<pre><br />
POST http://localhost/api/v1/location/55ce8053-113a-4954-8aa3-fc9771da0bda/sword/ HTTP/1.1<br />
Host: localhost<br />
Authorization: Archivematica-API api_key="XXXXXXXXXXXXXXXXXXXX", username="timh"<br />
Content-Length: 0<br />
Content-Type: application/atom+xml;type=entry<br />
In-Progress: false<br />
</pre><br />
<br />
The response will be HTTP 200/OK or 400/Error (400 if the Transfer was already finalized). If the transfer doesn't exist the response will be HTTP 404.<br />
<br />
=== Get Status of Transfer ===<br />
To check Status:<br />
<br />
GET the State-IRI<br />
in this example:<br />
<br />
GET http://localhost/api/v2/transfer/sword/1225c695-cfb8-4ebb-aaaa-80da344efa6a/state HTTP/1.1<br />
<br />
response will include:<br />
<pre><atom:feed xmlns:sword="http://purl.org/net/sword/terms/" <br />
xmlns:atom="http://www.w3.org/2005/Atom"><br />
<br />
<atom:category scheme="http://purl.org/net/sword/terms/state"<br />
term="failed"<br />
label="State"><br />
Deposit initiation: Failed<br />
</atom:category><br />
<br />
</atom:feed></pre><br />
the list of possible descriptions is not finalized.<br />
<br />
The state term value will either be "processing" (asynchronous deposit still working), "complete" (ready to be finalized), or "failed" (asynchronous deposit encountered an error).<br />
<br />
== Additional Details == <br />
<br />
=== Transfer Details ===<br />
* redirect to Edit-IRI<br />
* used to get basic info about a Transfer with HTTP GET<br />
* can update basic info using HTTP PUT (not yet implemented)<br />
* can allow deletion with HTTP DELETE<br />
* follows the form: [archivematica hostname]/api/v2/transfer/[uuid of transfer]<br />
* example: http://localhost/api/v2/transfer/1225c695-cfb8-4ebb-aaaa-80da344efa6a<br />
<br />
=== EM-IRI ===<br />
* Edit-Media IRI <br />
* used to add new objects to an existing transfer<br />
* follows the form: [archivematica hostname]/api/v2/transfer/[uuid of transfer]/media<br />
* example: http://localhost/api/v2/transfer/1225c695-cfb8-4ebb-aaaa-80da344efa6a/media<br />
<br />
An HTTP POST to the em-iri for a transfer should include a file as the body (may not be supported in v2, return "not supported" HTTP status)<br />
<br />
An HTTP GET should return a list of files in the transfer<br />
<br />
An HTTP DELETE to the em-iri will remove all digital objects from the Transfer. This is a valid operation only while the Transfer is being assembled. Once the Transfer has been finalized, attempting to DELETE will return an error.<br />
<br />
=== Edit-IRI ===<br />
The client can replace the metadata of a resource by performing an HTTP PUT of a new Atom Entry on the Edit-IRI.<br />
<br />
This would be used to update metadata about a transfer, such as the transfer name.<br />
<br />
* example: http://localhost/api/v2/transfer/1225c695-cfb8-4ebb-aaaa-80da344efa6a/edit<br />
<br />
=== SE-IRI ===<br />
* example: http://localhost/api/v2/transfer/add/1225c695-cfb8-4ebb-aaaa-80da344efa6a<br />
<br />
=== State-IRI ===<br />
* used to retrieve status of transfer<br />
* implemented as Atom document<br />
* example: http://localhost/api/v2/transfer/1225c695-cfb8-4ebb-aaaa-80da344efa6a/state<br />
* should be able to subscribe like RSS feed<br />
<br />
== Example session ==<br />
<br />
Below is an example session using curl to manipulate the API. In the example a deposit is created, a file is added to it, and it is finalized.<br />
<br />
NOTE: The SWORD API is in the process of being moved to the storage service. These URLs may not work.<br />
<br />
<pre># create new deposit<br />
curl -v -H "In-Progress: true" --data-binary @mets.xml --request POST http://localhost:8000/api/v1/location/52bbe770-3f96-4493-8d93-ded54c958c51/sword/collection/<br />
# response XML includes endpoints for adding addition files, etc.<br />
<br />
# add another file to the transfer<br />
curl -v -H "Content-Disposition: attachment; filename=joke.jpg" --request POST \<br />
--data-binary "@joke.jpg" \<br />
http://localhost:8000/api/v1/deposit/8e1cba3c-f133-48b2-afef-e42505a7bdc8/sword/media/<br />
<br />
# finalize transfer and approve processing<br />
curl -v -H "In-Progress: false" --request POST http://localhost:8000/api/v1/deposit/8e1cba3c-f133-48b2-afef-e42505a7bdc8/sword/</pre><br />
<br />
You might, at some point, want to list the transfers that have been started. The following curl command will do so.<br />
<br />
<pre>curl -v http://localhost:8000/api/v1/location/52bbe770-3f96-4493-8d93-ded54c958c51/sword/collection/</pre><br />
<br />
If you're working on a transfer and want to list what files are included in it, the following curl command will list them.<br />
<br />
<pre># list files in transfer<br />
curl -v http://192.168.1.231:8000/api/v1/deposit/8e1cba3c-f133-48b2-bdc8/sword/media/</pre><br />
<br />
If you've started a deposit, but want to discard it, you can delete the deposit. The following curl command shows an example.<br />
<br />
<pre>curl -v -XDELETE http://localhost:8000/api/v1/deposit/8e1cba3c-f133-48b2-afef-e42505a7bdc8/sword/</pre><br />
<br />
== Synchronous Deposit Examples ==<br />
<br />
If you wanted to deposit a transfer then immediately finalize it you could use something like the following curl command.<br />
<br />
<pre>curl -v -H "In-Progress: false" --data-binary @mets.xml --request POST http://localhost:8000/api/v1/location/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/</pre><br />
<br />
If you wanted to deposit a transfer, immediately finalize it, and have a pipeline automatically approve it you could use something like the following curl command.<br />
<br />
<pre>curl -v -H "In-Progress: false" --data-binary @mets.xml --request POST http://localhost:8000/api/v1/location/c0bee7c8-3e9b-41e3-8600-ee9b2c475da2/sword/collection/?approval_pipeline=41b57f04-9738-43d8-b80e-3fad88c75abc</pre></div>Mcantelon