Monday, November 5th, 2012

Tips for Using the Shared Items Endpoint

By

A few weeks ago we released the /shared_items endpoint, which is an extremely powerful endpoint if you know how to use it. Before we get into how the API works, let’s look at how shared items work in the Box web application.

The Shared Item Experience on the Web

For every file and folder (I’m going to refer to the set of these as items going forward) in Box, you have the ability to create a special link to that item that anyone can access, even if they don’t have a Box account.

The link https://www.box.com/s/8tqjqtoky18sbnoz264c will take anyone to this folder, even if they’re not logged into a Box account.

Even though I’m not logged in, I can still download individual files from this folder, or even the entire folder itself in a single click. If I had my own Box account, I could even re-upload those files to my account afterwards.

The Shared Item Experience in the API

Shared Items work similarly in the API. Let’s say I have the same shared link as before:

If you recall:

The link https://www.box.com/s/8tqjqtoky18sbnoz264c will take anyone to this folder, even if they’re not logged into a Box account.

This same paradigm applies to shared items the API. If you have one of these shared links, you can retrieve its content without an auth token for a user. An API request like:

curl https://api.box.com/2.0/shared_items \
-H "Authorization: BoxAuth api_key=YOUR_API_KEY&shared_link=https%3A%2F%2Fwww.box.com%2Fs%2F8tqjqtoky18sbnoz264c"

is completely valid, and will return an object as if I were an authenticated user getting the folder:

{
    "type": "folder",
    "id": "470843624",
    "sequence_id": "0",
    "name": "Puppies",
    "created_at": "2012-11-05T14:03:02-08:00",
    "modified_at": "2012-11-05T14:07:00-08:00",
    "description": "",
    "size": 343506,
    "created_by": {
        "type": "user",
        "id": "181216415",
        "name": "sean rose",
        "login": "sean+awesome@box.com"
    },
    "modified_by": {
        "type": "user",
        "id": "181216415",
        "name": "sean rose",
        "login": "sean+awesome@box.com"
    },
    "owned_by": {
        "type": "user",
        "id": "181216415",
        "name": "sean rose",
        "login": "sean+awesome@box.com"
    },
    "shared_link": {
        "url": "https://www.box.com/s/8tqjqtoky18sbnoz264c",
        "download_url": "https://www.box.com/shared/static/8tqjqtoky18sbnoz264c",
        "password_enabled": false,
        "unshared_at": null,
        "download_count": 0,
        "preview_count": 0,
        "access": "Open",
        "permissions": {
            "download": true,
            "preview": true
        }
    },
    "parent": {
        "type": "folder",
        "id": "0",
        "sequence_id": null,
        "name": "All Files"
    },
    "item_status": "active"
}

That shared_link parameter in the Authorization header is your magic key to that folder and its contents. If you keep it in the header, you can even retrieve the folder from the normal /folders endpoint since you know its ID:

curl https://api.box.com/2.0/folders/470843624 \
-H "Authorization: BoxAuth api_key=YOUR_API_KEY&shared_link=https%3A%2F%2Fwww.box.com%2Fs%2F8tqjqtoky18sbnoz264c"

and also retrieve one of the individual files in that folder:

curl https://api.box.com/2.0/files/3850724632 \
-H "Authorization: BoxAuth api_key=YOUR_API_KEY&shared_link=https%3A%2F%2Fwww.box.com%2Fs%2F8tqjqtoky18sbnoz264c"

While you didn’t need an auth token to do the above steps, if you do have an auth_token, you can do even more. Since I can perform actions on that shared item, I can actually copy it into my account. I’d otherwise have to download all of those files, re-create the folder(s), and re-upload. Instead of all that, I can just do:

curl https://api.box.com/2.0/folders/470843624/copy \
-H "Authorization: BoxAuth api_key=YOUR_API_KEY&auth_token=YOUR_AUTH_TOKEN&shared_link=https%3A%2F%2Fwww.box.com%2Fs%2F8tqjqtoky18sbnoz264c" \
-d '{"parent": {"id" : DESTINATION_FOLDER_ID}}' \
-X POST

(where DESTINATION_FOLDER_ID is the ID of a folder in my account) and let Box handle moving all of the files and folders. This sort of operation might otherwise take a really long time with a lot of memory and computing power on your end. Not anymore!

By

See all of Sean's articles.

  • Nitin Pande

    Whats the significance of download_count and preview_count? Its not increasing even after somebody performs the action. I enabled download and preview access for shared item.