Friday, September 28th, 2012

Exciting New V2 Updates

By , Platform Manager

This week, we have a crop of awesome features we’re releasing for the V2 API that will make your Box apps more powerful and efficient than ever.

Collaborations

A collaboration is Box’s equivalent of an access control list for folders. As long as a user has the proper permissions, they can invite other users to a folder as well as set what levels of access that user has to the folder and its contents. You can read more about the roles that Box defines for users here.

{
    "type": "collaboration",
    "id": "763169",
    "created_by": {
        "type": "user",
        "id": "16868249",
        "name": "Jon Snow",
        "login": "jsnow@thewall.net"
    },
    "created_at": "2012-08-06T17:01:08-07:00",
    "modified_at": "2012-08-25T21:05:41-07:00",
    "expires_at": null,
    "role": "Previewer",
    "status": "Accepted",
    "accessible_by": {
        "type": "user",
        "id": "16873941",
        "name": "Robb Stark",
        "login": "robb@winterfell.com"
    },
    "acknowledged_at": "2012-08-06T17:01:08-07:00",
    "item": {
        "type": "folder",
        "id": "11152632",
        "sequence_id": "5",
        "name": "Direwolf Pics"
    }
}

The /collaborations endpoint supports the full gamut of PUT, POST, GET, and DELETE, giving you programmatic access to all of the functionality you see in the web app!

Enterprise Admin Logs

If you’ve ever used a Box Admin account, you’re most likely familiar with this screen:

We previously only allowed you to manually export these user activity reports from the Web UI, but now you can access them through an extremely simple GET request

GET /events?stream_type=admin_logs

You’ll notice that the logs are accessed through the same /events endpoint that normal users would access. The objects returned are also identical to the event objects returned when hitting the /events endpoint normally. We munged the admin logs for you so that you wouldn’t have to write any additional code to understand and compare the event objects.

When including the admin_logs stream type, you also get a few additional parameters to utilize

  • created_after – a lower bound on the events you want returned
  • created_before – an upper bound on the events you want returned
  • event_type – a commma-separated list of specific event_type you want

And that’s it! The admin logs are perfect for plugging in to your favorite business intelligence tool or logging system.

?fields

Whenever you make a GET request to the /folders/{id}/items endpoint, you get back a collection of mini file and folder objects.

Sometime you’ll want additional information about each item, like its modified_date, for example. Currently, you’ll have to make an individual GET request for each item. This is extremely inefficient for both the API client as well as the API itself. To help remedy this, we’ve created the fields parameter. Usage is extremely simple, you just include the fields parameter with a comma-separated list of the attributes you want back:

GET /folders/{id}/items?fields=name,description,created_by

…and just like that, the response will have only those attributes. Currently, files and folders don’t have a completely identical set of attributes; if you include an attribute that is exclusive to one, you’ll back that attribute for that one, but not the other, for example

GET /folders/{id}/item?fields=etag,name

will return

{
    "total_count":2,
    "entries":[
        {
            "type":"file",
            "id":"2305649799",
            "name":"1",
            "etag":"241op4jo12j4fasfa"
        },
        {
            "type":"folder",
            "id":"2305649799",
            "name":"1"
        }
    ]
}

By default, you will always get type and id back as attributes.

Other Tweaks

We updated the /users object to return a bunch more information:

{
    "total_count": 1,
    "entries": [
        {
            "type": "user",
            "id": "181216415",
            "name": "sean rose",
            "login": "sean+awesome@box.com",
            "created_at": "2012-05-03T21:39:11-07:00",
            "modified_at": "2012-08-23T14:57:48-07:00",
            "role": "user",
            "language": "en",
            "space_amount": 5368709120,
            "space_used": 52947,
            "max_upload_size": 104857600,
            "tracking_codes": [],
            "see_managed_users": false,
            "sync_enabled": true,
            "status": "active",
            "job_title": "",
            "phone": "5555551374",
            "address": "10 Cloud Way Los Altos CA",
            "avatar_url": "https://api.box.com/api/avatar/large/181216415"
        }
    ]
}

Per the post last week, don’t forget that we’re deprecating POST /folders/{id} and adding an If-Match requirement to POST /files/{id}/data. Don’t forget to update your code!

By ,

Platform Manager

See all of Sean's articles.