Wednesday, November 28th, 2012

Announcing If-Match and More V2

By

We have a couple of great features for the V2 API to announce this week! Read on for more info.

If-Match Headers

Box is inherently a social product. That means that people are updating files all of the time, even if another person is working on them. You may not want your Box application to overwrite a change that someone else made while your application was working on a particular file. That would cause all sort of problems. To put this in more plain English terms, your application will want to know, do I have the most current version of this file on hand? If yes, proceed as usual. If no, tell me so, and I’ll get the latest version. This is the core idea behind the If-Match header that the API now supports for the /files and /folders endpoint

Now, when you make an API call to the supported endpoints, you’ll be able to include an If-Match header with the etag of the file. The etag is just an attribute that is included in every file and folder object and also unique for every version of a particular file or folder. If your etag matches the current version of the item on Box, then your API call will proceed as usual. If not, you’ll receive a response telling you that you have a stale version of the item.

For example, let’s say I have this file on hand in my app:

{
    "type": "file",
    "id": "2915155761",
    "sequence_id": "3",
    "etag": "3",
    "sha1": "359c6c1ed98081b9a69eb3513b9deced59c957f9",
    "name": "Eggs.js",
    "description": "",
    "size": 92556,
    "path": "/Eggs.js",
    "path_id": "/0/2915155761",
    "created_at": "2012-08-20T10:20:30-07:00",
    "modified_at": "2012-11-28T13:14:58-08:00",
    "created_by": {
        "type": "user",
        "id": "183732129",
        "name": "Daenerys Targaryen",
        "login": "dany@meereen.com"
    },
    "modified_by": {
        "type": "user",
        "id": "183732129",
        "name": "Daenerys Targaryen",
        "login": "dany@meereen.com"
    },
    "owned_by": {
        "type": "user",
        "id": "183732129",
        "name": "Daenerys Targaryen",
        "login": "dany@meereen.com"
    },
    "shared_link": null,
    "parent": {
        "type": "folder",
        "id": "0",
        "sequence_id": null,
        "etag": null,
        "name": "All Files"
    },
    "item_status": "active"
}

Take note of the fact that the etag value is “3”. Let’s say this is the current version on Box

{
    "type": "file",
    "id": "2915155761",
    "sequence_id": "4",
    "etag": "4",
    "sha1": "359c6c1ed98081b9a69eb3513b9deced59c957f9",
    "name": "Dragons.js",
    "description": "",
    "size": 92556,
    "path": "/Dragons.js",
    "path_id": "/0/2915155761",
    "created_at": "2012-08-20T10:20:30-07:00",
    "modified_at": "2012-11-28T13:14:58-08:00",
    "created_by": {
        "type": "user",
        "id": "183732129",
        "name": "Daenerys Targaryen",
        "login": "dany@meereen.com"
    },
    "modified_by": {
        "type": "user",
        "id": "183732129",
        "name": "Daenerys Targaryen",
        "login": "dany@meereen.com"
    },
    "owned_by": {
        "type": "user",
        "id": "183732129",
        "name": "Daenerys Targaryen",
        "login": "dany@meereen.com"
    },
    "shared_link": null,
    "parent": {
        "type": "folder",
        "id": "0",
        "sequence_id": null,
        "etag": null,
        "name": "All Files"
    },
    "item_status": "active"
}

Someone changed the name of the file, so the etag has changed to a different value, “4”. Let’s say I also try to change the name of the file, using my stale etag in the If-Match header:

curl https://api.box.com/2.0/files/2915155761 \
-H "Authorization: BoxAuth api_key=API_KEY&auth_token=AUTH_TOKEN" \
-H "If-Match: 3" \
-d '{"Name": "Rocks.js"}' \
-X PUT

Since my If-Match value doesn’t match the version Box has on hand, I’ll get this response:

{
    "type": "error",
    "status": 412,
    "code": "precondition_failed",
    "help_url": "http://developers.box.com/docs/#errors",
    "message": "The resource has been modified. Please retrieve the resource again and retry",
    "request_id": "155996325950b68e124990e"
}

That’s just one example of how to use If-Match. We also support If-None-Match as well. Check out the full documentation for more info.

/users/me

Oftentimes an app will want information about the the user for whom it currently has an auth token, but may not readily know what that user’s ID is. In order to make it easier to get the current user’s information, we’ve built out a simple alias, /me, that will let you get the current user’s information throught the /users endpoint e.g.

curl https://api.box.com/2.0/users/me
-H "Authorization: BoxAuth api_key=API_KEY&auth_token=AUTH_TOKEN"

will return:

{
    "type": "user",
    "id": "183732129",
    "name": "Tommen Baratheon",
    "login": "t.lannister@gmail.com",
    "created_at": "2012-08-10T09:00:08-07:00",
    "modified_at": "2012-10-20T11:10:17-07:00",
    "role": "user",
    "language": "en",
    "space_amount": 5368709120,
    "space_used": 291994,
    "max_upload_size": 104857600,
    "tracking_codes": [],
    "see_managed_users": false,
    "is_sync_enabled": true,
    "status": "active",
    "job_title": "",
    "phone": "6509241374",
    "address": "",
    "avatar_url": "https://www.box.com/api/avatar/large/183732129",
    "is_exempt_from_device_limits": false,
    "is_exempt_from_login_verification": false
}

That’s all for this week. Be sure to follow the blog to stay up to date with new V2 features.

By

See all of Sean's articles.