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…')
 
(30 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 
<!-- Pod2Wiki=_preamble_  
 
<!-- 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' comments will be lost.
+
This page has been automatically generated from the EPrints 3.4 source. Any wiki changes made between the 'Pod2Wiki=*' and 'Edit below this comment' comments will be lost.
  -->{{API}}{{Pod2Wiki}}{{API:Source|file=perl_lib/EPrints/Apache/CRUD.pm|package_name=EPrints::Apache::CRUD}}[[Category:API|CRUD]][[Category:API:EPrints/Apache|CRUD]][[Category:API:EPrints/Apache/CRUD|CRUD]]<div><!-- Edit below this comment -->
+
  -->{{API}}{{Pod2Wiki}}{{API:Source|file=EPrints/Apache/CRUD.pm|package_name=EPrints::Apache::CRUD}}[[Category:API|CRUD]][[Category:API:EPrints/Apache|CRUD]]<div><!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=_private_ --><!-- Pod2Wiki=head_name -->
+
<!-- Pod2Wiki=_private_ -->{{Version|since=3.3.0}}<!-- Pod2Wiki=head_name -->
 
==NAME==
 
==NAME==
EPrints::Apache::CRUD
+
'''EPrints::Apache::CRUD''' - Create, read, update and delete via HTTP
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 51: Line 51:
 
Create a new eprint based on a single file:
 
Create a new eprint based on a single file:
  
   curl -x POST \
+
   curl -X POST \
 
     -i \
 
     -i \
 
     -u user:password \
 
     -u user:password \
Line 100: Line 100:
 
   ...
 
   ...
 
    
 
    
 +
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.
 +
 +
GET a list of the eprints owned by the user. POST 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%; '>
 
<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>
 
<span style='display:none'>User Comments</span>
Line 107: Line 134:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
<!-- Pod2Wiki=head_content_negotiation -->
+
<!-- Pod2Wiki=item_id_datasetid_dataobjid_delete_get_head_options_put -->
===Content Negotiation===
+
====/id/[datasetid]/[dataobjid] DELETE,GET,HEAD,OPTIONS,PUT====
You can GET/HEAD/POST/PUT in the formats supported by your {{API:PodLink|file=EPrints/Plugin/Export|package_name=EPrints::Plugin::Export|section=|text=Export}}/{{API:PodLink|file=EPrints/Plugin/Import|package_name=EPrints::Plugin::Import|section=|text=Import}} plugins. ('Export' plugins for GET/HEAD and 'Import' for POST/PUT.)
+
 
 +
Requires authentication depending on user's privileges and object visibility.
  
When GETing, your repository should support at least:
+
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).
  
  application/vnd.eprints.data+xml - EPrints XML
+
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
   application/atom+xml - Atom XML
+
<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.
 +
 
 +
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 -->
 +
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=head_http_content_negotiation -->
 +
===HTTP Content Negotiation===
 +
GET/HEAD requests are processed using {{API:PodLink|file=EPrints/Plugin/Export|package_name=EPrints::Plugin::Export|section=|text=Export}} plugins. POST/PUT 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 <em>Accept</em> (GET/HEAD) or <em>Content-Type</em> (POST/PUT) 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
 
    
 
    
Depending on the object type requested (eprint, document etc.) additional formats may be available. These are defined by the 'mime-type' in the plugin.
+
Will search for an Export plugin that accepts objects of type '''dataobj/eprint''' and can produce output in the MIME type '''application/vnd.eprints.data+xml'''. This will most likely be the {{API:PodLink|file=EPrints/Plugin/Export/XML|package_name=EPrints::Plugin::Export::XML|section=|text=EP3 XML}} 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.
+
In addition to the general plugin negotiation behaviour some special cases are supported to improve compatibility with Atom Pub/Web Browser clients:
  
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.
+
<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 -->
  
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).
+
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=item_id_eprint -->
 +
====/id/eprint/...====
  
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'.
+
Requesting {{API:PodLink|file=EPrints/DataObj/EPrint|package_name=EPrints::DataObj::EPrint|section=|text=EPrint}} objects as text/html will result in a 303 Redirect 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%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 135: Line 194:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
<!-- Pod2Wiki=head_updating_complex_objects_using_put -->
+
<!-- Pod2Wiki=item_id_document_contents -->
===Updating complex objects using PUT===
+
====/id/document/.../contents====
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>.
+
Requesting the <em>/contents</em> 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%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 148: Line 206:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
<!-- Pod2Wiki=head_uris -->
+
<!-- Pod2Wiki=item_id_file -->
===URIs===
+
====/id/file/...====
 +
 
 +
Requesting a {{API:PodLink|file=EPrints/DataObj/File|package_name=EPrints::DataObj::File|section=|text=File}} object with no <em>Accept</em> header (or '''*/*''') 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%; '>
 
<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>
 
<span style='display:none'>User Comments</span>
Line 157: Line 218:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
<!-- Pod2Wiki=item_id_contents_get_head_options_post -->
+
<!-- Pod2Wiki=item_post_id_contents -->
====/id/contents GET,HEAD,OPTIONS,POST====
+
====POST /id/.../contents====
 +
 
 +
When creating new records via POST, content negotiation is performed against the Import plugins.
  
Requires authentication.
+
If no Import plugin supports the <em>Content-Type</em> header the content will be treated as '''application/octet-stream''' and stored in a new object. The resulting Atom entry will describe the new object (e.g. the <em>eprint</em> object in which the new <em>document</em> and <em>file</em> objects were created).
  
GET a list of the eprints owned by the user. POST to create a new EPrint object.
+
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%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 171: Line 234:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
<!-- Pod2Wiki=item_id_datasetid_dataobjid_delete_get_head_options_put -->
+
<!-- Pod2Wiki=item_content_type_header -->
====/id/[datasetid]/[dataobjid] DELETE,GET,HEAD,OPTIONS,PUT====
+
====Content-Type header====
 +
 
 +
If no <em>Content-Type</em> header is given the MIME type defaults to '''application/octet-stream''' for POSTs and PUTs.
 +
 
 +
<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 -->
 +
 
  
Requires authentication depending on user's privileges and object visibility.
+
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=item_content_disposition_header -->
 +
====Content-Disposition header====
  
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).
+
If the <em>Content-Disposition</em> header is missing or does not contain a <em>filename</em> parameter the filename defaults to ''main.bin'' for POSTs and PUTs.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 185: Line 258:
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
 
</div>
 
</div>
<!-- Pod2Wiki=item_id_datasetid_dataobjid_contents_delete_get_head_options_post_put -->
+
<!-- Pod2Wiki=head_updating_complex_objects_using_put -->
====/id/[datasetid]/[dataobjid]/contents DELETE,GET,HEAD,OPTIONS,POST,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 {{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 &lt;documents&gt; XML element.
 +
 
 +
PUTing to <em>/contents</em> will always replace all contents - PUTing to <em>/eprint/23/contents</em> is equivalent to <em>DELETE /eprint/23/contents</em> then <em>POST /eprint/23/contents</em>.
 +
 
 +
<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 -->
 +
 
  
Requires authentication depending on user's privileges and object visibility.
+
<!-- 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 -->
  
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.
 
  
 +
<!-- 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%; '>
 
<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>
 
<span style='display:none'>User Comments</span>
Line 226: Line 316:
 
  $r = $crud-&gt;request()
 
  $r = $crud-&gt;request()
 
Returns the current {{API:PodLink|file=Apache2/RequestUtil|package_name=Apache2::RequestUtil|section=|text=Apache2::RequestUtil}}.
 
Returns the current {{API:PodLink|file=Apache2/RequestUtil|package_name=Apache2::RequestUtil|section=|text=Apache2::RequestUtil}}.
 +
 +
<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_method -->
 +
===method===
 +
 +
$method = $crud-&gt;method()
 +
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%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 330: Line 433:
 
  $bool = $crud-&gt;is_write()
 
  $bool = $crud-&gt;is_write()
 
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 -->
 +
 +
 +
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=item_accept_type -->
 +
===accept_type===
 +
 +
$accept_type = $crud-&gt;accept_type()
 +
Returns the EPrints type 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%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 343: Line 459:
 
  $rc = $crud-&gt;check_packaging()
 
  $rc = $crud-&gt;check_packaging()
 
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 -->
 +
 +
 +
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=item_resolve_relations -->
 +
===resolve_relations===
 +
 +
$dataobj = $crud-&gt;resolve_relations( $dataobj [, @relations ] )
 +
Resolve the relation path from $dataobj and return the resulting dataobj.
 +
 +
Returns undef if there is no such related 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_authen -->
 +
===authen===
 +
 +
$rc = $crud-&gt;authen
 +
Returns HTTP code based of whether CRUD request can be authenticated.
 +
 +
<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_authz -->
 +
===authz===
 +
 +
$rc = $crud-&gt;authz
 +
Returns HTTP code based of whether CRUD request can be authorized.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 358: Line 515:
  
 
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 -->
 +
 +
 +
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=item_create_dataobj -->
 +
===create_dataobj===
 +
 +
$dataobj = $crud-&gt;create_dataobj( $owner, $epdata )
 +
Creates data object as user $owner with metadata from $epdata
 +
 +
Returns an [[API:EPrints/DataObj|EPrints::DataObj]]
 +
 +
<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_import_plugins -->
 +
===import_plugins===
 +
 +
@plugins = $crud-&gt;import_plugins( [ %params ] )
 +
Returns all matching import plugins against %params ordered by descending 'q' score.
 +
 +
<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_export_plugins -->
 +
===export_plugins===
 +
 +
@plugins = $crud-&gt;export_plugins( [ %params ] )
 +
Returns all matching export plugins against %params ordered by descending 'q' score.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 369: Line 567:
 
===content_negotiate_best_plugin===
 
===content_negotiate_best_plugin===
  
  $plugin = $crud-&gt;content_negotiate_best_plugin( $r )
+
  $plugin = $crud-&gt;content_negotiate_best_plugin()
 
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 -->
 +
 +
 +
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=item_crud -->
 +
===crud===
 +
 +
EPrints::Apache::CRUD( $media_range )
 +
Takes the $media_range string and returns array of acceptable MIME types. See http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.1 for more detail.
 +
 +
<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_handler -->
 +
===handler===
 +
 +
$rc = $crud-&gt;handler
 +
Handler of CRUD requests.
 +
 +
Returns HTTP response 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 -->
 +
 +
 +
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=item_delete -->
 +
===delete===
 +
 +
$rc = $crud-&gt;DELETE()
 +
Handle DELETE requests.
 +
 +
<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_http_method_not_allowed -->
 +
===http_method_not_allowed===
 +
 +
HTTP_METHOD_NOT_ALLOWED
 +
Can't perform DELETE on ''/id/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=item_http_not_found -->
 +
===http_not_found===
 +
 +
HTTP_NOT_FOUND
 +
No such 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_http_conflict -->
 +
===http_conflict===
 +
 +
HTTP_CONFLICT
 +
Lock conflict with another user.
 +
 +
<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_http_no_content -->
 +
===http_no_content===
 +
 +
HTTP_NO_CONTENT
 +
Successfully removed the 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_get -->
 +
===get===
 +
 +
$rc = $crud-&gt;GET( [ $owner ] )
 +
Handle GET requests.
 +
 +
<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_http_no_content -->
 +
===http_no_content===
 +
 +
HTTP_NO_CONTENT
 +
No sub-objects in <em>/id/.../contents</em>.
 +
 +
<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_http_not_acceptable -->
 +
===http_not_acceptable===
 +
 +
HTTP_NOT_ACCEPTABLE
 +
More than one sub-object in <em>/id/.../contents</em>.
 +
 +
<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_http_unsupported_media_type -->
 +
===http_unsupported_media_type===
 +
 +
HTTP_UNSUPPORTED_MEDIA_TYPE
 +
No {{API:PodLink|file=EPrints/Plugin/Export|package_name=EPrints::Plugin::Export|section=|text=Export}} plugin matches the <em>Accept</em> header/object type.
 +
 +
<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_http_see_other -->
 +
===http_see_other===
 +
 +
HTTP_SEE_OTHER
 +
Redirect to a non-CRUD EPrints 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_http_not_found -->
 +
===http_not_found===
 +
 +
HTTP_NOT_FOUND
 +
Object not found.
 +
 +
<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_http_ok -->
 +
===http_ok===
 +
 +
HTTP_OK
 +
Object outputted successfully.
 +
 +
<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 -->
 +
===post===
 +
 +
$rc = $crud-&gt;POST( [ $owner ] )
 +
Handle POST requests.
 +
 +
<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_http_method_not_allowed -->
 +
===http_method_not_allowed===
 +
 +
HTTP_METHOD_NOT_ALLOWED
 +
Can only POST to <em>/id/.../contents</em>.
 +
 +
<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_http_bad_request -->
 +
===http_bad_request===
 +
 +
HTTP_BAD_REQUEST
 +
No plugin for the SWORD <em>Packaging</em> header.
 +
 +
<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_http_created -->
 +
===http_created===
 +
 +
HTTP_CREATED
 +
Object(s) successfully created.
 +
 +
<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_put -->
 +
===put===
 +
 +
$rc = $crud-&gt;PUT( [ $owner ] )
 +
Handle PUT requests.
 +
 +
<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_http_unsupported_media_type -->
 +
===http_unsupported_media_type===
 +
 +
HTTP_UNSUPPORTED_MEDIA_TYPE
 +
No {{API:PodLink|file=EPrints/Plugin/Import|package_name=EPrints::Plugin::Import|section=|text=Import}} plugin matched the <em>Content-Type</em> header/object type.
 +
 +
<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_http_range_not_satisfiable -->
 +
===http_range_not_satisfiable===
 +
 +
HTTP_RANGE_NOT_SATISFIABLE
 +
<em>Range</em> header is invalid or unsupported for the <em>object type</em>.
 +
 +
<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_http_forbidden -->
 +
===http_forbidden===
 +
 +
HTTP_FORBIDDEN
 +
User does not have permission to create/update the <em>object</em>.
 +
 +
<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_http_created -->
 +
===http_created===
 +
 +
HTTP_CREATED
 +
Object was successfully created.
 +
 +
<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_http_no_content -->
 +
===http_no_content===
 +
 +
HTTP_NO_CONTENT
 +
Object was successfully updated.
 +
 +
<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_put_contents -->
 +
===put_contents===
 +
 +
$rc = $crud-&gt;PUT_contents( [ $owner ] )
 +
Equivalent to <tt>DELETE /id/.../contents</tt> then <tt>POST /id/.../contents</tt>.
 +
 +
See [[API:EPrints/Apache/CRUD#DELETE|DELETE]] and [[API:EPrints/Apache/CRUD#POST|POST]].
 +
 +
<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_metadata_relevant -->
 +
===metadata_relevant===
 +
 +
$crud-&gt;metadata_relevant( $file )
 +
Test and if suitable use $file as metadata source to updatie the associated [[API:EPrints/DataObj/EPrint|EPrints::DataObj::EPrint]].
 +
 +
<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_servicedocument -->
 +
===servicedocument===
 +
 +
$crud-&gt;servicedocument
 +
Gennerate response containing CRUD service document.
 +
 +
<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_on_behalf_of -->
 +
===on_behalf_of===
 +
 +
$rc = $crud-&gt;on_behalf_of( $user )
 +
Submit CRUD request on behalf od another user.
 +
 +
Returns HTTPS response code based on wehther request on behalf of is  permitted.
 +
 +
<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_is_true -->
 +
===is_true===
 +
 +
$boolean = EPrints::Apache::Crud::is_true( $header )
 +
Tests if $header attribute is true.
 +
 +
<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_is_false -->
 +
===is_false===
 +
 +
$boolean = EPrints::Apache::Crud::is_false( $header )
 +
Tests if $header attribute is false.
 +
 +
<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_is_file_ok -->
 +
===is_file_ok===
 +
 +
$boolean = $crud-&gt;is_file_ok( $epdata )
 +
Tests if files with $epdata were uploaded with corruption.
 +
 +
<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_process_headers -->
 +
===process_headers===
 +
 +
$boolean = $crud-&gt;process_headers
 +
Process headers of CRUD 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 -->
 +
 +
 +
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=item_$boolean -->
 +
===$boolean===
 +
 +
$boolean = $crud-&gt;( %opts )
 +
Generate SWORD error documents based on provided %opts.
 +
 +
<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_plugin_error -->
 +
===plugin_error===
 +
 +
$boolean = $crud-&gt;plugin_error( $plugin, $messages )
 +
Generate error message for import $plugin used with $messages provided.
 +
 +
<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_generate_error_document -->
 +
===generate_error_document===
 +
 +
$error_document = EPrints::Apache::Crud::generate_error_document( $repo, %opts )
 +
Return error document for [[API:EPrints/Repository|EPrints::Repository]] $repo using options  from %opts.
 +
 +
<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_send_response -->
 +
===send_response===
 +
 +
$rc = $crud-&gt;send_response( $status, $content_type, $content )
 +
Output response to CRUD request with HTTP status code $status, content type $content_type.
 +
 +
Returns HTTP response code OK.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
Line 394: Line 1,068:
 
<!-- Pod2Wiki=head_copyright -->
 
<!-- Pod2Wiki=head_copyright -->
 
==COPYRIGHT==
 
==COPYRIGHT==
 +
{{API:Copyright}}
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<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>
 
<span style='display:none'>User Comments</span>

Revision as of 21:08, 14 December 2021

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.4, 3.3) | Revision Log | Before editing this page please read Pod2Wiki


Warning This feature requires EPrints version 3.3.0 or later

Contents

NAME

EPrints::Apache::CRUD - Create, read, update and delete via HTTP

User Comments


SYNOPSIS

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

User Comments


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" />
 

User Comments


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.

User Comments


URI layout

These URIs are relative to your EPrints HTTP/HTTPs root.

User Comments


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

User Comments


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

User Comments


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

User Comments


HTTP Content Negotiation

GET/HEAD requests are processed using Export plugins. POST/PUT requests are processed using Import plugins.

The plugin used depends on the request's Accept (GET/HEAD) or Content-Type (POST/PUT) 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 dataobj/eprint and can produce output in the MIME type application/vnd.eprints.data+xml. This will most likely be the 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:

User Comments


/id/eprint/...

Requesting EPrint objects as text/html will result in a 303 Redirect to the eprint object's abstract page or, if the eprint is not public, its View page.

User Comments


/id/document/.../contents

Requesting the /contents of a Document object will return the content of the document's main file.

User Comments


/id/file/...

Requesting a File object with no Accept header (or */*) will return the file's content.

User Comments


POST /id/.../contents

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

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

User Comments


Content-Type header

If no Content-Type header is given the MIME type defaults to application/octet-stream for POSTs and PUTs.

User Comments


Content-Disposition header

If the Content-Disposition header is missing or does not contain a filename parameter the filename defaults to main.bin for POSTs and PUTs.

User Comments


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 EP3 XML will replace the documents if you include a <documents> XML element.

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

User Comments


PUT/DELETE from Javascript

User Comments


Upserting objects with PUT

User Comments


METHODS

User Comments


repository

$repo = $crud->repository()

Returns the current repository.

User Comments


request

$r = $crud->request()

Returns the current Apache2::RequestUtil.

User Comments


method

$method = $crud->method()

Returns the HTTP method.

User Comments


scope

$scope = $crud->scope()

Returns the scope of the action being performed.

User Comments


dataset

$dataset = $crud->dataset()

Returns the current dataset (if any).

User Comments


dataobj

$dataobj = $crud->dataobj()

Returns the current dataobj (if any).

User Comments


field

$field = $crud->field()

Returns the current field (if available);

User Comments


headers

$headers = $crud->headers()

Get the processed headers.

User Comments


options

@verbs = $crud->options()

Returns the available HTTP verbs for the current request.

User Comments


plugin

$plugin = $crud->plugin()

Returns the current plugin (if available).

User Comments


is_write

$bool = $crud->is_write()

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

User Comments


accept_type

$accept_type = $crud->accept_type()

Returns the EPrints type for the current request.

User Comments


check_packaging

$rc = $crud->check_packaging()

Check the Packaging header is ok, if given.

User Comments


resolve_relations

$dataobj = $crud->resolve_relations( $dataobj [, @relations ] )

Resolve the relation path from $dataobj and return the resulting dataobj.

Returns undef if there is no such related object.

User Comments


authen

$rc = $crud->authen

Returns HTTP code based of whether CRUD request can be authenticated.

User Comments


authz

$rc = $crud->authz

Returns HTTP code based of whether CRUD request can be authorized.

User Comments


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.

User Comments


create_dataobj

$dataobj = $crud->create_dataobj( $owner, $epdata )

Creates data object as user $owner with metadata from $epdata

Returns an EPrints::DataObj

User Comments


import_plugins

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

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

User Comments


export_plugins

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

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

User Comments


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.

User Comments


crud

EPrints::Apache::CRUD( $media_range )

Takes the $media_range string and returns array of acceptable MIME types. See http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.1 for more detail.

User Comments


handler

$rc = $crud->handler

Handler of CRUD requests.

Returns HTTP response code.

User Comments


delete

$rc = $crud->DELETE()

Handle DELETE requests.

User Comments


http_method_not_allowed

HTTP_METHOD_NOT_ALLOWED

Can't perform DELETE on /id/contents.

User Comments


http_not_found

HTTP_NOT_FOUND

No such object.

User Comments


http_conflict

HTTP_CONFLICT

Lock conflict with another user.

User Comments


http_no_content

HTTP_NO_CONTENT

Successfully removed the object.

User Comments


get

$rc = $crud->GET( [ $owner ] )

Handle GET requests.

User Comments


http_no_content

HTTP_NO_CONTENT

No sub-objects in /id/.../contents.

User Comments


http_not_acceptable

HTTP_NOT_ACCEPTABLE

More than one sub-object in /id/.../contents.

User Comments


http_unsupported_media_type

HTTP_UNSUPPORTED_MEDIA_TYPE

No Export plugin matches the Accept header/object type.

User Comments


http_see_other

HTTP_SEE_OTHER

Redirect to a non-CRUD EPrints page.

User Comments


http_not_found

HTTP_NOT_FOUND

Object not found.

User Comments


http_ok

HTTP_OK

Object outputted successfully.

User Comments


post

$rc = $crud->POST( [ $owner ] )

Handle POST requests.

User Comments


http_method_not_allowed

HTTP_METHOD_NOT_ALLOWED

Can only POST to /id/.../contents.

User Comments


http_bad_request

HTTP_BAD_REQUEST

No plugin for the SWORD Packaging header.

User Comments


http_created

HTTP_CREATED

Object(s) successfully created.

User Comments


put

$rc = $crud->PUT( [ $owner ] )

Handle PUT requests.

User Comments


http_unsupported_media_type

HTTP_UNSUPPORTED_MEDIA_TYPE

No Import plugin matched the Content-Type header/object type.

User Comments


http_range_not_satisfiable

HTTP_RANGE_NOT_SATISFIABLE

Range header is invalid or unsupported for the object type.

User Comments


http_forbidden

HTTP_FORBIDDEN

User does not have permission to create/update the object.

User Comments


http_created

HTTP_CREATED

Object was successfully created.

User Comments


http_no_content

HTTP_NO_CONTENT

Object was successfully updated.

User Comments


put_contents

$rc = $crud->PUT_contents( [ $owner ] )

Equivalent to DELETE /id/.../contents then POST /id/.../contents.

See DELETE and POST.

User Comments


metadata_relevant

$crud->metadata_relevant( $file )

Test and if suitable use $file as metadata source to updatie the associated EPrints::DataObj::EPrint.

User Comments


servicedocument

$crud->servicedocument

Gennerate response containing CRUD service document.

User Comments


on_behalf_of

$rc = $crud->on_behalf_of( $user )

Submit CRUD request on behalf od another user.

Returns HTTPS response code based on wehther request on behalf of is permitted.

User Comments


is_true

$boolean = EPrints::Apache::Crud::is_true( $header )

Tests if $header attribute is true.

User Comments


is_false

$boolean = EPrints::Apache::Crud::is_false( $header )

Tests if $header attribute is false.

User Comments


is_file_ok

$boolean = $crud->is_file_ok( $epdata )

Tests if files with $epdata were uploaded with corruption.

User Comments


process_headers

$boolean = $crud->process_headers

Process headers of CRUD request

User Comments


$boolean

$boolean = $crud->( %opts )

Generate SWORD error documents based on provided %opts.

User Comments


plugin_error

$boolean = $crud->plugin_error( $plugin, $messages )

Generate error message for import $plugin used with $messages provided.

User Comments


generate_error_document

$error_document = EPrints::Apache::Crud::generate_error_document( $repo, %opts )

Return error document for EPrints::Repository $repo using options from %opts.

User Comments


send_response

$rc = $crud->send_response( $status, $content_type, $content )

Output response to CRUD request with HTTP status code $status, content type $content_type.

Returns HTTP response code OK.

User Comments


SEE ALSO

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

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

User Comments


COPYRIGHT

© Copyright 2023 University of Southampton.

EPrints 3.4 is supplied by EPrints Services.

http://www.eprints.org/eprints-3.4/

LICENSE

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

EPrints 3.4 and this file are released under the terms of the GNU Lesser General Public License version 3 as published by the Free Software Foundation unless otherwise stated.

EPrints 3.4 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 3.4. If not, see http://www.gnu.org/licenses/.

User Comments