TNS Internal:NDR/API/2.0/specification/deleteResource

From NSDLWiki

Jump to: navigation, search


 NDR Project Documentation   Conceptual Framework   v1.0 NDR-API Index   v2.0 NDR-API Index   Model 

Under Construction
Proposed method for inclusion in NDR/API 2.x.

Please provide feedback and comments in the NSDL Data Repository (NDR) API 2.0 Forum of the NSDL Community Forums.


NDR API Documentation - deleteResource

Delete a resource registration from the NDR optionally cascading to metadata records and annotations.



Request URL

http://ndr.nsdlib.org/api/deleteResource/[handle]?cascade=[cascade]&purge=[purge]
where [handle][cascade], and [purge] are defined in the Arguments section.
May be an HTTP GET or POST request.
WARNING: Use of purge=true will permanently and irrevocably remove from the NDR the resource registration and all metadata and annotations that are related to the resource registration.

NOTE: The agent making this request must have permissions sufficient to delete the resource registration and all related metadata records and annotations for this request to complete successfully.

NOTE: A resource registration will not be deleted if any metadata records or annotations would continue to be related to the resource registration after the delete process is completed.
Arguments

Parameters on Request URL:

  • [handle] (required) - the externally resolvable identifier of the resource
  • [cascade] (optional) - cascade deletes to annotations related to this metadata record
    • cascade=true - cascade to annotations
    • cascade=false (default) - do not cascade NOTE: An error message will be returned if annotations exist related to this metadata record.
  • [purge] (optional) - determines whether objects are permanently purged from the repository or marked as deleted
    • purge=true - permanently and irrevocably remove the resource and all metadata and annotations that are associated with the resource from the repository
    • purge=false (default) - mark as deleted the resource and all metadata and annotations that are associated with the resource

NOTE: The agent making this request must have permissions sufficient to delete the registration and all related metadata records and annotations for this request to complete successfully.


Request URL Example

Below is an example of a request URL for deleting (mark as deleted) a resource identified by a handle and all metadata and annotations that are associated with the resource from the NDR.

http://ndr.nsdlib.org/api/deleteResource/2200/20061212543?cascade=true

Below is an example of a request URL for purging (permanently and irrevocably removed) a resource identified by a handle and all metadata and annotations associated with the resource from the NDR.

http://ndr.nsdlib.org/api/deleteResource/2200/20061212543?cascade=true&purge=true



Behaviors

WARNING: Use of purge=true will permanently and irrevocably remove from the NDR the resource registration and, if cascading, all metadata and annotations that are related to the resource registration.


IMPORTANT NOTE: Deleting a resource registration can optionally cascade to deleting all metadata and annotations that are related to the resource registration. If cascade=false and related metadata records and annotations exist, the delete will fail.


By default, 'deleting' a resource registration in the NDR via deleteResource does not actually remove the resource registration and related objects from the NDR; it changes the objects' states to 'Deleted'. In this case, deleteResource is a non-destructive operation. No data is lost upon delete, and any deleted object can be undeleted as desired. If purge=true parameter is part of the request, then the resource registration and related objects are permanently and irrevocably removed from the NDR.

Any resource registration and related objects that are marked as deleted are invisible to all API requests unless explicitly referenced by handle or state. For example:


Response

Structure of response:

  • handle - the externally resolvable identifier for the Resource Registration.


Common Errors

  • permissions do not allow the deleting of this resource registration
  • cascade=true, but permissions do not allow the deleting of one or more metadata records that point to this resource registration
  • cascade=false and metadata records point to this resource registration


Response Example

Below is an example response for this request.

<?xml version="1.0" encoding="UTF-8"?>
<NSDLDataRepository schemaVersion="1.00.000" 
    xmlns="http://ns.nsdlib.org/ndr/response_v2.00/"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://ns.nsdlib.org/ndr/response_v2.00/ http://ns.nsdlib.org/schemas/ndr/response_v2.00.xsd">
  <responseTime>2006-04-10T18:07:53Z</responseTime>
  <requestURL>http://ndr.nsdlib.org/api/deleteResource/[handle]?cascade=[cascade]&purge=[purge]</requestURL>
  
  <resultData>
    <handle>2200/20061212543</handle>
  <resultData>
</NSDLDataRespository>



API Links:


Additional Links Related to This Call:

Personal tools