NDR API Documentation - deleteAnnotation

Delete an annotation optionally cascading to annotations of the annotation being deleted.

Request URL

http://ndr.nsdlib.org/api/deleteAnnotation/[handle]?cascade=[cascade]&purge=[purge]

where [handle], [cascade], and [purge] are defined in the Arguments section.

Must be an HTTP POST request.

WARNING: Use of purge=true will permanently and irrevocably remove from the NDR the annotation and, if cascading, all related annotations.

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

Arguments

Parameters on Request URL:

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

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

Request URL Example

Below is an example of a request URL for deleting an annotation.

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

Behaviors

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

IMPORTANT NOTE: Deleting an annotation can optionally cascade to deleting all annotations that are related to the annotation being deleted. If cascade=false and related annotations exist, the delete will fail.

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

Any annotation 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 Annotation will not appear in a listAnnotations request or listAnnotationIdentifiers request unless the parameter state=deleted is part of the Request URL.
A getAnnotation request on a specific deleted Annotation will display its contents.

Response

Structure of response:

handle - the externally resolvable identifier for the annotation.

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