nav[aria-label="Primary Navigation"] { padding: 0; & ul { list-style: none; width: 100%; display: flex; flex-direction: row; justify-content: start; align-items: start; gap: 30px; padding: 0; & li { margin: 0; } & ul li { list-style: none; } } }

Child Item

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

Dan L.10

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'

Find more posts tagged with

API

Abuse

Comments

Steve M.

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

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.

Steve M.

Thanks for the feedback. This should work fine:

_.pluck(results, 'match_type[".tag"]')

Dan L.10

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.

Steve M.

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).