Pragmatic Geographer

SOFTWARE GEOGRAPHY ECONOMICS HISTORY

REST and File Uploads/Attachments

Your web application will support uploading files. At first glance, this is an action and you might consider working with it as an RPC endpoint rather than REST. The upload could refer to a verb rather than a noun.

There isn’t anything really wrong with this, but I would argue there are significant advantages with going with it as a noun (REST resource). Here are a few:

Staging an upload to external datastore

An upload may not be directly to you, and it might not be used by the requesting client – signed S3 forms, one-time URL endpoints, other protocols like Bittorrent, and other mechanisms that allow direct client uploads.

Example:

1
2
3
4
5
6
{
    "upload_to_url": "https://example.com/one/time/endpoint/hashhashhash",
    "signed_token": "blahblahblah",
    "expires": "2013-07-12T19:10:19.491Z",
    "etc": "..."
}

Tracking/auditing – both internally and externally

What if a user wants to see what uploads are currently in progress? All of the successful ones? The failures? Those are all also useful metrics internally as well.

1
2
3
4
5
6
{
    "createuser": "https://example.com/user/1234",
    "modifieduser": "https://example.com/user/1234",
    "createdate": "2013-07-12T19:10:19.491Z",
    "modifieduser": "2013-07-12T19:10:19.491Z"
}

Attaching additional resources as a means of post-upload action

The file being uploaded is unlikely to exist in a vacuum. You will have related resources and possibly related actions. Consider, for instance, that you want to send alerts to some people when the upload is complete:

1
2
3
4
5
6
7
8
{
    "subscribers": [
      "https://example.com/user/1234",
      "https://example.com/user/288",
      "https://example.com/user/3"
    ],
    "etc": "..."
}

Explicit vs. implicit

Bottom line – your upload has state information. You are probably capturing it anyway in logs or other resources. If you have some subscribers as above, you want to make that information explicit, and in many cases, client controlled.

Comments