NDR API Documentation - deleteMetadataRecord

Delete a metadata record about a resource optionally cascading to annotations.

Request URL

http://ndr.nsdlib.org/api/deleteMetadataRecord/[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 metadata record and all annotations that are related to the metadata record.

NOTE: The agent making this request must have permissions sufficient to delete the metadata record and, if cascading, all annotations for this request to complete successfully.

Arguments

Parameters on Request URL:

[handle] (optional) - the externally resolvable identifier of a metadata record for a resource (returned by addMetadataRecord)
[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 metadata record and, if cascading, all annotations that are related to this metadata record from the repository
- purge=false (default) - mark as deleted the metadata record and, if cascading, all annotations that are related to this metadata record

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

Request URL Example

Below is an example of a request URL for deleting a metadata record.

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

Behaviors

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

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

By default, 'deleting' a metadata record in the NDR via deleteMetadataRecord does not actually remove the metadata record and related objects from the NDR; it changes the objects' states to 'Deleted'. In this case, deleteMetadataRecord 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 metadata record and related objects are permanently and irrevocably removed from the NDR.

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

A deleted Metadata Record will not appear in a listMetadataRecords request or listMetadataIdentifiers request unless the parameter state=deleted is part of the Request URL.
A getMetadataRecord request on a specific deleted Metadata Record will display its contents.

Response

Structure of response:

handle - the externally resolvable identifier for the Metadata.

Common Errors

permissions do not allow the deleting of this metadata record
cascade=true, but permissions do not allow the deleting of one or more annotations that are associated with this metadata record
cascade=false and annotations are associated with this metadata record

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/deleteMetadataRecord/[handle]?cascade=[cascade]&purge=[purge]</requestURL>
  
  <resultData>
    <handle>2200/20061212543</handle>
  <resultData>
</NSDLDataRespository>