Objects
Objects are Drop-generated binary blobs with attached metadata. They are used to store images, downloads, and similar files.
Authentication
Objects don't inherently require authentication, but generally do. Object ACLs are one of three values:
anonymous: Anyone can access it. The object doesn't require authentication.internal: Anyone with an account can access it. As long as you have a valid session or User token, you can access it.[userId]: Only a specific user can access it, based on the user ID.
As long with one of these values, one of the following CRUD operations can be append:
read: Read access to the object.write: Update/overwrite access to the object.delete: Delete access to the object.
Putting these together, we get ACLs like:
anonymous:read[userId]:writeinternal:write
However, these kinds of operations are rarely handled by the object system, for various reasons. Generally only read permissions are granted at an object-level, and then endpoints update object IDs internally.
Object metadata
Alongside a raw binary blob, objects store various bits of metadata, which are used internally for various purposes. As an API consumer, you don't have access to most of this metadata directly, but it is exposed in the behaviour of various routes.
Properties
- Name
mime- Type
- string
- Description
MIME type of the data. This type is returned in the
Content-Typeheader for fetch requests of objects. Read about MIME types on the MDN.
- Name
permissions- Type
- string[]
- Description
List of ACLs as described above. They define what operations are permitted and not permitted on objects.
- Name
userMetadata- Type
- string
- Description
Additional metadata. Despite the name, this metadata is not provided by, you, the user, but instead by consumers of the internal object API, who is 'user' instead. Essentially, this metadata is per-object and per-usecase specific. It is not exposed.
Check object
This endpoint is used by browsers to check ETag values for client-side caching. It only sets ETag headers, not Content-Type.
The above ACL isn't required to access resources, only if you want to access user-restricted or internal objects.
Request
curl -I http://localhost:3000/api/v1/object/{id} \
-H "Authorization: Bearer {token}"
Response
No response returned.
Fetch object
This endpoint fetches a binary stream of the object's content. It sets both ETag headers and Content-Type for proper rendering within browsers.
The above ACL isn't required to access resources, only if you want to access user-restricted or internal objects.
Request
curl -G http://localhost:3000/api/v1/object/{id} \
-H "Authorization: Bearer {token}" \
--output myfile.bin
Response
< ... binary stream of object contents ...>
Update object
This endpoint overwrites an object in-place (the ID doesn't change). It's rarely used, as endpoint generally handle uploads themselves.
The above ACL isn't required to access resources, only if you want to access user-restricted or internal objects.
Request
curl -X POST http://localhost:3000/api/v1/object/{id} \
-H "Authorization: Bearer {token}" \
--data-binary "@myfile.bin"
Response
{
"success": true
}
Delete object
This endpoint deletes an object by ID. Again, it is rarely used, as individual endpoints handle object deletions themselves.
The above ACL isn't required to access resources, only if you want to access user-restricted or internal objects.
Request
curl -X DELETE http://localhost:3000/api/v1/object/{id} \
-H "Authorization: Bearer {token}"
Response
{
"success": true
}
Object cleanup
It is important to note that there is a scheduled task on Drop instances that cleans up unreferenced objects. It automatically deletes objects unreferenced in the database, but it may not function correctly. If you find that objects are disappearing on you, please file a bug report.