Uploading, downloading and describing files with Atomic Data

The Atomic Data model (Atomic Schema) is great for describing structured data, but for many types of existing data, we already have a different way to represent them: files. In Atomic Data, files have two URLs. One describes the file and its metadata, and the other is a URL that downloads the file. This allows us to present a better view when a user wants to take a look at some file, and learn about its context before downloading it.

The File class

url: https://atomicdata.dev/classes/File

Files always have a downloadURL. They often also have a filename, a filesize, a checksum, a mimetype, and an internal ID (more on that later). They also often have a parent, which can be used to set permissions / rights. If the file is an image they will also get an imageWidth and imageHeight property.

Uploading a file

In atomic-server, a /upload endpoint exists for uploading a file.

• Decide where you want to add the file in the hierarchy of your server. You can add a file to any resource - your file will refer to this resource as its parent. Make sure you have write rights on this parent.
• Use that parent to add a query parameter to the server's /upload endpoint, e.g. /upload?parent=https%3A%2F%2Fatomicdata.dev%2Ffiles.
• Send an HTTP POST request to the server's /upload endpoint containing multi-part-form-data. You can upload multiple files in one request. Add authentication headers, and sign the HTTP request with the
• The server will check your authentication headers, your permissions, and will persist your uploaded file(s). It will now create File resources.
• The server will reply with an array of created Atomic Data Files

Downloading a file

Simply send an HTTP GET request to the File's download-url (make sure to authenticate this request).

Image compression

AtomicServer can automatically generate compressed versions of images in modern image formats (WebP, AVIF). To do this add one or more of the following query parameters to the download URL:

Example: https://atomicdata.dev/download/files/1668879942069-funny-meme.jpg?f=avif&q=60&w=500

Discussion

• Discussion on specification
• Discussion on Rust server implementation
• Discussion on Typescript client implementation