Difference between revisions of "API:EPrints/Apache/CRUD"
Line 33: | Line 33: | ||
<!-- Pod2Wiki=head_description --> | <!-- Pod2Wiki=head_description --> | ||
==DESCRIPTION== | ==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. | + | 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: | + | 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="Sword" href="https://myrepo/sword-app/servicedocument" /> | ||
Line 110: | Line 110: | ||
</div> | </div> | ||
<!-- Pod2Wiki=head_uri_layout --> | <!-- Pod2Wiki=head_uri_layout --> | ||
− | ===URI | + | ===URI Layout=== |
These URIs are relative to your EPrints HTTP/HTTPs root. | These URIs are relative to your EPrints HTTP/HTTPs root. | ||
Line 125: | Line 125: | ||
Requires authentication. | Requires authentication. | ||
− | GET a list of the eprints owned by the user. POST to create a new EPrint object. | + | <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%; '> | <div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | ||
Line 139: | Line 139: | ||
Requires authentication depending on user's privileges and object visibility. | Requires authentication depending on user's privileges and object visibility. | ||
− | 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 | + | <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%; '> | <div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | ||
Line 153: | Line 153: | ||
Requires authentication depending on user's privileges and object visibility. | 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. | + | <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%; '> | <div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | ||
Line 164: | Line 164: | ||
<!-- Pod2Wiki=head_http_content_negotiation --> | <!-- Pod2Wiki=head_http_content_negotiation --> | ||
===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. | + | <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 < | + | 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 | GET /id/eprint/23 HTTP/1.1 | ||
Accept: application/vnd.eprints.data+xml | Accept: application/vnd.eprints.data+xml | ||
− | Will search for an Export plugin that accepts objects of type | + | 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: | + | 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%; '> | <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 185: | ||
====/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 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. | + | 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%; '> | <div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | ||
Line 197: | Line 197: | ||
====/id/document/.../contents==== | ====/id/document/.../contents==== | ||
− | Requesting the < | + | 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%; '> | <div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | ||
Line 209: | Line 209: | ||
====/id/file/...==== | ====/id/file/...==== | ||
− | Requesting a {{API:PodLink|file=EPrints/DataObj/File|package_name=EPrints::DataObj::File|section=|text=File}} object with no < | + | 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%; '> | <div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | ||
Line 221: | Line 221: | ||
====POST /id/.../contents==== | ====POST /id/.../contents==== | ||
− | When creating new records via POST, content negotiation is performed against the Import plugins. | + | 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 | + | 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). | + | 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 237: | Line 237: | ||
====Content-Type header==== | ====Content-Type header==== | ||
− | If no < | + | 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%; '> | <div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | ||
Line 249: | Line 249: | ||
====Content-Disposition header==== | ====Content-Disposition header==== | ||
− | If the < | + | 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%; '> | <div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | ||
Line 260: | Line 260: | ||
<!-- 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 | + | 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><documents</tt>> 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%; '> | <div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | ||
Line 282: | Line 282: | ||
<!-- Pod2Wiki=head_upserting_objects_with_put --> | <!-- Pod2Wiki=head_upserting_objects_with_put --> | ||
===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 --> | ||
+ | ==CONSTANTS == | ||
+ | <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_scope_user_contents --> | ||
+ | ===CRUD_SCOPE_USER_CONTENTS=== | ||
+ | |||
+ | Restrict the scope of the CRUD request to user submitting content (i.e. ''/id/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_crud_scope_dataset --> | ||
+ | ===CRUD_SCOPE_DATASET=== | ||
+ | |||
+ | Restrict the scope of the CRUD request to a dataset (i.e. ''/id/FOO...''). | ||
+ | |||
+ | <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_scope_dataobj --> | ||
+ | ===CRUD_SCOPE_DATAOBJ=== | ||
+ | |||
+ | Restrict the scope of the CRUD request to a data object (i.e. ''/id/FOO/BAR''). | ||
+ | |||
+ | <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_scope_field --> | ||
+ | ===CRUD_SCOPE_FIELD=== | ||
+ | |||
+ | Restrict the scope of the CRUD request to a field of data object (i.e. ''/id/FOO/BAR/BAZ''). | ||
+ | |||
+ | <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_scope_contents --> | ||
+ | ===CRUD_SCOPE_CONTENTS=== | ||
+ | |||
+ | Restrict the scope of the CRUD request to the contents of data object (i.e. ''/id/FOO/BAR/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_crud_scope_servicedocument --> | ||
+ | ===CRUD_SCOPE_SERVICEDOCUMENT=== | ||
+ | |||
+ | Restrict the scope of the CRUD request to the 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%; '> | <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 291: | Line 372: | ||
<!-- Pod2Wiki=head_methods --> | <!-- Pod2Wiki=head_methods --> | ||
==METHODS== | ==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 --> | ||
+ | |||
+ | |||
+ | <!-- Pod2Wiki= --> | ||
+ | </div> | ||
+ | <!-- Pod2Wiki=head_constructor_methods --> | ||
+ | ===Constructor 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 --> | ||
+ | |||
+ | |||
+ | <!-- Pod2Wiki= --> | ||
+ | </div> | ||
+ | <!-- Pod2Wiki=item_new --> | ||
+ | ====new==== | ||
+ | |||
+ | $crud = EPrints::Apache::CRUD->new( %params ) | ||
+ | Return a new CRUD request using parameters given in <tt>%params</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_object_methods --> | ||
+ | ===Object Methods=== | ||
<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 299: | Line 411: | ||
</div> | </div> | ||
<!-- Pod2Wiki=item_repository --> | <!-- Pod2Wiki=item_repository --> | ||
− | ===repository=== | + | ====repository==== |
$repo = $crud->repository() | $repo = $crud->repository() | ||
Line 312: | Line 424: | ||
</div> | </div> | ||
<!-- Pod2Wiki=item_request --> | <!-- Pod2Wiki=item_request --> | ||
− | ===request=== | + | ====request==== |
$r = $crud->request() | $r = $crud->request() | ||
Line 325: | Line 437: | ||
</div> | </div> | ||
<!-- Pod2Wiki=item_method --> | <!-- Pod2Wiki=item_method --> | ||
− | ===method=== | + | ====method==== |
$method = $crud->method() | $method = $crud->method() | ||
Line 338: | Line 450: | ||
</div> | </div> | ||
<!-- Pod2Wiki=item_scope --> | <!-- Pod2Wiki=item_scope --> | ||
− | ===scope=== | + | ====scope==== |
$scope = $crud->scope() | $scope = $crud->scope() | ||
Line 351: | Line 463: | ||
</div> | </div> | ||
<!-- Pod2Wiki=item_dataset --> | <!-- Pod2Wiki=item_dataset --> | ||
− | ===dataset=== | + | ====dataset==== |
$dataset = $crud->dataset() | $dataset = $crud->dataset() | ||
Line 364: | Line 476: | ||
</div> | </div> | ||
<!-- Pod2Wiki=item_dataobj --> | <!-- Pod2Wiki=item_dataobj --> | ||
− | ===dataobj=== | + | ====dataobj==== |
$dataobj = $crud->dataobj() | $dataobj = $crud->dataobj() | ||
Line 377: | Line 489: | ||
</div> | </div> | ||
<!-- Pod2Wiki=item_field --> | <!-- Pod2Wiki=item_field --> | ||
− | ===field=== | + | ====field==== |
$field = $crud->field() | $field = $crud->field() | ||
Line 390: | Line 502: | ||
</div> | </div> | ||
<!-- Pod2Wiki=item_headers --> | <!-- Pod2Wiki=item_headers --> | ||
− | ===headers=== | + | ====headers==== |
$headers = $crud->headers() | $headers = $crud->headers() | ||
Line 403: | Line 515: | ||
</div> | </div> | ||
<!-- Pod2Wiki=item_options --> | <!-- Pod2Wiki=item_options --> | ||
− | ===options=== | + | ====options==== |
@verbs = $crud->options() | @verbs = $crud->options() | ||
Line 416: | Line 528: | ||
</div> | </div> | ||
<!-- Pod2Wiki=item_plugin --> | <!-- Pod2Wiki=item_plugin --> | ||
− | ===plugin=== | + | ====plugin==== |
$plugin = $crud->plugin() | $plugin = $crud->plugin() | ||
Line 429: | Line 541: | ||
</div> | </div> | ||
<!-- Pod2Wiki=item_is_write --> | <!-- Pod2Wiki=item_is_write --> | ||
− | ===is_write=== | + | ====is_write==== |
$bool = $crud->is_write() | $bool = $crud->is_write() | ||
− | Returns true if the request is not a read-only method. | + | Returns <tt>true</tt> 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%; '> | <div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | ||
Line 442: | Line 554: | ||
</div> | </div> | ||
<!-- Pod2Wiki=item_accept_type --> | <!-- Pod2Wiki=item_accept_type --> | ||
− | ===accept_type=== | + | ====accept_type==== |
$accept_type = $crud->accept_type() | $accept_type = $crud->accept_type() | ||
Line 455: | Line 567: | ||
</div> | </div> | ||
<!-- Pod2Wiki=item_check_packaging --> | <!-- Pod2Wiki=item_check_packaging --> | ||
− | ===check_packaging=== | + | ====check_packaging==== |
$rc = $crud->check_packaging() | $rc = $crud->check_packaging() | ||
Line 468: | Line 580: | ||
</div> | </div> | ||
<!-- Pod2Wiki=item_resolve_relations --> | <!-- Pod2Wiki=item_resolve_relations --> | ||
− | ===resolve_relations=== | + | ====resolve_relations==== |
$dataobj = $crud->resolve_relations( $dataobj [, @relations ] ) | $dataobj = $crud->resolve_relations( $dataobj [, @relations ] ) | ||
− | Resolve the relation path from $dataobj and return the resulting | + | Resolve the relation path from <tt>$dataobj</tt> and return the resulting data object. |
− | Returns undef if there is no such related object. | + | Returns c<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%; '> | <div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | ||
Line 483: | Line 595: | ||
</div> | </div> | ||
<!-- Pod2Wiki=item_authen --> | <!-- Pod2Wiki=item_authen --> | ||
− | ===authen=== | + | ====authen==== |
$rc = $crud->authen | $rc = $crud->authen | ||
Line 496: | Line 608: | ||
</div> | </div> | ||
<!-- Pod2Wiki=item_authz --> | <!-- Pod2Wiki=item_authz --> | ||
− | ===authz=== | + | ====authz==== |
$rc = $crud->authz | $rc = $crud->authz | ||
Line 509: | Line 621: | ||
</div> | </div> | ||
<!-- Pod2Wiki=item_parse_input --> | <!-- Pod2Wiki=item_parse_input --> | ||
− | ===parse_input=== | + | ====parse_input==== |
$list = $crud->parse_input( $plugin, $f [, %params ] ) | $list = $crud->parse_input( $plugin, $f [, %params ] ) | ||
− | Parse the content submitted by the user using the given $plugin. | + | Parse the content submitted by the user using the given <tt>$plugin</tt>. <tt>$f</tt> is called by c<epdata_to_dataobj> to convert EPrints data markup to a data object. <tt>%params</tt> are passed to the plugin's <tt>input_fh</tt> method. |
− | Returns undef on error. | + | Returns <tt>undef</tt> on error. Otherwise returns an [[API:EPrints/List|EPrints::List]] of data objects. |
<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 524: | Line 636: | ||
</div> | </div> | ||
<!-- Pod2Wiki=item_create_dataobj --> | <!-- Pod2Wiki=item_create_dataobj --> | ||
− | ===create_dataobj=== | + | ====create_dataobj==== |
$dataobj = $crud->create_dataobj( $owner, $epdata ) | $dataobj = $crud->create_dataobj( $owner, $epdata ) | ||
Creates data object as user $owner with metadata from $epdata | Creates data object as user $owner with metadata from $epdata | ||
− | Returns an [[API:EPrints/DataObj|EPrints::DataObj]] | + | 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%; '> | <div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | ||
Line 539: | Line 651: | ||
</div> | </div> | ||
<!-- Pod2Wiki=item_import_plugins --> | <!-- Pod2Wiki=item_import_plugins --> | ||
− | ===import_plugins=== | + | ====import_plugins==== |
@plugins = $crud->import_plugins( [ %params ] ) | @plugins = $crud->import_plugins( [ %params ] ) | ||
− | Returns all matching import plugins against %params ordered by descending | + | Returns all matching import plugins against <tt>%params</tt> ordered by descending <tt>q</tt> 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 552: | Line 664: | ||
</div> | </div> | ||
<!-- Pod2Wiki=item_export_plugins --> | <!-- Pod2Wiki=item_export_plugins --> | ||
− | ===export_plugins=== | + | ====export_plugins==== |
@plugins = $crud->export_plugins( [ %params ] ) | @plugins = $crud->export_plugins( [ %params ] ) | ||
− | Returns all matching export plugins against %params ordered by descending | + | Returns all matching export plugins against <tt>%params</tt> ordered by descending <tt>q</tt> 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 565: | Line 677: | ||
</div> | </div> | ||
<!-- Pod2Wiki=item_content_negotiate_best_plugin --> | <!-- Pod2Wiki=item_content_negotiate_best_plugin --> | ||
− | ===content_negotiate_best_plugin=== | + | ====content_negotiate_best_plugin==== |
$plugin = $crud->content_negotiate_best_plugin() | $plugin = $crud->content_negotiate_best_plugin() | ||
− | Work out the best plugin to export/update an object based on the client | + | 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%; '> | <div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | ||
Line 578: | Line 690: | ||
</div> | </div> | ||
<!-- Pod2Wiki=item_crud --> | <!-- Pod2Wiki=item_crud --> | ||
− | ===crud=== | + | ====crud==== |
EPrints::Apache::CRUD( $media_range ) | 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. | + | Takes the <tt>$media_range</tt> 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%; '> | <div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | ||
Line 591: | Line 703: | ||
</div> | </div> | ||
<!-- Pod2Wiki=item_handler --> | <!-- Pod2Wiki=item_handler --> | ||
− | ===handler=== | + | ====handler==== |
$rc = $crud->handler | $rc = $crud->handler | ||
Line 606: | Line 718: | ||
</div> | </div> | ||
<!-- Pod2Wiki=item_delete --> | <!-- Pod2Wiki=item_delete --> | ||
− | ===delete=== | + | ====delete==== |
$rc = $crud->DELETE() | $rc = $crud->DELETE() | ||
− | Handle DELETE requests. | + | Handle <tt>DELETE</tt> requests. |
<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 619: | Line 731: | ||
</div> | </div> | ||
<!-- Pod2Wiki=item_http_method_not_allowed --> | <!-- Pod2Wiki=item_http_method_not_allowed --> | ||
− | ===http_method_not_allowed=== | + | ====http_method_not_allowed==== |
HTTP_METHOD_NOT_ALLOWED | HTTP_METHOD_NOT_ALLOWED | ||
− | Can't perform DELETE on ''/id/contents''. | + | Can't perform <tt>DELETE</tt> 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%; '> | <div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | ||
Line 632: | Line 744: | ||
</div> | </div> | ||
<!-- Pod2Wiki=item_http_not_found --> | <!-- Pod2Wiki=item_http_not_found --> | ||
− | ===http_not_found=== | + | ====http_not_found==== |
HTTP_NOT_FOUND | HTTP_NOT_FOUND | ||
Line 645: | Line 757: | ||
</div> | </div> | ||
<!-- Pod2Wiki=item_http_conflict --> | <!-- Pod2Wiki=item_http_conflict --> | ||
− | ===http_conflict=== | + | ====http_conflict==== |
HTTP_CONFLICT | HTTP_CONFLICT | ||
Line 658: | Line 770: | ||
</div> | </div> | ||
<!-- Pod2Wiki=item_http_no_content --> | <!-- Pod2Wiki=item_http_no_content --> | ||
− | ===http_no_content=== | + | ====http_no_content==== |
HTTP_NO_CONTENT | HTTP_NO_CONTENT | ||
Line 671: | Line 783: | ||
</div> | </div> | ||
<!-- Pod2Wiki=item_get --> | <!-- Pod2Wiki=item_get --> | ||
− | ===get=== | + | ====get==== |
$rc = $crud->GET( [ $owner ] ) | $rc = $crud->GET( [ $owner ] ) | ||
− | Handle GET requests. | + | Handle <tt>GET</tt> requests. |
<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 684: | Line 796: | ||
</div> | </div> | ||
<!-- Pod2Wiki=item_http_no_content --> | <!-- Pod2Wiki=item_http_no_content --> | ||
− | ===http_no_content=== | + | ====http_no_content==== |
HTTP_NO_CONTENT | HTTP_NO_CONTENT | ||
− | No sub-objects in | + | No sub-objects in ''/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%; '> | <div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | ||
Line 697: | Line 809: | ||
</div> | </div> | ||
<!-- Pod2Wiki=item_http_not_acceptable --> | <!-- Pod2Wiki=item_http_not_acceptable --> | ||
− | ===http_not_acceptable=== | + | ====http_not_acceptable==== |
HTTP_NOT_ACCEPTABLE | HTTP_NOT_ACCEPTABLE | ||
− | More than one sub-object in | + | More than one sub-object in ''/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%; '> | <div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | ||
Line 710: | Line 822: | ||
</div> | </div> | ||
<!-- Pod2Wiki=item_http_unsupported_media_type --> | <!-- Pod2Wiki=item_http_unsupported_media_type --> | ||
− | ===http_unsupported_media_type=== | + | ====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 < | + | No {{API:PodLink|file=EPrints/Plugin/Export|package_name=EPrints::Plugin::Export|section=|text=Export}} plugin matches the <tt>Accept</tt> 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%; '> | <div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | ||
Line 723: | Line 835: | ||
</div> | </div> | ||
<!-- Pod2Wiki=item_http_see_other --> | <!-- Pod2Wiki=item_http_see_other --> | ||
− | ===http_see_other=== | + | ====http_see_other==== |
HTTP_SEE_OTHER | HTTP_SEE_OTHER | ||
Line 736: | Line 848: | ||
</div> | </div> | ||
<!-- Pod2Wiki=item_http_not_found --> | <!-- Pod2Wiki=item_http_not_found --> | ||
− | ===http_not_found=== | + | ====http_not_found==== |
HTTP_NOT_FOUND | HTTP_NOT_FOUND | ||
Line 749: | Line 861: | ||
</div> | </div> | ||
<!-- Pod2Wiki=item_http_ok --> | <!-- Pod2Wiki=item_http_ok --> | ||
− | ===http_ok=== | + | ====http_ok==== |
HTTP_OK | HTTP_OK | ||
Line 762: | Line 874: | ||
</div> | </div> | ||
<!-- Pod2Wiki=item_post --> | <!-- Pod2Wiki=item_post --> | ||
− | ===post=== | + | ====post==== |
$rc = $crud->POST( [ $owner ] ) | $rc = $crud->POST( [ $owner ] ) | ||
− | Handle POST requests. | + | Handle <tt>POST</tt> requests. |
<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 775: | Line 887: | ||
</div> | </div> | ||
<!-- Pod2Wiki=item_http_method_not_allowed --> | <!-- Pod2Wiki=item_http_method_not_allowed --> | ||
− | ===http_method_not_allowed=== | + | ====http_method_not_allowed==== |
HTTP_METHOD_NOT_ALLOWED | HTTP_METHOD_NOT_ALLOWED | ||
− | Can only POST to | + | Can only POST to ''/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%; '> | <div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | ||
Line 788: | Line 900: | ||
</div> | </div> | ||
<!-- Pod2Wiki=item_http_bad_request --> | <!-- Pod2Wiki=item_http_bad_request --> | ||
− | ===http_bad_request=== | + | ====http_bad_request==== |
HTTP_BAD_REQUEST | HTTP_BAD_REQUEST | ||
− | No plugin for the SWORD < | + | No plugin for the SWORD <tt>Packaging</tt> header. |
<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 801: | Line 913: | ||
</div> | </div> | ||
<!-- Pod2Wiki=item_http_created --> | <!-- Pod2Wiki=item_http_created --> | ||
− | ===http_created=== | + | ====http_created==== |
HTTP_CREATED | HTTP_CREATED | ||
Line 814: | Line 926: | ||
</div> | </div> | ||
<!-- Pod2Wiki=item_put --> | <!-- Pod2Wiki=item_put --> | ||
− | ===put=== | + | ====put==== |
$rc = $crud->PUT( [ $owner ] ) | $rc = $crud->PUT( [ $owner ] ) | ||
− | Handle PUT requests. | + | Handle <tt>PUT</tt> requests. |
<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 827: | Line 939: | ||
</div> | </div> | ||
<!-- Pod2Wiki=item_http_unsupported_media_type --> | <!-- Pod2Wiki=item_http_unsupported_media_type --> | ||
− | ===http_unsupported_media_type=== | + | ====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 < | + | No {{API:PodLink|file=EPrints/Plugin/Import|package_name=EPrints::Plugin::Import|section=|text=Import}} plugin matched the <tt>Content-Type</tt> 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%; '> | <div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | ||
Line 840: | Line 952: | ||
</div> | </div> | ||
<!-- Pod2Wiki=item_http_range_not_satisfiable --> | <!-- Pod2Wiki=item_http_range_not_satisfiable --> | ||
− | ===http_range_not_satisfiable=== | + | ====http_range_not_satisfiable==== |
HTTP_RANGE_NOT_SATISFIABLE | HTTP_RANGE_NOT_SATISFIABLE | ||
− | < | + | <tt>Range</tt> header is invalid or unsupported for the 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%; '> | <div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | ||
Line 853: | Line 965: | ||
</div> | </div> | ||
<!-- Pod2Wiki=item_http_forbidden --> | <!-- Pod2Wiki=item_http_forbidden --> | ||
− | ===http_forbidden=== | + | ====http_forbidden==== |
HTTP_FORBIDDEN | HTTP_FORBIDDEN | ||
− | User does not have permission to create/update the | + | User does not have permission to create/update 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%; '> | <div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | ||
Line 866: | Line 978: | ||
</div> | </div> | ||
<!-- Pod2Wiki=item_http_created --> | <!-- Pod2Wiki=item_http_created --> | ||
− | ===http_created=== | + | ====http_created==== |
HTTP_CREATED | HTTP_CREATED | ||
Line 879: | Line 991: | ||
</div> | </div> | ||
<!-- Pod2Wiki=item_http_no_content --> | <!-- Pod2Wiki=item_http_no_content --> | ||
− | ===http_no_content=== | + | ====http_no_content==== |
HTTP_NO_CONTENT | HTTP_NO_CONTENT | ||
Line 892: | Line 1,004: | ||
</div> | </div> | ||
<!-- Pod2Wiki=item_put_contents --> | <!-- Pod2Wiki=item_put_contents --> | ||
− | ===put_contents=== | + | ====put_contents==== |
$rc = $crud->PUT_contents( [ $owner ] ) | $rc = $crud->PUT_contents( [ $owner ] ) | ||
− | Equivalent to <tt>DELETE /id/.../contents</tt> then <tt>POST /id/.../contents</tt>. | + | 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]]. | See [[API:EPrints/Apache/CRUD#DELETE|DELETE]] and [[API:EPrints/Apache/CRUD#POST|POST]]. | ||
Line 907: | Line 1,019: | ||
</div> | </div> | ||
<!-- Pod2Wiki=item_metadata_relevant --> | <!-- Pod2Wiki=item_metadata_relevant --> | ||
− | ===metadata_relevant=== | + | ====metadata_relevant==== |
$crud->metadata_relevant( $file ) | $crud->metadata_relevant( $file ) | ||
− | Test and if suitable use $file as metadata source to | + | Test and if suitable use <tt>$file</tt> as metadata source to update 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%; '> | <div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | ||
Line 920: | Line 1,032: | ||
</div> | </div> | ||
<!-- Pod2Wiki=item_servicedocument --> | <!-- Pod2Wiki=item_servicedocument --> | ||
− | ===servicedocument=== | + | ====servicedocument==== |
$crud->servicedocument | $crud->servicedocument | ||
− | + | Generate 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%; '> | <div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | ||
Line 933: | Line 1,045: | ||
</div> | </div> | ||
<!-- Pod2Wiki=item_on_behalf_of --> | <!-- Pod2Wiki=item_on_behalf_of --> | ||
− | ===on_behalf_of=== | + | ====on_behalf_of==== |
$rc = $crud->on_behalf_of( $user ) | $rc = $crud->on_behalf_of( $user ) | ||
− | Submit CRUD request on behalf | + | Submit CRUD request on behalf of another user. |
− | Returns HTTPS response code based on | + | Returns HTTPS response code based on whether 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%; '> | <div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | ||
Line 948: | Line 1,060: | ||
</div> | </div> | ||
<!-- Pod2Wiki=item_is_true --> | <!-- Pod2Wiki=item_is_true --> | ||
− | ===is_true=== | + | ====is_true==== |
$boolean = EPrints::Apache::Crud::is_true( $header ) | $boolean = EPrints::Apache::Crud::is_true( $header ) | ||
− | Tests if $header attribute is true. | + | Tests if <tt>$header</tt> attribute is <tt>true</tt>. |
<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 961: | Line 1,073: | ||
</div> | </div> | ||
<!-- Pod2Wiki=item_is_false --> | <!-- Pod2Wiki=item_is_false --> | ||
− | ===is_false=== | + | ====is_false==== |
$boolean = EPrints::Apache::Crud::is_false( $header ) | $boolean = EPrints::Apache::Crud::is_false( $header ) | ||
− | Tests if $header attribute is false. | + | Tests if <tt>$header</tt> attribute is <tt>false</tt>. |
<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 974: | Line 1,086: | ||
</div> | </div> | ||
<!-- Pod2Wiki=item_is_file_ok --> | <!-- Pod2Wiki=item_is_file_ok --> | ||
− | ===is_file_ok=== | + | ====is_file_ok==== |
$boolean = $crud->is_file_ok( $epdata ) | $boolean = $crud->is_file_ok( $epdata ) | ||
− | Tests if files with $epdata were uploaded with corruption. | + | Tests if files with <tt>$epdata</tt> 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%; '> | <div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '> | ||
Line 987: | Line 1,099: | ||
</div> | </div> | ||
<!-- Pod2Wiki=item_process_headers --> | <!-- Pod2Wiki=item_process_headers --> | ||
− | ===process_headers=== | + | ====process_headers==== |
$boolean = $crud->process_headers | $boolean = $crud->process_headers | ||
Line 1,000: | Line 1,112: | ||
</div> | </div> | ||
<!-- Pod2Wiki=item_$boolean --> | <!-- Pod2Wiki=item_$boolean --> | ||
− | ===$boolean=== | + | ====$boolean==== |
$boolean = $crud->( %opts ) | $boolean = $crud->( %opts ) | ||
− | Generate SWORD error documents based on provided %opts. | + | Generate SWORD error documents based on provided <tt>%opts</tt>. |
<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 1,013: | Line 1,125: | ||
</div> | </div> | ||
<!-- Pod2Wiki=item_plugin_error --> | <!-- Pod2Wiki=item_plugin_error --> | ||
− | ===plugin_error=== | + | ====plugin_error==== |
$boolean = $crud->plugin_error( $plugin, $messages ) | $boolean = $crud->plugin_error( $plugin, $messages ) | ||
− | Generate error message for import $plugin used with $messages provided. | + | Generate error message for import <tt>$plugin</tt> used with <tt>$messages</tt> provided. |
<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 1,026: | Line 1,138: | ||
</div> | </div> | ||
<!-- Pod2Wiki=item_generate_error_document --> | <!-- Pod2Wiki=item_generate_error_document --> | ||
− | ===generate_error_document=== | + | ====generate_error_document==== |
$error_document = EPrints::Apache::Crud::generate_error_document( $repo, %opts ) | $error_document = EPrints::Apache::Crud::generate_error_document( $repo, %opts ) | ||
− | Return error document for [[API:EPrints/Repository|EPrints::Repository]] $repo using options | + | Return error document for [[API:EPrints/Repository|EPrints::Repository]] <tt>$repo</tt> using options from <tt>%opts</tt>. |
<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 1,039: | Line 1,151: | ||
</div> | </div> | ||
<!-- Pod2Wiki=item_send_response --> | <!-- Pod2Wiki=item_send_response --> | ||
− | ===send_response=== | + | ====send_response==== |
$rc = $crud->send_response( $status, $content_type, $content ) | $rc = $crud->send_response( $status, $content_type, $content ) | ||
− | Output response to CRUD request with HTTP status code $status, content type $content_type. | + | Output response to CRUD request with HTTP status code <tt>$status</tt>, content type <tt>$content_type</tt>. |
− | Returns HTTP response code OK. | + | Returns HTTP response code <tt>OK</tt>. |
<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%; '> |
Revision as of 15:13, 15 March 2023
EPrints 3 Reference: Directory Structure - Metadata Fields - Repository Configuration - XML Config Files - XML Export Format - EPrints data structure - Core API - Data Objects
Latest Source Code (3.4, 3.3) | Revision Log | Before editing this page please read Pod2Wiki
This feature requires EPrints version 3.3.0 or later |
Contents
- 1 NAME
- 2 SYNOPSIS
- 3 DESCRIPTION
- 4 CONSTANTS
- 5 METHODS
- 5.1 Constructor Methods
- 5.2 Object Methods
- 5.2.1 repository
- 5.2.2 request
- 5.2.3 method
- 5.2.4 scope
- 5.2.5 dataset
- 5.2.6 dataobj
- 5.2.7 field
- 5.2.8 headers
- 5.2.9 options
- 5.2.10 plugin
- 5.2.11 is_write
- 5.2.12 accept_type
- 5.2.13 check_packaging
- 5.2.14 resolve_relations
- 5.2.15 authen
- 5.2.16 authz
- 5.2.17 parse_input
- 5.2.18 create_dataobj
- 5.2.19 import_plugins
- 5.2.20 export_plugins
- 5.2.21 content_negotiate_best_plugin
- 5.2.22 crud
- 5.2.23 handler
- 5.2.24 delete
- 5.2.25 http_method_not_allowed
- 5.2.26 http_not_found
- 5.2.27 http_conflict
- 5.2.28 http_no_content
- 5.2.29 get
- 5.2.30 http_no_content
- 5.2.31 http_not_acceptable
- 5.2.32 http_unsupported_media_type
- 5.2.33 http_see_other
- 5.2.34 http_not_found
- 5.2.35 http_ok
- 5.2.36 post
- 5.2.37 http_method_not_allowed
- 5.2.38 http_bad_request
- 5.2.39 http_created
- 5.2.40 put
- 5.2.41 http_unsupported_media_type
- 5.2.42 http_range_not_satisfiable
- 5.2.43 http_forbidden
- 5.2.44 http_created
- 5.2.45 http_no_content
- 5.2.46 put_contents
- 5.2.47 metadata_relevant
- 5.2.48 servicedocument
- 5.2.49 on_behalf_of
- 5.2.50 is_true
- 5.2.51 is_false
- 5.2.52 is_file_ok
- 5.2.53 process_headers
- 5.2.54 $boolean
- 5.2.55 plugin_error
- 5.2.56 generate_error_document
- 5.2.57 send_response
- 6 SEE ALSO
- 7 COPYRIGHT
NAME
EPrints::Apache::CRUD - Create, read, update and delete via HTTP
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 ...
You can find more examples in the tests/84_sword.t unit test.
URI Layout
These URIs are relative to your EPrints HTTP/HTTPs root.
/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.
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:
/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.
/id/document/.../contents
Requesting the /contents of a Document object will return the content of the document's main file.
/id/file/...
Requesting a File object with no Accept header (or */*) will return the file's content.
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).
Content-Type header
If no Content-Type header is given the MIME type defaults to application/octet-stream for POSTs and PUTs.
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.
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.
PUT/DELETE from Javascript
Upserting objects with PUT
CONSTANTS
CRUD_SCOPE_USER_CONTENTS
Restrict the scope of the CRUD request to user submitting content (i.e. /id/content).
CRUD_SCOPE_DATASET
Restrict the scope of the CRUD request to a dataset (i.e. /id/FOO...).
CRUD_SCOPE_DATAOBJ
Restrict the scope of the CRUD request to a data object (i.e. /id/FOO/BAR).
CRUD_SCOPE_FIELD
Restrict the scope of the CRUD request to a field of data object (i.e. /id/FOO/BAR/BAZ).
CRUD_SCOPE_CONTENTS
Restrict the scope of the CRUD request to the contents of data object (i.e. /id/FOO/BAR/contents).
CRUD_SCOPE_SERVICEDOCUMENT
Restrict the scope of the CRUD request to the service document.
METHODS
Constructor Methods
new
$crud = EPrints::Apache::CRUD->new( %params )
Return a new CRUD request using parameters given in %params.
Object 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.
resolve_relations
$dataobj = $crud->resolve_relations( $dataobj [, @relations ] )
Resolve the relation path from $dataobj and return the resulting data object.
Returns c<undef> if there is no such related object.
authen
$rc = $crud->authen
Returns HTTP code based of whether CRUD request can be authenticated.
authz
$rc = $crud->authz
Returns HTTP code based of whether CRUD request can be authorized.
parse_input
$list = $crud->parse_input( $plugin, $f [, %params ] )
Parse the content submitted by the user using the given $plugin. $f is called by c<epdata_to_dataobj> to convert EPrints data markup to a data object. %params are passed to the plugin's input_fh method.
Returns undef on error. Otherwise returns an EPrints::List of data objects.
create_dataobj
$dataobj = $crud->create_dataobj( $owner, $epdata )
Creates data object as user $owner with metadata from $epdata
Returns an EPrints::DataObj.
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.
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.
handler
$rc = $crud->handler
Handler of CRUD requests.
Returns HTTP response code.
delete
$rc = $crud->DELETE()
Handle DELETE requests.
http_method_not_allowed
HTTP_METHOD_NOT_ALLOWED
Can't perform DELETE on /id/contents.
http_not_found
HTTP_NOT_FOUND
No such object.
http_conflict
HTTP_CONFLICT
Lock conflict with another user.
http_no_content
HTTP_NO_CONTENT
Successfully removed the object.
get
$rc = $crud->GET( [ $owner ] )
Handle GET requests.
http_no_content
HTTP_NO_CONTENT
No sub-objects in /id/.../contents.
http_not_acceptable
HTTP_NOT_ACCEPTABLE
More than one sub-object in /id/.../contents.
http_unsupported_media_type
HTTP_UNSUPPORTED_MEDIA_TYPE
No Export plugin matches the Accept header/object type.
http_see_other
HTTP_SEE_OTHER
Redirect to a non-CRUD EPrints page.
http_not_found
HTTP_NOT_FOUND
Object not found.
http_ok
HTTP_OK
Object outputted successfully.
post
$rc = $crud->POST( [ $owner ] )
Handle POST requests.
http_method_not_allowed
HTTP_METHOD_NOT_ALLOWED
Can only POST to /id/.../contents.
http_bad_request
HTTP_BAD_REQUEST
No plugin for the SWORD Packaging header.
http_created
HTTP_CREATED
Object(s) successfully created.
put
$rc = $crud->PUT( [ $owner ] )
Handle PUT requests.
http_unsupported_media_type
HTTP_UNSUPPORTED_MEDIA_TYPE
No Import plugin matched the Content-Type header/object type.
http_range_not_satisfiable
HTTP_RANGE_NOT_SATISFIABLE
Range header is invalid or unsupported for the object type.
http_forbidden
HTTP_FORBIDDEN
User does not have permission to create/update the object.
http_created
HTTP_CREATED
Object was successfully created.
http_no_content
HTTP_NO_CONTENT
Object was successfully updated.
put_contents
$rc = $crud->PUT_contents( [ $owner ] )
Equivalent to DELETE /id/.../contents then POST /id/.../contents.
metadata_relevant
$crud->metadata_relevant( $file )
Test and if suitable use $file as metadata source to update the associated EPrints::DataObj::EPrint.
servicedocument
$crud->servicedocument
Generate response containing CRUD service document.
on_behalf_of
$rc = $crud->on_behalf_of( $user )
Submit CRUD request on behalf of another user.
Returns HTTPS response code based on whether request on behalf of is permitted.
is_true
$boolean = EPrints::Apache::Crud::is_true( $header )
Tests if $header attribute is true.
is_false
$boolean = EPrints::Apache::Crud::is_false( $header )
Tests if $header attribute is false.
is_file_ok
$boolean = $crud->is_file_ok( $epdata )
Tests if files with $epdata were uploaded with corruption.
process_headers
$boolean = $crud->process_headers
Process headers of CRUD request
$boolean
$boolean = $crud->( %opts )
Generate SWORD error documents based on provided %opts.
plugin_error
$boolean = $crud->plugin_error( $plugin, $messages )
Generate error message for import $plugin used with $messages provided.
generate_error_document
$error_document = EPrints::Apache::Crud::generate_error_document( $repo, %opts )
Return error document for EPrints::Repository $repo using options from %opts.
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.
SEE ALSO
http://en.wikipedia.org/wiki/Create,_read,_update_and_delete
http://en.wikipedia.org/wiki/Content_negotiation
COPYRIGHT
© Copyright 2000-2024 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/.