We Want to Hear From You! What Do You Want to See on the Community? Tell us here!

Forum Discussion

Dan L.10's avatar
Dan L.10
New member | Level 1
10 years ago

API v2 feedback: files' ".tag" attribute extremely unfriendly for HTTP/JSON

I'm using v2 of the HTTP API and wanted to pass along some feedback.

When I hit a files list from an endpoint like files/list_folder, I get a JSON response like this:

{ entries:
[
  { '.tag': 'file',
    name: 'foo.pdf',
    path_lower: '/foo.pdf',
   
id: 'id:abcdefg',
   
client_modified: '2015-11-16T00:50:26Z',
   
server_modified: '2015-11-16T00:50:26Z',
   
rev: 'd3adb33f',
   
size: 8675309 },
  ...
],
cusor: ...
}

Passing back attributes like ".tag" makes it extremely difficult to work with in JSON.  eg the only way to access it is with the string accessor: result['.tag'].  Many popular data manipulation libraries like lodash break when trying to define simple filters or accessors for this property.

Since the HTTP API speaks JSON, it would be far more developer-friendly to use proper json attribute names.  If the attribute is meant to "private", the underscore convention would be more appropriate, eg 'result._tag'

5 Replies

Replies have been turned off for this discussion
  • Thanks for the feedback! I think you're specifically talking about JavaScript, right?

    The dot wasn't meant to indicate that the field is private–clients definitely need to read it. It was meant to be in a namespace that would never cause collisions. A dot seemed like a good way to do that, since it's uncommonly used in a JSON dictionary key.

    It's unfortunately too late to change this for API v2, which just recently came out of beta. But we could consider changing it in a future version of the API. I'd love to hear specific examples ofwhere this causes trouble, e.g. in lodash.

    This seems to work fine:

    var files = _.filter(entries, '.tag', 'file');
  • Dan L.10's avatar
    Dan L.10
    New member | Level 1
    10 years ago

    The files search API returns lists like:

    ```
    [
    { match_type: { '.tag': 'filename'},
      metadata: { '.tag': 'file', ...}
    }
    ]
    ```

    Both `_.pluck(results, 'match_type.tag')` and `_.pluck(results, 'match_type..tag')` fail.

    Any filter is awkward: `list.filter( result => result.metadata['.tag'] === 'folder' )`

    Any javascript/JSON api should not be using .'s, -'s, or spaces in attribute names.  Makes developing against it very kludgy.

  • Thanks for the feedback. This should work fine:

    _.pluck(results, 'match_type[".tag"]')
  • Dan L.10's avatar
    Dan L.10
    New member | Level 1
    10 years ago

    The [".tag"] selector was always a workaround, the feedback is that a json API shouldn't have to resort to such fallbacks.

    Any chance of calling the ".tag" attribute deprecated and just duplicating the information under a more friendly attribute name so we can start preparing for the next version of the API?  At the cost of some small redundancy, an approach like that won't break existing integrations while still providing a friendlier developer experience with the existing API.

  • I'm passing this along, but I don't think we'll be making this change in API v2. The lack of support for JavaScript's dot-notation syntactic sugar is sort of by design. We used a dot specifically because it's not likely to collide with anything else (because dots are uncommon in JSON dictionary keys).

About Dropbox API Support & Feedback

Node avatar for Dropbox API Support & Feedback
Find help with the Dropbox API from other developers.6,033 PostsLatest Activity: 3 years ago
409 Following

The Dropbox Community team is active from Monday to Friday. We try to respond to you as soon as we can, usually within 2 hours.

If you need more help you can view your support options (expected response time for an email or ticket is 24 hours), or contact us on X or Facebook.

For more info on available support options for your Dropbox plan, see this article.

If you found the answer to your question in this Community thread, please 'like' the post to say thanks and to let us know it was useful!