REST search API requirements

[thialfihar]

Using the search API to query keybase.io, I have noticed the following things:

Naming

• You use "websites" but also "generic_web_site". I'd prefer "websites" and "generic_website".
• I'd prefer no abbreviations: "value" instead of "val"
• I'd prefer "fingerprint" instead of "keyfingerprint", the "key" doesn't add any information, does it? Especially while inside a JSON key object.
• I'd prefer "type" instead of "key_type".
• I'd prefer "modification_time" over "mtime". If the value is timezone specific, then "_utc" or something should probably reflect that in the name.
• Same for "creation_time" vs. "ctime".
• In /user/autocomplete.json websites have "protocol" and in /user/lookup.json they have a "presentation_tag". Their values also differ, see below.

  Values

• The fingerprint would be more useful as the actual full fingerprint, without spaces and not reduced to the key id. Especially in /user/autocomplete.json this would allow a client to display the fingerprint or use it for whatever without downloading all user data. Already mentioned here: https://github.com/keybase/keybase-issues/issues/697
• Times as UNIX timestamps are not ideal. I think ISO would be much better, and it could include a timezone. If that is a problem for whatever reason, then it probably should be UTC and reflected in the name of the field. Or another timezone field could be added.
• The "protocol" for websites in /user/autocomplete.json ends with a colon. Is that correct?
• What's the meaning of the value in "key_type"? I suspect "1" is "public" and "2" is "secret"... I think those strings would be more meaningful.

  New fields

It would be great if /user/autocomplete.json returned these fields as well:

• key size
• key algorithm
• perhaps also the main user ID of the key that'd make it more useful to be used as a look-up server.

But perhaps "autocomplete.json" is not the right resource to search for that data. Is there some /user/search.json or somesuch that I missed?

[malgorithms]

this is a great list, thanks!

[thialfihar]

Thanks for adding the key size and algorithm to autocomplete.json! That's very useful.

But I'd like to add them to the naming lists:

• wouldn't "algorithm" and something like "key_size" be more descriptive?
• They also don't seem at home inside "key_fingerprint".

I think it might be time for a search API that isn't used for autocomplete and that has a new and clean result structure.

Sorry about the nitpicking, but I think an API can dangerously easily become messy with many new features and loose naming conventions. :)

[timbray]

Meh, it’s just JSON, who cares what the field names are, or the details of the nesting, as long as they’re reasonably mnemonic. Ruby/python/JS programmers might be a little more upset since they tend to map JSON straight into native data structures, but often that’s unwise, a source of problems. I’ve gotten really used to picking pieces out of wire data formats to populate my runtime objects, it seems like the default reasonable way to behave, these days.

[zQueal]

Meh, it’s just JSON, who cares what the field names are

It may be just JSON, but to attract programmers some form of continuity needs to be established. No one wants to interface with software that's difficult to deal with.