API

[arlolra]

I started working on an API,

https://check.torproject.org/api/bulk?ip=38.229.72.19&port=443

This needs to be further fleshed out and documented.

[Ryman]

What's the idea around fleshing it out? What service/info is wanted? Or just to make bulk more useful?

I'd suggest versioning the api if it is something you want to adopt for the project long term (e.g. .../api/1.0/...), I guess it depends what the goal of the api is!

[arlolra]

What's the idea around fleshing it out? What service/info is wanted? Or just to make bulk more useful?

Nothing really wants this at the moment, it just seems like it could be useful to have around. An idea stemming from, https://trac.torproject.org/projects/tor/ticket/9529#comment:20

The fleshing out is to determine what info we have and how to expose it. Something like,

/api/ip?address=123.123.123.123&port=80  // returns { tor: true/false, fingerprint: ... }
/api/ip?fingerprint=AD2344243... // returns { exitip: 123.123.123.123 }
/api/bulk/all  // returns [ ... list of all known exits and their ips ... ]

I'd suggest versioning the api if it is something you want to adopt for the project long term (e.g. .../api/1.0/...), I guess it depends what the goal of the api is!

There are other services, besides the TBB, that depend on check, so long term support is a goal. See https://trac.torproject.org/projects/tor/ticket/10183

I'd rather not have the version number in the url. That can be accomplished with an Accept header. I guess see GitHub's API or this article as a model.

[Ryman]

/api/ip?address=123.123.123.123&port=80 // returns { tor: true/false, fingerprint: ... }

Seems sound, how about RESTful-ish /api/ip/-ip-/-port-
Should multiple IPs be supported per query? (I don't think so)

It could be useful to provide a lastseen timestamp for the IP lookups so consumers can make their own decisions for how many hours they're willing to allow true/false for instead of providing true/false? (or could be additional?)

If no port is given, we could return the accept/reject policies? (Since isTor can't be known for that?)
Could also list alternative IPs seen for the matched fingerprint (with last seen time for each?)

/api/ip?fingerprint=AD2344243... // returns { exitip: 123.123.123.123 }

Perhaps /api/router? Again, might want to provide ip/time combos?

/api/bulk/all // returns [ ... list of all known exits and their ips ... ]

So this is an exit list basically? , (I think we can drop the /all , no query implies all)

Would providing microdesc/fulldesc endpoints be overkill? Any consumer should probably be using the fingerprints to lookup atlas/globe/whatever for further information? Perhaps supplying a 'further info' link we can update to the service of the day might be useful?

I'd rather not have the version number in the url. That can be accomplished with an Accept header. I guess see GitHub's API or this article as a model.

I don't feel that strongly about implementation on that as long as it's there :) But I would note that having it in the url makes it easier to test in browser (not a big issue really)

On another aesthetic note: I noticed in the code it's looking for format=json, /i/like/endpoint.{json,xml,...} personally :)