Checking the existence of a directory

You use the HTTP HEAD method to check whether a directory exists in a namespace.

Access permission

To check for directory existence, you need browse permission.

Request header

HEAD /rest/directory HTTP/1.1

The HEAD request to check the existence of a directory has these elements:

  • If you’re accessing the namespace as an authenticated user, an Authorization header
ParameterRequiredDescription
directoryYesFolder name.
deletedNo

By default, the GET request to retrieve object versions does not include delete markers. To retrieve a listing that includes delete marker, specify this URL query parameter:

deleted=true

You can also specify deleted=false, which results in the default behavior.

Response headers

The table below describes the request-specific response headers for this operation.

  • X-HCP-Type

    The object entity type.

  • X-HCP-ChangeTimeMilliseconds

    The change time for the directory, in milliseconds since January 1, 1970, at 00:00:00 UTC, followed by an integer that is unique for the change time. For example: 1336483100178.00.

    The change time for a directory is the most recent of:

    • The time the directory was created
    • The time the directory was deleted
    • The time an object was added to the directory
    • The time an object was deleted from the directory

  • X-HCP-ChangeTimeString

    The change time for the object in this format:

    yyyy-MM-ddThh:mm:ssZ

    In this format, Z represents the offset from UTC and is specified as:

    (+|-)hhmm

    For example, 2020-09-18T09:18:20-0400 represents the start of the 20th second into 9:18 AM, September 18, 2020, EDT.

  • X-HCP-SymlinkTarget

    The path to the target object as specified when the symbolic link was created.

    This header is returned only if the URL specifies a symbolic link to an object.

    If this header is returned, the X-HCP-ACL value is always false.

Return codes

The table below describes the HTTP return codes that have specific meaning for this request.

CodeMeaningDescription
200OKHCP found a directory or object at the specified URL.
404Not Found

One of:

  • HCP could not find a directory, object, or version at the specified URL. The specified directory does not exist, or the request specified a directory that has been deleted.
  • Any component of the URL except for the last component in the path is a symbolic link to a directory.

Example: Checking the existence of a directory

Here’s a sample HTTP HEAD request that checks the existence of a directory named quarterly_rpts.

Request with curl command line

curl -k -iI -H "Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d"
    "https://finance.europe.hcp.example.com/rest/quarterly_rpts"

Request in Python using PycURL

import pycurl
import StringIO
cin = StringIO.StringIO()
curl = pycurl.Curl()
curl.setopt(pycurl.HTTPHEADER, ["Authorization: HCP
  bXl1c2Vy:3f3c6784e97531774380db177774ac8d"])
curl.setopt(pycurl.URL, "https://finance.europe.hcp.example.com \
  /rest/quarterly_rpts")
curl.setopt(pycurl.SSL_VERIFYPEER, 0)
curl.setopt(pycurl.SSL_VERIFYHOST, 0)
curl.setopt(pycurl.HEADER, 1)
curl.setopt(pycurl.NOBODY, 1)
curl.setopt(pycurl.WRITEFUNCTION, cin.write)
curl.perform()
print curl.getinfo(pycurl.RESPONSE_CODE)
print cin.getvalue()
curl.close()

Request headers

HEAD /rest/quarterly_rpts HTTP/1.1
Host: finance.europe.hcp.example.com
Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d

Response headers

HTTP/1.1 200 OK
X-HCP-ServicedBySystem: hcp.example.com
X-HCP-Time: 1334829227
X-HCP-SoftwareVersion: 7.0.0.16
Content-Type: text/xm
X-HCP-ChangeTimeMilliseconds: 1326336965436
X-HCP-ChangeTimeString: 2012-01-11T09:56:05-0500
X-HCP-Type: directory
Content-Length: 0