Editing API:EPrints/Apache/CRUD (section)

==DESCRIPTION==
The CRUD (Create/Read/Update/Delete) module provides the Web API for  manipulating content on the server. The API is an AtomPub  implementation that exposes Import and Export plugins via simple URLs and HTTP content type negotiation.

You should use the &lt;link&gt; entries in the repository's home page to  locate the CRUD endpoint, as they may change in the future:

  &lt;link rel="Sword" href="https://myrepo/sword-app/servicedocument" /&gt;
  &lt;link rel="SwordDeposit" href="https://myrepo/id/contents" /&gt;
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<span style='display:none'>User Comments</span>
<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
</div>
<!-- Pod2Wiki=head_examples -->
===Examples===
Create a new eprint based on a single file:

  curl -X POST \
    -i \
    -u user:password \
    -d 'Hello, World!' \
    -H 'Content-Type: text/plain' \
    https://myrepo/id/contents
  
  HTTP/1.1 201 Created
  Content-Type: application/atom+xml;charset=utf-8
  ...
  
Add a file to an existing eprint:

  curl -X POST \
    -i \
    -u user:password \
    -d 'Hello, World!' \
    -H 'Content-Disposition: attachment; filename=hello.txt' \
    -H 'Content-Type: text/plain' \
    https://myrepo/id/eprint/23/contents
  
  HTTP/1.1 201 Created
  Content-Type: application/atom+xml;charset=utf-8
  ...
  
Get an eprint's metadata in Atom XML:

  curl -X GET \
    -i \
    -u user:password \
    -H 'Accept: application/atom+xml' \
    https://myrepo/id/eprint/23
  
  HTTP/1.1 200 OK
  Content-Type: application/atom+xml;charset=utf-8
  ...
  
Get the list of contents (documents) of an eprint in Atom XML:

  curl -X GET \
    -i \
    -u user:password \
    -H 'Accept: application/atom+xml' \
    https://myrepo/id/eprint/23/contents
  
  HTTP/1.1 200 OK
  Content-Type: application/atom+xml;charset=utf-8
  ...
  
You can find more examples in the ''tests/84_sword.t'' unit test.

<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<span style='display:none'>User Comments</span>
<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
</div>
<!-- Pod2Wiki=head_uri_layout -->
===URI Layout===
These URIs are relative to your EPrints HTTP/HTTPs root.

<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<span style='display:none'>User Comments</span>
<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
</div>
<!-- Pod2Wiki=item_id_contents_get_head_options_post -->
====/id/contents GET,HEAD,OPTIONS,POST====

Requires authentication.

<tt>GET</tt> a list of the eprints owned by the user. <tt>POST</tt> to create a new EPrint object.

<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<span style='display:none'>User Comments</span>
<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
</div>
<!-- Pod2Wiki=item_id_datasetid_dataobjid_delete_get_head_options_put -->
====/id/[datasetid]/[dataobjid] DELETE,GET,HEAD,OPTIONS,PUT====

Requires authentication depending on user's privileges and object visibility.

<tt>GET</tt> an object's metadata or, for {{API:PodLink|file=EPrints/DataObj/File|package_name=EPrints::DataObj::File|section=|text=File}} objects, the file content. <tt>PUT</tt> to replace the metadata and/or contents (see  [[API:EPrints/Apache/CRUD#Updating_complex_objects_using_PUT|Updating complex objects using PUT]]). If the object does not exist will  attempt to create it with the given dataobjid (requires <tt>upsert</tt> privilege).

<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<span style='display:none'>User Comments</span>
<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
</div>
<!-- Pod2Wiki=item_id_datasetid_dataobjid_contents_delete_get_head_options_post_put -->
====/id/[datasetid]/[dataobjid]/contents DELETE,GET,HEAD,OPTIONS,POST,PUT====

Requires authentication depending on user's privileges and object visibility.

<tt>GET</tt> the logical contents of the object: documents for eprints or files for  documents. <tt>PUT</tt> to replace the existing contents or POST to add to the  existing contents.

<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<span style='display:none'>User Comments</span>
<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
</div>
<!-- Pod2Wiki=head_http_content_negotiation -->
===HTTP Content Negotiation===
<tt>GET</tt>/<tt>HEAD</tt> requests are processed using {{API:PodLink|file=EPrints/Plugin/Export|package_name=EPrints::Plugin::Export|section=|text=Export}}  plugins. <tt>POST</tt>/<tt>PUT</tt> requests are processed using {{API:PodLink|file=EPrints/Plugin/Import|package_name=EPrints::Plugin::Import|section=|text=Import}} plugins.

The plugin used depends on the request's <tt>Accept</tt> (<tt>GET</tt>/<tt>HEAD</tt>) or  <tt>Content-Type</tt> (<tt>POST</tt>/<tt>PUT</tt>) header and the type of object being acted on. For example, the following request:

  GET /id/eprint/23 HTTP/1.1
  Accept: application/vnd.eprints.data+xml
  
Will search for an Export plugin that accepts objects of type <tt>dataobj/eprint</tt>  and can produce output in the MIME type <tt>application/vnd.eprints.data+xml</tt>.  This will most likely be the {{API:PodLink|file=EPrints/Plugin/Export/XML|package_name=EPrints::Plugin::Export::XML|section=|text=EP3 XML}} plugin.

In addition to the general plugin negotiation behaviour some special cases are  supported to improve compatibility with Atom Pub/Web Browser clients:

<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<span style='display:none'>User Comments</span>
<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
</div>
<!-- Pod2Wiki=item_id_eprint -->
====/id/eprint/...====

Requesting {{API:PodLink|file=EPrints/DataObj/EPrint|package_name=EPrints::DataObj::EPrint|section=|text=EPrint}} objects as text/html will result in a <tt>303 Redirect</tt> to the eprint object's abstract page or, if the eprint is  not public, its {{API:PodLink|file=EPrints/Plugin/Screen/EPrint/View|package_name=EPrints::Plugin::Screen::EPrint::View|section=|text=View}} page.

<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<span style='display:none'>User Comments</span>
<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
</div>
<!-- Pod2Wiki=item_id_document_contents -->
====/id/document/.../contents====

Requesting the <tt>/contents</tt> of a {{API:PodLink|file=EPrints/DataObj/Document|package_name=EPrints::DataObj::Document|section=|text=Document}} object  will return the content of the document's main file.

<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<span style='display:none'>User Comments</span>
<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
</div>
<!-- Pod2Wiki=item_id_file -->
====/id/file/...====

Requesting a {{API:PodLink|file=EPrints/DataObj/File|package_name=EPrints::DataObj::File|section=|text=File}} object with no <tt>Accept</tt> header (or  <tt>*/*</tt>) will return the file's content.

<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<span style='display:none'>User Comments</span>
<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
</div>
<!-- Pod2Wiki=item_post_id_contents -->
====POST /id/.../contents====

When creating new records via POST, content negotiation is performed against  the Import plugins.

If no Import plugin supports the <em>Content-Type</em> header the content will be  treated as <tt>application/octet-stream</tt> and stored in a new object. The  resulting Atom entry will describe the new object (e.g. the <tt>eprint</tt> object  in which the new <tt>document</tt> and <tt>file</tt> objects were created).

Otherwise, the result will depend on the Import plugin's output. Import  plugins may produce a single object, multiple objects or an object plus  content file(s).

<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<span style='display:none'>User Comments</span>
<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
</div>
<!-- Pod2Wiki=item_content_type_header -->
====Content-Type header====

If no <tt>Content-Type</tt> header is given the MIME type defaults to  <tt>application/octet-stream</tt> for <tt>POST</tt>s and <tt>PUT</tt>s.

<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<span style='display:none'>User Comments</span>
<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
</div>
<!-- Pod2Wiki=item_content_disposition_header -->
====Content-Disposition header====

If the <tt>Content-Disposition</tt> header is missing or does not contain a  <tt>filename</tt> parameter the filename defaults to ''main.bin'' for <tt>POST</tt>s and  <tt>PUT</tt>s.

<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<span style='display:none'>User Comments</span>
<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
</div>
<!-- Pod2Wiki=head_updating_complex_objects_using_put -->
===Updating complex objects using PUT===
Eprint objects contain zero or more documents, which each contain zero or  more files. When you update (<tt>PUT</tt>) an eprint object the contained documents  will only be replaced if the Import plugin defines new documents e.g. the  Atom Import plugin will never define new documents so <tt>PUT</tt>ing Atom content  will only update the eprint's metadata. <tt>PUT</tt>ing  {{API:PodLink|file=EPrints/Plugin/Export/XML|package_name=EPrints::Plugin::Export::XML|section=|text=EP3 XML}} will replace the documents if you  include a <tt>&lt;documents</tt>&gt; XML element.

<tt>PUT</tt>ing to <tt>/contents</tt> will always replace all contents - <tt>PUT</tt>ing to  <tt>/eprint/23/contents</tt> is equivalent to <tt>DELETE /eprint/23/contents</tt> then  <tt>POST /eprint/23/contents</tt>.

<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<span style='display:none'>User Comments</span>
<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
</div>
<!-- Pod2Wiki=head_put_delete_from_javascript -->
===PUT/DELETE from Javascript===
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<span style='display:none'>User Comments</span>
<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
</div>
<!-- Pod2Wiki=head_upserting_objects_with_put -->
===Upserting objects with PUT===
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<span style='display:none'>User Comments</span>
<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
</div>
<!-- Pod2Wiki=head_constants -->