NDR API Documentation - deleteCollection

Delete the specified collection and all metadata and annotations that are part of the collection.

Request URL

http://ndr.nsdlib.org/api/deleteCollection/[handle]?purge=[purge]

where [handle] 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 collection and all metadata and annotations that are part of the collection.

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

Arguments

Parameters on Request URL:

[handle] (required) - the externally resolvable identifier of the collection (returned by addCollection)
[purge] (optional) - determines whether objects are permanently purged from the repository or marked as deleted
- purge=true - permanently and irrevocably remove the collection and all metadata and annotations that are part of the collection from the repository
- purge=false (default) - mark as deleted the collection and all metadata and annotations that are part of the collection

Request URL Example

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

http://ndr.nsdlib.org/api/deleteCollection/2200/20061212543

Below is an example of a request URL for purging (permanently and irrevocably removed) a collection identified by a handle and all metadata and annotations that are part of the collection from the NDR.

http://ndr.nsdlib.org/api/deleteCollection/2200/20061212543?purge=true

Behaviors

WARNING: Use of purge=true will permanently and irrevocably remove from the NDR the collection and all metadata and annotations that are part of the collection.

IMPORTANT NOTE: Deleting a collection cascades to deleting all metadata and annotations that are part of the collection.

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

Any collection 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 Collection will not appear in a listCollectionRecords request or listCollectionIdentifiers request unless the parameter state=deleted is part of the Request URL.
A getCollectionRecord request on a specific deleted Collection will display its contents.
A findCollections request will not match any deleted Collection (even if it otherwise matches) unless the find request explicitly declares a 'deleted' state as one if its match criteria.

Response

Structure of response:

handle - the externally resolvable identifier for the deleted Collection.

Common Errors

permissions do not allow the deleting of this collection
permissions do not allow the deleting of one or more metadata record or annotations that are part of this collection

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