Difference between revisions of "API:EPrints/Apache/CRUD"

From EPrints Documentation
Jump to: navigation, search
(Created page with '<!-- Pod2Wiki=_preamble_ This page has been automatically generated from the EPrints 3.2 source. Any wiki changes made between the 'Pod2Wiki=*' and 'Edit below this comment' com…')
 
Line 8: Line 8:
 
EPrints::Apache::CRUD
 
EPrints::Apache::CRUD
  
<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 -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
</div>
 
 
<!-- Pod2Wiki=head_synopsis -->
 
<!-- Pod2Wiki=head_synopsis -->
 
==SYNOPSIS==
 
==SYNOPSIS==
  $crud = EPrints::Apache::CRUD-&gt;new(
+
<source lang="perl">$crud = EPrints::Apache::CRUD->new(
      repository =&gt; $repo,
+
repository => $repo,
      request =&gt; $r,
+
request => $r,
      datasetid =&gt; "eprint",
+
datasetid => "eprint",
      dataobjid =&gt; "23",
+
dataobjid => "23",
    );
+
);</source>
 
+
 
<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 -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
</div>
 
 
<!-- Pod2Wiki=head_description -->
 
<!-- Pod2Wiki=head_description -->
 
==DESCRIPTION==
 
==DESCRIPTION==
Line 37: Line 31:
 
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:
 
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;
+
<pre>  &lt;link rel="Sword" href="https://myrepo/sword-app/servicedocument" /&gt;
   &lt;link rel="SwordDeposit" href="https://myrepo/id/contents" /&gt;
+
   &lt;link rel="SwordDeposit" href="https://myrepo/id/contents" /&gt;</pre>
 
+
 
<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 -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
</div>
 
 
<!-- Pod2Wiki=head_examples -->
 
<!-- Pod2Wiki=head_examples -->
 
===Examples===
 
===Examples===
 
Create a new eprint based on a single file:
 
Create a new eprint based on a single file:
  
  curl -x POST \
+
<pre>  curl -x POST \
 
     -i \
 
     -i \
 
     -u user:password \
 
     -u user:password \
Line 60: Line 51:
 
   HTTP/1.1 201 Created
 
   HTTP/1.1 201 Created
 
   Content-Type: application/atom+xml;charset=utf-8
 
   Content-Type: application/atom+xml;charset=utf-8
   ...
+
   ...</pre>
 
+
 
 
Add a file to an existing eprint:
 
Add a file to an existing eprint:
  
  curl -X POST \
+
<pre>  curl -X POST \
 
     -i \
 
     -i \
 
     -u user:password \
 
     -u user:password \
Line 74: Line 65:
 
   HTTP/1.1 201 Created
 
   HTTP/1.1 201 Created
 
   Content-Type: application/atom+xml;charset=utf-8
 
   Content-Type: application/atom+xml;charset=utf-8
   ...
+
   ...</pre>
 
+
 
 
Get an eprint's metadata in Atom XML:
 
Get an eprint's metadata in Atom XML:
  
  curl -X GET \
+
<pre>  curl -X GET \
 
     -i \
 
     -i \
 
     -u user:password \
 
     -u user:password \
Line 86: Line 77:
 
   HTTP/1.1 200 OK
 
   HTTP/1.1 200 OK
 
   Content-Type: application/atom+xml;charset=utf-8
 
   Content-Type: application/atom+xml;charset=utf-8
   ...
+
   ...</pre>
 
+
 
 
Get the list of contents (documents) of an eprint in Atom XML:
 
Get the list of contents (documents) of an eprint in Atom XML:
  
  curl -X GET \
+
<pre>  curl -X GET \
 
     -i \
 
     -i \
 
     -u user:password \
 
     -u user:password \
Line 98: Line 89:
 
   HTTP/1.1 200 OK
 
   HTTP/1.1 200 OK
 
   Content-Type: application/atom+xml;charset=utf-8
 
   Content-Type: application/atom+xml;charset=utf-8
   ...
+
   ...</pre>
 
+
 
<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 -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
</div>
 
 
<!-- Pod2Wiki=head_content_negotiation -->
 
<!-- Pod2Wiki=head_content_negotiation -->
 
===Content Negotiation===
 
===Content Negotiation===
Line 113: Line 101:
 
When GETing, your repository should support at least:
 
When GETing, your repository should support at least:
  
  application/vnd.eprints.data+xml - EPrints XML
+
<pre>  application/vnd.eprints.data+xml - EPrints XML
   application/atom+xml - Atom XML
+
   application/atom+xml - Atom XML</pre>
 
+
 
 
Depending on the object type requested (eprint, document etc.) additional formats may be available. These are defined by the 'mime-type' in the plugin.
 
Depending on the object type requested (eprint, document etc.) additional formats may be available. These are defined by the 'mime-type' in the plugin.
  
 
{{API:PodLink|file=EPrints/DataObj/EPrint|package_name=EPrints::DataObj::EPrint|section=|text=EPrint}} objects are always available as text/html, which will result in a 303 Redirect to the EPrint's abstract page or, if the EPrint is not public, the {{API:PodLink|file=EPrints/Plugin/Screen/EPrint/View|package_name=EPrints::Plugin::Screen::EPrint::View|section=|text=View}} page.
 
{{API:PodLink|file=EPrints/DataObj/EPrint|package_name=EPrints::DataObj::EPrint|section=|text=EPrint}} objects are always available as text/html, which will result in a 303 Redirect to the EPrint's abstract page or, if the EPrint is not public, the {{API:PodLink|file=EPrints/Plugin/Screen/EPrint/View|package_name=EPrints::Plugin::Screen::EPrint::View|section=|text=View}} page.
  
Requesting the <tt>/contents</tt> of a {{API:PodLink|file=EPrints/DataObj/Document|package_name=EPrints::DataObj::Document|section=|text=Document}} will return the content of the main file. Requesting a {{API:PodLink|file=EPrints/DataObj/File|package_name=EPrints::DataObj::File|section=|text=File}} with no Accept header (or '*/*') will return the file content.
+
Requesting the <code>/contents</code> of a {{API:PodLink|file=EPrints/DataObj/Document|package_name=EPrints::DataObj::Document|section=|text=Document}} will return the content of the main file. Requesting a {{API:PodLink|file=EPrints/DataObj/File|package_name=EPrints::DataObj::File|section=|text=File}} with no Accept header (or '*/*') will return the file content.
  
 
When creating new records via POST content negotiation is performed against the Import plugins. If no Import plugin supports the given Content-Type the content will be treated as binary and stored in a new, blank object. The returned Atom entry will describe the new object (e.g. the root 'eprint' object, in which the new document and file were created).
 
When creating new records via POST content negotiation is performed against the Import plugins. If no Import plugin supports the given Content-Type the content will be treated as binary and stored in a new, blank object. The returned Atom entry will describe the new object (e.g. the root 'eprint' object, in which the new document and file were created).
Line 128: Line 116:
 
If no Content-Type is given the MIME type defaults to application/octet-stream. If no Content-Disposition with a 'filename' argument is given the filename will be set to 'main.bin'.
 
If no Content-Type is given the MIME type defaults to application/octet-stream. If no Content-Disposition with a 'filename' argument is given the filename will be set to 'main.bin'.
  
<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 -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
</div>
 
 
<!-- Pod2Wiki=head_updating_complex_objects_using_put -->
 
<!-- Pod2Wiki=head_updating_complex_objects_using_put -->
 
===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 (PUT) 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 PUTing Atom content will only update the EPrint's metadata. PUTing EPrints XML will replace the documents if you include a &lt;documents&gt; XML element.
 
EPrint objects contain zero or more documents, which each contain zero or more files. When you update (PUT) 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 PUTing Atom content will only update the EPrint's metadata. PUTing EPrints XML will replace the documents if you include a &lt;documents&gt; XML element.
  
PUTing to <tt>/contents</tt> will always replace all contents e.g. PUTing to <tt>/eprint/23/contents</tt> is equivalent to <tt>DELETE /eprint/23/contents</tt> then <tt>POST /eprint/23/contents</tt>.
+
PUTing to <code>/contents</code> will always replace all contents e.g. PUTing to <code>/eprint/23/contents</code> is equivalent to <code>DELETE /eprint/23/contents</code> then <code>POST /eprint/23/contents</code>.
  
<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 -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
</div>
 
 
<!-- Pod2Wiki=head_uris -->
 
<!-- Pod2Wiki=head_uris -->
 
===URIs===
 
===URIs===
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+
* /id/contents GET,HEAD,OPTIONS,POST
<span style='display:none'>User Comments</span>
+
*: Requires authentication.
<!-- Edit below this comment -->
+
  
 +
*: GET a list of the eprints owned by the user. POST to create a new EPrint object.
  
<!-- Pod2Wiki= -->
+
* /id/[datasetid]/[dataobjid] DELETE,GET,HEAD,OPTIONS,PUT
</div>
+
*: Requires authentication depending on user's privileges and object visibility.
<!-- Pod2Wiki=item_id_contents_get_head_options_post -->
+
====/id/contents GET,HEAD,OPTIONS,POST====
+
  
Requires authentication.
+
*: GET an object's metadata or, for {{API:PodLink|file=EPrints/DataObj/File|package_name=EPrints::DataObj::File|section=|text=File}} objects, the file content. PUT 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 'upsert' privilege).
  
GET a list of the eprints owned by the user. POST to create a new EPrint object.
+
* /id/[datasetid]/[dataobjid]/contents DELETE,GET,HEAD,OPTIONS,POST,PUT
 +
*: Requires authentication depending on user's privileges and object visibility.
 +
 
 +
*: GET the logical contents of the object: documents for eprints or files for documents. PUT 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 -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
</div>
+
<!-- Pod2Wiki=head_ajax_requests -->
<!-- Pod2Wiki=item_id_datasetid_dataobjid_delete_get_head_options_put -->
+
==AJAX REQUESTS==
====/id/[datasetid]/[dataobjid] DELETE,GET,HEAD,OPTIONS,PUT====
+
Browsers only allow GET and POST requests. To perform other requests use the 'X-Method' header with POST to specify the actual method you want.
  
Requires authentication depending on user's privileges and object visibility.
+
<pre>  POST /id/eprint/23 HTTP/1.1
 +
  X-Method: PUT
 +
  ...</pre>
  
GET an object's metadata or, for {{API:PodLink|file=EPrints/DataObj/File|package_name=EPrints::DataObj::File|section=|text=File}} objects, the file content. PUT 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 'upsert' 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 -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
</div>
+
<!-- Pod2Wiki=head_methods -->
<!-- Pod2Wiki=item_id_datasetid_dataobjid_contents_delete_get_head_options_post_put -->
+
==METHODS==
====/id/[datasetid]/[dataobjid]/contents DELETE,GET,HEAD,OPTIONS,POST,PUT====
+
<!-- Pod2Wiki=head_repository -->
 +
===repository===
  
Requires authentication depending on user's privileges and object visibility.
+
<source lang="perl">$repo = $crud->repository()
  
GET the logical contents of the object: documents for eprints or files for documents. PUT to replace the existing contents or POST to add to the existing contents.
+
</source>
 +
Returns the current repository.
  
<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 -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
</div>
+
<!-- Pod2Wiki=head_request -->
<!-- Pod2Wiki=head_methods -->
+
===request===
==METHODS==
+
<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 -->
+
  
 +
<source lang="perl">$r = $crud->request()
  
<!-- Pod2Wiki= -->
+
</source>
</div>
+
Returns the current {{API:PodLink|file=Apache2/RequestUtil|package_name=Apache2::RequestUtil|section=|text=Apache2::RequestUtil}}.
<!-- Pod2Wiki=item_repository -->
+
===repository===
+
 
+
$repo = $crud-&gt;repository()
+
Returns the current repository.
+
  
<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 -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
</div>
+
<!-- Pod2Wiki=head_method -->
<!-- Pod2Wiki=item_request -->
+
===method===
===request===
+
  
$r = $crud-&gt;request()
+
<source lang="perl">$method = $crud->method()
Returns the current {{API:PodLink|file=Apache2/RequestUtil|package_name=Apache2::RequestUtil|section=|text=Apache2::RequestUtil}}.
+
 
 +
</source>
 +
Returns the HTTP method.
  
<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 -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
</div>
+
<!-- Pod2Wiki=head_scope -->
<!-- Pod2Wiki=item_scope -->
+
 
===scope===
 
===scope===
  
$scope = $crud-&gt;scope()
+
<source lang="perl">$scope = $crud->scope()
 +
 
 +
</source>
 
Returns the scope of the action being performed.
 
Returns the scope of the action being performed.
  
<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 -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
</div>
+
<!-- Pod2Wiki=head_dataset -->
<!-- Pod2Wiki=item_dataset -->
+
 
===dataset===
 
===dataset===
  
$dataset = $crud-&gt;dataset()
+
<source lang="perl">$dataset = $crud->dataset()
 +
 
 +
</source>
 
Returns the current dataset (if any).
 
Returns the current dataset (if any).
  
<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 -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
</div>
+
<!-- Pod2Wiki=head_dataobj -->
<!-- Pod2Wiki=item_dataobj -->
+
 
===dataobj===
 
===dataobj===
  
$dataobj = $crud-&gt;dataobj()
+
<source lang="perl">$dataobj = $crud->dataobj()
 +
 
 +
</source>
 
Returns the current dataobj (if any).
 
Returns the current dataobj (if any).
  
<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 -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
</div>
+
<!-- Pod2Wiki=head_field -->
<!-- Pod2Wiki=item_field -->
+
 
===field===
 
===field===
  
$field = $crud-&gt;field()
+
<source lang="perl">$field = $crud->field()
 +
 
 +
</source>
 
Returns the current field (if available);
 
Returns the current field (if available);
  
<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 -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
</div>
+
<!-- Pod2Wiki=head_headers -->
<!-- Pod2Wiki=item_headers -->
+
 
===headers===
 
===headers===
  
$headers = $crud-&gt;headers()
+
<source lang="perl">$headers = $crud->headers()
 +
 
 +
</source>
 
Get the processed headers.
 
Get the processed headers.
  
<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 -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
</div>
+
<!-- Pod2Wiki=head_options -->
<!-- Pod2Wiki=item_options -->
+
 
===options===
 
===options===
  
@verbs = $crud-&gt;options()
+
<source lang="perl">@verbs = $crud->options()
 +
 
 +
</source>
 
Returns the available HTTP verbs for the current request.
 
Returns the available HTTP verbs for the current request.
  
<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 -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
</div>
+
<!-- Pod2Wiki=head_plugin -->
<!-- Pod2Wiki=item_plugin -->
+
 
===plugin===
 
===plugin===
  
$plugin = $crud-&gt;plugin()
+
<source lang="perl">$plugin = $crud->plugin()
 +
 
 +
</source>
 
Returns the current plugin (if available).
 
Returns the current plugin (if available).
  
<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 -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
</div>
+
<!-- Pod2Wiki=head_is_write -->
<!-- Pod2Wiki=item_is_write -->
+
 
===is_write===
 
===is_write===
  
$bool = $crud-&gt;is_write()
+
<source lang="perl">$bool = $crud->is_write()
 +
 
 +
</source>
 
Returns true if the request is not a read-only method.
 
Returns true if the request is not a read-only method.
  
<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 -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
</div>
+
<!-- Pod2Wiki=head_accept_type -->
<!-- Pod2Wiki=item_check_packaging -->
+
===accept_type===
 +
 
 +
<source lang="perl">$accept_type = $crud->accept_type()
 +
 
 +
</source>
 +
Returns the EPrints type for the current request.
 +
 
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
<!-- Pod2Wiki=head_check_packaging -->
 
===check_packaging===
 
===check_packaging===
  
$rc = $crud-&gt;check_packaging()
+
<source lang="perl">$rc = $crud->check_packaging()
 +
 
 +
</source>
 
Check the Packaging header is ok, if given.
 
Check the Packaging header is ok, if given.
  
<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 -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
</div>
+
<!-- Pod2Wiki=head_parse_input -->
<!-- Pod2Wiki=item_parse_input -->
+
 
===parse_input===
 
===parse_input===
  
$list = $crud-&gt;parse_input( $plugin, $f [, %params ] )
+
<source lang="perl">$list = $crud->parse_input( $plugin, $f [, %params ] )
 +
 
 +
</source>
 
Parse the content submitted by the user using the given $plugin.  $f is called by epdata_to_dataobj to convert epdata to a dataobj.  %params are passed to the plugin's input_fh method.
 
Parse the content submitted by the user using the given $plugin.  $f is called by epdata_to_dataobj to convert epdata to a dataobj.  %params are passed to the plugin's input_fh method.
  
 
Returns undef on error.
 
Returns undef on error.
  
<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 -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
</div>
+
<!-- Pod2Wiki=head_import_plugins -->
<!-- Pod2Wiki=item_content_negotiate_best_plugin -->
+
===import_plugins===
 +
 
 +
<source lang="perl">@plugins = $crud->import_plugins( [ %params ] )
 +
 
 +
</source>
 +
Returns all matching import plugins against %params ordered by descending 'q' score.
 +
 
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
<!-- Pod2Wiki=head_export_plugins -->
 +
===export_plugins===
 +
 
 +
<source lang="perl">@plugins = $crud->export_plugins( [ %params ] )
 +
 
 +
</source>
 +
Returns all matching export plugins against %params ordered by descending 'q' score.
 +
 
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
<!-- Pod2Wiki=head_content_negotiate_best_plugin -->
 
===content_negotiate_best_plugin===
 
===content_negotiate_best_plugin===
  
$plugin = $crud-&gt;content_negotiate_best_plugin( $r )
+
<source lang="perl">$plugin = $crud->content_negotiate_best_plugin()
 +
 
 +
</source>
 
Work out the best plugin to export/update an object based on the client-headers.
 
Work out the best plugin to export/update an object based on the client-headers.
  
<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 -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
</div>
 
 
<!-- Pod2Wiki=head_see_also -->
 
<!-- Pod2Wiki=head_see_also -->
 
==SEE ALSO==
 
==SEE ALSO==
Line 385: Line 377:
 
http://en.wikipedia.org/wiki/Content_negotiation
 
http://en.wikipedia.org/wiki/Content_negotiation
  
<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 -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
</div>
 
 
<!-- Pod2Wiki=head_copyright -->
 
<!-- Pod2Wiki=head_copyright -->
 
==COPYRIGHT==
 
==COPYRIGHT==
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #ccepadding: 0em 1em 0em 1em; font-size: 80%; '>
+
Copyright 2000-2011 University of Southampton.
<span style='display:none'>User Comments</span>
+
 
 +
This file is part of EPrints http://www.eprints.org/.
 +
 
 +
EPrints is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
 +
 
 +
EPrints is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
 +
 
 +
You should have received a copy of the GNU Lesser General Public License along with EPrints.  If not, see http://www.gnu.org/licenses/.
 +
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
</div>
+
<!-- Pod2Wiki=_postamble_ -->
<!-- Pod2Wiki=_postamble_ --><!-- Edit below this comment -->
+
<!-- Edit below this comment -->

Revision as of 15:25, 30 March 2012

EPrints 3 Reference: Directory Structure - Metadata Fields - Repository Configuration - XML Config Files - XML Export Format - EPrints data structure - Core API - Data Objects


API: Core API

Latest Source Code (3.3, 3.2) | Revision Log | Before editing this page please read Pod2Wiki


NAME

EPrints::Apache::CRUD


SYNOPSIS

$crud = EPrints::Apache::CRUD->new(
		repository => $repo,
		request => $r,
		datasetid => "eprint",
		dataobjid => "23",
	);


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 <link> entries in the repository's home page to locate the CRUD endpoint, as they may change in the future:

  <link rel="Sword" href="https://myrepo/sword-app/servicedocument" />
  <link rel="SwordDeposit" href="https://myrepo/id/contents" />


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
  ...


Content Negotiation

You can GET/HEAD/POST/PUT in the formats supported by your Export/Import plugins. ('Export' plugins for GET/HEAD and 'Import' for POST/PUT.)

When GETing, your repository should support at least:

  application/vnd.eprints.data+xml - EPrints XML
  application/atom+xml - Atom XML

Depending on the object type requested (eprint, document etc.) additional formats may be available. These are defined by the 'mime-type' in the plugin.

EPrint objects are always available as text/html, which will result in a 303 Redirect to the EPrint's abstract page or, if the EPrint is not public, the View page.

Requesting the /contents of a Document will return the content of the main file. Requesting a File with no Accept header (or '*/*') will return the file content.

When creating new records via POST content negotiation is performed against the Import plugins. If no Import plugin supports the given Content-Type the content will be treated as binary and stored in a new, blank object. The returned Atom entry will describe the new object (e.g. the root 'eprint' object, in which the new document and file were created).

If the POSTed content is in a recognised format the resulting object(s) will depend on what the Import plugin outputs. This may be a single object, if the output is only an object, or an object plus content file(s).

If no Content-Type is given the MIME type defaults to application/octet-stream. If no Content-Disposition with a 'filename' argument is given the filename will be set to 'main.bin'.


Updating complex objects using PUT

EPrint objects contain zero or more documents, which each contain zero or more files. When you update (PUT) 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 PUTing Atom content will only update the EPrint's metadata. PUTing EPrints XML will replace the documents if you include a <documents> XML element.

PUTing to /contents will always replace all contents e.g. PUTing to /eprint/23/contents is equivalent to DELETE /eprint/23/contents then POST /eprint/23/contents.


URIs

  • /id/contents GET,HEAD,OPTIONS,POST
    Requires authentication.
  • GET a list of the eprints owned by the user. POST to create a new EPrint object.
  • /id/[datasetid]/[dataobjid] DELETE,GET,HEAD,OPTIONS,PUT
    Requires authentication depending on user's privileges and object visibility.
  • GET an object's metadata or, for File objects, the file content. PUT to replace the metadata and/or contents (see Updating complex objects using PUT). If the object does not exist will attempt to create it with the given dataobjid (requires 'upsert' privilege).
  • /id/[datasetid]/[dataobjid]/contents DELETE,GET,HEAD,OPTIONS,POST,PUT
    Requires authentication depending on user's privileges and object visibility.
  • GET the logical contents of the object: documents for eprints or files for documents. PUT to replace the existing contents or POST to add to the existing contents.


AJAX REQUESTS

Browsers only allow GET and POST requests. To perform other requests use the 'X-Method' header with POST to specify the actual method you want.

  POST /id/eprint/23 HTTP/1.1
  X-Method: PUT
  ...


METHODS

repository

$repo = $crud->repository()

Returns the current repository.


request

$r = $crud->request()

Returns the current Apache2::RequestUtil.


method

$method = $crud->method()

Returns the HTTP method.


scope

$scope = $crud->scope()

Returns the scope of the action being performed.


dataset

$dataset = $crud->dataset()

Returns the current dataset (if any).


dataobj

$dataobj = $crud->dataobj()

Returns the current dataobj (if any).


field

$field = $crud->field()

Returns the current field (if available);


headers

$headers = $crud->headers()

Get the processed headers.


options

@verbs = $crud->options()

Returns the available HTTP verbs for the current request.


plugin

$plugin = $crud->plugin()

Returns the current plugin (if available).


is_write

$bool = $crud->is_write()

Returns true if the request is not a read-only method.


accept_type

$accept_type = $crud->accept_type()

Returns the EPrints type for the current request.


check_packaging

$rc = $crud->check_packaging()

Check the Packaging header is ok, if given.


parse_input

$list = $crud->parse_input( $plugin, $f [, %params ] )

Parse the content submitted by the user using the given $plugin. $f is called by epdata_to_dataobj to convert epdata to a dataobj.  %params are passed to the plugin's input_fh method.

Returns undef on error.


import_plugins

@plugins = $crud->import_plugins( [ %params ] )

Returns all matching import plugins against %params ordered by descending 'q' score.


export_plugins

@plugins = $crud->export_plugins( [ %params ] )

Returns all matching export plugins against %params ordered by descending 'q' score.


content_negotiate_best_plugin

$plugin = $crud->content_negotiate_best_plugin()

Work out the best plugin to export/update an object based on the client-headers.


SEE ALSO

http://en.wikipedia.org/wiki/Create,_read,_update_and_delete

http://en.wikipedia.org/wiki/Content_negotiation


COPYRIGHT

Copyright 2000-2011 University of Southampton.

This file is part of EPrints http://www.eprints.org/.

EPrints is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

EPrints is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with EPrints. If not, see http://www.gnu.org/licenses/.