Resource Upload / Edit API

NOTE This requires a user to be part of the tDAR API Group. Please contact Digital Antiquity staff (info@digitalantiquity.org) to be added to this group.

The API Controller uses simple HTTP posts to add records to tDAR. Records can be passed via the post with files as multi-part attachments.

Limitations:

cannot assign rights to records directly (only through the use of a Shared Collection)
cannot delete records

Examples and Tools:

JAVA: The CommandLine API Tool and the Client API (part of the core package; maven repo: https://dev.tdar.org/archiva/repository/internal ; groupId: org.tdar ; artifactId: core and artifactId: utils; can be used to help )
Ruby: The Simple Uploader script provides a very basic example of connecting to tDAR and uploading an XML record

URL: http://core.tdar.org/api/upload
Method: POST

Parameters:

Parameter	Optional	Note
record	no	This should contain the XML representation of the TDAR Record
projectId	yes	Use this to override the project association for a given record
uploadFile	yes	This parameter can be used for mutli-part forms to associate files that should be uploaded with the record
accountId	no	the tDAR Account to be used
id	yes	if updating a resource, the tDAR ID of the resource to update

Updating vs Creating:

If an ID is specified in the XML, it will try and update the record if the user has the permissions to update the record.If no ID is specified, it'll create the record.

Walking through a simple creation process:

Start by logging in via the API and getting an authentication token
Create an XML record via the template, using tDAR's current Schema (http://core.tdar.org/schema/current)
Construct a POST request including the XML in the record parameter, the accountId, and any files you'd like to upload via uploadFile
POST that request to http://core.tdar.org/api/upload
Logout

Response of a "valid" Create request:

Response of a Valid "Create" request

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<tdar:resultContainer xsi:schemaLocation="http://localhost:8180/schema/current schema.xsd" xmlns:tdar="http://www.tdar.org/namespace" xmlns:ns3="http://archaeologydataservice.ac.uk/tag/schema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <tdar:message>created:43012</tdar:message>
    <tdar:statusCode>201</tdar:statusCode>
    <tdar:status>HTTP 201 CREATED</tdar:status>
    <tdar:recordId>43012</tdar:recordId>
</tdar:resultContainer>

Creating a record:

Below is a sample XML record that we can use to test the upload process. It does not have all of the fields defined in the schema, but many of the common ones. It can be used as a template / example. Below, we'll call attention to a few specific sections

Sample GIS Record

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<tdar:geospatial status="ACTIVE" xsi:schemaLocation="http://localhost:8180/schema/current schema.xsd" xmlns:tdar="http://www.tdar.org/namespace" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <tdar:coverageDates>
        <tdar:coverageDate>
            <tdar:dateType>CALENDAR_DATE</tdar:dateType>
            <tdar:endDate>2015</tdar:endDate>
            <tdar:endDateApproximate>false</tdar:endDateApproximate>
            <tdar:startDate>2010</tdar:startDate>
            <tdar:startDateApproximate>false</tdar:startDateApproximate>
        </tdar:coverageDate>
    </tdar:coverageDates>
    <tdar:cultureKeywords>
        <tdar:cultureKeyword approved="false" selectable="false" status="ACTIVE">
            <tdar:label>Modern</tdar:label>
        </tdar:cultureKeyword>
    </tdar:cultureKeywords>
    <tdar:date>-1</tdar:date>
    <tdar:dateCreated>2016-06-02T08:12:14.972-07:00</tdar:dateCreated>
    <tdar:description>test map</tdar:description>
    <tdar:externalReference>false</tdar:externalReference>
    <tdar:fileProxies>
        <tdar:fileProxy>
            <tdar:action>ADD</tdar:action>
            <tdar:filename>geotiff.tiff</tdar:filename>
            <tdar:restriction>PUBLIC</tdar:restriction>
            <tdar:sequenceNumber>0</tdar:sequenceNumber>
            <tdar:versionType>UPLOADED</tdar:versionType>
        </tdar:fileProxy>
    </tdar:fileProxies>
    <tdar:geographicKeywords>
        <tdar:geographicKeyword status="ACTIVE">
            <tdar:label>Washington, DC</tdar:label>
        </tdar:geographicKeyword>
    </tdar:geographicKeywords>
    <tdar:informationResourceFiles/>
    <tdar:inheritingCollectionInformation>false</tdar:inheritingCollectionInformation>
    <tdar:inheritingCulturalInformation>false</tdar:inheritingCulturalInformation>
    <tdar:inheritingIdentifierInformation>false</tdar:inheritingIdentifierInformation>
    <tdar:inheritingIndividualAndInstitutionalCredit>false</tdar:inheritingIndividualAndInstitutionalCredit>
    <tdar:inheritingInvestigationInformation>false</tdar:inheritingInvestigationInformation>
    <tdar:inheritingMaterialInformation>false</tdar:inheritingMaterialInformation>
    <tdar:inheritingNoteInformation>false</tdar:inheritingNoteInformation>
    <tdar:inheritingOtherInformation>false</tdar:inheritingOtherInformation>
    <tdar:inheritingSiteInformation>false</tdar:inheritingSiteInformation>
    <tdar:inheritingSpatialInformation>false</tdar:inheritingSpatialInformation>
    <tdar:inheritingTemporalInformation>false</tdar:inheritingTemporalInformation>
    <tdar:investigationTypes>
        <tdar:investigationType status="ACTIVE">
            <tdar:label>Architectural Survey</tdar:label>
        </tdar:investigationType>
    </tdar:investigationTypes>
    <tdar:latitudeLongitudeBoxes>
        <tdar:latitudeLongitudeBox okayToShowExactLocation="false">
            <tdar:maximumLatitude>38.88953803591012</tdar:maximumLatitude>
            <tdar:maximumLongitude>-77.04992473125458</tdar:maximumLongitude>
            <tdar:minimumLatitude>38.889028630817144</tdar:minimumLatitude>
            <tdar:minimumLongitude>-77.05041825771332</tdar:minimumLongitude>
        </tdar:latitudeLongitudeBox>
    </tdar:latitudeLongitudeBoxes>
    <tdar:managedGeographicKeywords/>
    <tdar:materialKeywords>
        <tdar:materialKeyword approved="false" status="ACTIVE">
            <tdar:label>Ceramic</tdar:label>
        </tdar:materialKeyword>
    </tdar:materialKeywords>
    <tdar:otherKeywords>
        <tdar:otherKeyword status="ACTIVE">
            <tdar:label>map</tdar:label>
        </tdar:otherKeyword>
    </tdar:otherKeywords>
    <tdar:relatedComparativeCollections/>
    <tdar:resourceAnnotations/>
    <tdar:resourceCollections>
        <tdar:resourceCollection hidden="false">
            <tdar:description>test description</tdar:description>
            <tdar:name>test collection</tdar:name>
            <tdar:orientation>LIST</tdar:orientation>
            <tdar:sortBy>RESOURCE_TYPE</tdar:sortBy>
            <tdar:type>SHARED</tdar:type>
        </tdar:resourceCollection>
    </tdar:resourceCollections>
    <tdar:resourceCreators>
        <tdar:resourceCreator role="CREATOR" sequenceNumber="0">
            <tdar:person>
                <tdar:firstName>test</tdar:firstName>
                <tdar:institution status="ACTIVE">
                    <tdar:name>University of Arizona</tdar:name>
                </tdar:institution>
                <tdar:lastName>user</tdar:lastName>
            </tdar:person>
        </tdar:resourceCreator>
    </tdar:resourceCreators>
    <tdar:resourceNotes>
        <tdar:resourceNote type="GENERAL">
            <tdar:note>collected around the national monument</tdar:note>
        </tdar:resourceNote>
    </tdar:resourceNotes>
    <tdar:resourceType>GEOSPATIAL</tdar:resourceType>
    <tdar:siteNameKeywords/>
    <tdar:siteTypeKeywords/>
    <tdar:sourceCollections/>
    <tdar:temporalKeywords>
        <tdar:temporalKeyword status="ACTIVE">
            <tdar:label>21st Century</tdar:label>
        </tdar:temporalKeyword>
    </tdar:temporalKeywords>
    <tdar:title>map of ceramics around national monument</tdar:title>
    <tdar:dataTables/>
    <tdar:currentnessUpdateNotes>current as of 2012</tdar:currentnessUpdateNotes>
    <tdar:scale>1:1000</tdar:scale>
    <tdar:spatialReferenceSystem>WGS:84</tdar:spatialReferenceSystem>
</tdar:geospatial>

The File Proxy Section (Note this section is Optional unless you specifically want to add/modify the rights for a file)

This section allows you to specify additional attributes about files, this includes whether a file is confidential or embargoed or not, as well as the order of the files if you have multiple.

Sample GIS Record

    <tdar:fileProxies>
        <tdar:fileProxy>
            <tdar:action>ADD</tdar:action>
            <tdar:filename>geotiff.tiff</tdar:filename>
            <tdar:restriction>PUBLIC</tdar:restriction>
            <tdar:sequenceNumber>0</tdar:sequenceNumber>
            <tdar:versionType>UPLOADED</tdar:versionType>
        </tdar:fileProxy>
    </tdar:fileProxies>

Deleting a File

You can also delete a file this way if you have the fileId (the id of the InformationResourceFile).

Sample GIS Record

    <tdar:fileProxies>
        <tdar:fileProxy>
            <tdar:action>DELETE</tdar:action>
            <tdar:filename>geotiff.tiff</tdar:filename>
            <tdar:fileId>1234</tdar:fileId>
        </tdar:fileProxy>
    </tdar:fileProxies>

The Resource Collection Section

This section allows you to specify whether the resource is part of an existing Resource Collection or not. It enables you to assign rights by associating it with a collection later on or by creating the collection ahead of time. You can also specify the display and sort options for the collection. If you specify the same collection in multiple resources without an ID, tDAR will search for that collection ahead of time and use the first one it finds.

Sample GIS Record

     <tdar:resourceCollections>
        <tdar:resourceCollection hidden="false">
            <tdar:description>test description</tdar:description>
            <tdar:name>test collection</tdar:name>
            <tdar:orientation>LIST</tdar:orientation>
            <tdar:sortBy>RESOURCE_TYPE</tdar:sortBy>
            <tdar:type>SHARED</tdar:type>
        </tdar:resourceCollection>
    </tdar:resourceCollections>

The Resource Creator Section

This section allows you to specify the various creators related to this resource, they may be people or institutions. Please check the documentation to verify which roles are available to which creator types and which resource types.

Sample GIS Record

    <tdar:resourceCreators>
        <tdar:resourceCreator role="CREATOR" sequenceNumber="0">
            <tdar:person status="ACTIVE">
                <tdar:firstName>test</tdar:firstName>
                <tdar:institution id="12088" status="ACTIVE">
                    <tdar:name>University of TEST</tdar:name>
                </tdar:institution>
                <tdar:lastName>user</tdar:lastName>
            </tdar:person>
        </tdar:resourceCreator>
        <tdar:resourceCreator role="SPONSOR" sequenceNumber="0">
            <tdar:institution status="ACTIVE">
                <tdar:name>University of TEST</tdar:name>
            </tdar:institution>
        </tdar:resourceCreator>
    </tdar:resourceCreators>