- 03 May 2024
- 5 Minutes to read
- Print
- DarkLight
- PDF
Asset Directory API
- Updated on 03 May 2024
- 5 Minutes to read
- Print
- DarkLight
- PDF
The Asset Directory API provides simple RESTful access to files and folders in an asset directory. All API endpoints are accessed through the following base URL:
/endpoints/«AssetDirectoryName»/...
Asset Directories are represented internally in ProGet as Feeds, so Feed API keys can be used to authenticate to Asset Directories.
The Asset Directory API is comprised of endpoints for both files and folders:
📄 File Management
These endpoints are for directly managing the files located in the asset directory. They are designed to function like a standard web server, so hosted files can be accessed by simple GET requests with support for browser caching.
- Download Asset File - returns the content of a specified file or the files's headers
- Upload Asset File - uploads a specified file to the asset directory
- Delete Asset File - deletes a specified file from the asset directory
For managing very large (2GB+) files, please see our Multipart Upload API.
📁 Folder Management
These endpoints are for managing the folders located in the asset directory.
- List Asset Folder - describes assets in a specified folder
- Create Asset Folder - creates a new subfolder
- Delete Asset Folder - deletes a specified subfolder
- Export Asset Folder - exports the contents of a folder as either a
ZIP
or aTGZ
archive - Import Archive - imports the contents of either a
ZIP
or aTGZ
archive as a subfolder
🔖 Metadata Management
The Metadata endpoints allow for reading or updating metadata on a file or folder. These endpoints were added in ProGet v6.0.0.
- Get Asset Metadata - describes the metadata for the specified file or folder
- Update Asset Metadata - updates the
Content-Type
or the user-defined metadata of a file or folder.
Authenticating to Asset Directory API Endpoints
The following is a summary of access types and their corresponding requirements for various API keys types and endpoints within this API.
Access Type | Requirements |
---|---|
System API Keys | Use/Manage Feeds |
Feed API Keys | View/Download is required for all endpointsAdd/Repackage is required for uploading/importing endpointsOverwrite/Delete is required for deletion endpoints |
Personal API Key | Feeds_ViewFeed is required for all endpointsFeeds_AddPackage is required for uploading/importing endpointsFeeds_DeletePackage is required for deletion endpoints |
No API Key | anonymous or authenticated user must have at least Feeds_ViewFeed |
To specify an API Key, use the request header (X-ApiKey
), querystring (key
), or api:«api-key»
as the username. See API Key Usage to learn more.
For example, to authenticate with the API key abc12345
to the "List Folder" endpoint, you could specify the API key as follows:
curl -X GET --header "X-ApiKey: abc12345" "https://proget.corp.local/endpoints/internal-files/dir/"
Data Specifications
ItemData Object Attributes
ItemData
is a set of key/value pairs that correspond to the properties an "item" (either a file or folder) within the Asset Directory. It's used as output data for the List Folder endpoint as a JSON-formatted object.
Property | Format | Notes |
---|---|---|
name | string | contains the local name of the item. This property does not include the full path. |
parent | string | contains the full path of the parent directory of the item. This property does not include the name of the item itself. This property may be omitted if the item is contained in the root folder of the asset directory. |
type | string | contains either the Content-Type of the the item, or the literal text dir if the item represents a subfolder. |
content | string | contains a full URL where this item can be downloaded. |
created | string | contains the UTC date of the original creation time of the item in ISO 8601 format (yyyy-MM-ddThh:mm:ss). |
modified | string | contains the UTC date of the last time of the item was updated in ISO 8601 format (yyyy-MM-ddThh:mm:ss). |
size | number | specifies the number of bytes in size of the item. |
sha1 | string | contains the SHA1 hash of the item. |
The content
, size
, modified
and sha1
properties are omitted if the item represents a folder.
JSON Object
{
"name": "example.txt",
"parent": "/documents",
"type": "text/plain",
"content": "https://proget.corp.local/endpoints/myAssetDirectory/content/documents/example.txt",
"created": "2023-11-29T09:45:00",
"modified": "2023-11-29T10:30:00",
"size": 1024,
"sha1": "a1b2c3d4e5f6g7h8i9j0"
}
Metadata Object Attributes
Metadata
is a set of key/value pairs that correspond to the properties of an item's (file or folder) metadata. It's used as output data for the Get Metadata Endpoint as a JSON-formatted object.
Property | Format | Notes |
---|---|---|
name | string | contains the local name of the item. This property does not include the full path. |
parent | string | contains the full path of the parent directory of the item. This property does not include the name of the item itself. This property may be omitted if the item is contained in the root folder of the asset directory. |
type | string | contains either the Content-Type of the the item, or the literal text dir if the item represents a subfolder. |
content | string | contains a full URL where this item can be downloaded. |
created | string | contains the UTC date of the original creation time of the item in ISO 8601 format (yyyy-MM-ddThh:mm:ss). |
modified | string | contains the UTC date of the last time of the item was updated in ISO 8601 format (yyyy-MM-ddThh:mm:ss). |
size | number | specified the number of bytes in size of the item. |
sha1 | string | contains the SHA1 hash of the item. |
userMetadata | object | lists key/value pairs of user-defined metadata for the item. |
cacheHeader | object | contains the type of caching used and the value configured. See cache header settings for more information. |
The content
, size
, modified
and sha1
properties are omitted if the item represents a subfolder.
JSON Object
{
"name": "example.txt",
"parent": "/documents",
"type": "text/plain",
"content": "https://proget.corp.local/endpoints/myAssetDirectory/content/documents/example.txt",
"created": "2023-11-29T09:45:00",
"modified": "2023-11-29T10:30:00",
"size": 1024,
"sha1": "a1b2c3d4e5f6g7h8i9j0",
"userMetadata":
{
userMetadata // userMetaData Object
},
"cacheHeader": {
"type": "TTL",
"value": 30
}
}
MetadataUpdate Object Attributes
MetadataUpdate
is a set of key/value pairs that correspond to the fields in a metadata update. It's used as input data for the Update Metadata Endpoint as a JSON-formatted object.
Property | Format | Notes |
---|---|---|
type | string | contains the new Content-Type of the the asset. Ignored for directories. If not specified, the Content-Type is not updated. |
userMetadata | object | lists updated key/value pairs of user-defined metadata for the item. |
userMetadataUpdateMode | string | contains one of: update (create/update properties) or replace (create/update properties and delete missing values) |
cacheHeader | object | contains two properties, type and value . If not specified, the Cache Header is not updated. (ex: { 'type': 'TTL', 'value': 30 } ). |
JSON Object
{
"type": "application/json",
"userMetadata":
{
userMetadata // userMetaData Object
},
"userMetadataUpdateMode": "update",
"cacheHeader":
{
"type": "TTL",
"value": 60
}
}
Cache Header Settings
See client-side caching for more information.
Type | Description | Value |
---|---|---|
Inherit | Inherit from parent folder | Value is not needed |
NoCache | Do not cache this item | Value is not needed |
TTL | Length in seconds to cache items | Integer value (ex: 30 ) |
Custom | Use a custom Cache-Control header with the specified value | String value (ex: public, max-age=604800, immutable ) |