Files

What are files?

Even though the API has an endpoint called files, the only thing you can upload there are images. The image formats we accept are png, gif, and jpg. The maximum upload size is 2000000 bytes (just under 2MB). The API will ACCEPT larger files and by default resize them for you, but only up to a certain point. To avoid problems, try to keep your images around 2MB or below.

File data and privacy

Files have two components: they have the raw image data, and then a "content" type managed in the API. The content serves as a sort of metadata for the file, and you can request and modify it through the api just like other content (like pages). The file's link uses the content hash, and is always available if you have the link. Since the hash is random, and is clearly given by the content, privacy is achieved by making the content private. Unless someone guesses the hash, this will prevent the file from showing up in searches, but NEVER prevent you from sharing the file.

So for instance, if you want to share an image with only a select group of people, you set the file's global permissions on upload to disallow public access (set the globalPerms on the formData to "."; sometimes empty string doesn't work so we also accept "." as "no perms"), and only you will know the link to the raw file data. You can then share the link with only the people you care about.

Buckets

Files are stored in S3, in a private bucket. Perhaps confusingly, we have also historically had the concept of buckets across many of the services we (the community that consumes contentapi) uses. In this iteration of the api, there's no longer the concept of a "bucket" as far as the backend is concerned, but we still emulate it for because we're all familiar with it.

To emulate a bucket, we set the "bucket" key on the values dictionary, available on all content. You can set the values for a file on upload; see https://github.com/randomouscrap98/contentapi/blob/master/contentapi/wwwroot/imagemini.html and look for values[bucket] (imagemini.html is actually a full example for emulated buckets). By setting this value now, it allows us to later search for images within a bucket, making it act somewhat like a folder or a tag (again see imagemini.html, this time look for !valuelike). However, that's not all you need to do.

Historically (such as on kland), buckets have been used for privacy, because the bucket name was kept private and thus people couldn't list images unless they knew the bucket name. This is no longer how the API works, as buckets don't exist, however we can go one step further now and simply set the file permissions to private using globalPerms (see previous section).

With both the "bucket" key set in values for the purposes of search, and global permissions stripped from the file, files you "put in a bucket" will not show up in any list, but you can see all the files you put in that bucket.