keybase / keybase/keybase-issues

REST search API requirements

Open
#711 4 comments 0 reactions 0 assignees View on GitHub
Dominant language
No language data
Stars
899
Forks
40
PR merge metrics
No merged PRs in 30d

Description

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 "key_fingerprint", 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?

Contributor guide

No contributing guide indexed for this repository

Research direction

Compare the response schemas for /user/autocomplete.json and /user/lookup.json, including the naming, timestamp, fingerprint, protocol, and key_type examples called out in the issue. Review the related issue #697 and determine whether a separate search endpoint is needed. Done means the API requirements are resolved into an agreed schema and endpoint scope.

Written by the indexing model from the issue text.

Assessment

Domain
api, backend-api-design
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.