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…')
(No difference)

Revision as of 11:05, 27 February 2012

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


API: Core API

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


NAME

EPrints::Apache::CRUD

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

User Comments


Content Negotiation

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

When GETing, your repository should support at least:

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

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

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

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

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

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

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

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

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

User Comments


URIs

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


METHODS

User Comments


repository

$repo = $crud->repository()

Returns the current repository.

User Comments


request

$r = $crud->request()

Returns the current Apache2::RequestUtil.

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


check_packaging

$rc = $crud->check_packaging()

Check the Packaging header is ok, if given.

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


content_negotiate_best_plugin

$plugin = $crud->content_negotiate_best_plugin( $r )

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

User Comments


SEE ALSO

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

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

User Comments


COPYRIGHT

User Comments