Topic: API bug (user-agent parsing) + suggestions

Posted under e621 Tools and Applications

I got the example (/posts.json) to return something, using curl to start. Here was my process

curl "https://e621.net/posts.json" -> returns a 403, which might make sense if you need an API token
curl "https://e621.net/posts.json" --basic -u za3k:API_KEY -> also returns 403
curl "https://e621.net/posts.json?login=za3k&api_key=API_KEY" -> also returns 403
If I add a user-agent of "username za3k on e621", for example with -H "User-Agent:username za3k on e621", then I see "error code: 1010". If I provide a user-agent that EXACTLY matches the API example format, AND I give an API key, it works though.

Bug report, plus some API design suggestions from a retired programmer, just my opinions though. Generally it looks great, and good documentation too!
1. (Bug) Don't die parsing any user-agent :) such as the example above. It LOOKS based on testing like you meant to allow arbitrary user-agents (which is what I'd recommend), and you just are trying to parse usernames where possible. If you want to REQUIRE the exact template format given in the API guidelines, make sure to make that clear in the documentation--right now it's written as though this is just an example user-agent.
2. (Arguable Bug) Give an explicit error that you need to provide a user-agent if one is missing--give a specific reason access was denied. Don't list a whole bunch of things that might be the problem on your 403 page, that's silly.
3. The 403 page doesn't list a missing user-agent as a possible issue.
4. All the links on the 403 page are broken. (the url is "#1" etc)
5. Give at least one full URL or working example in the "Basics" section, because there's going to be at least one person where this is the first API they've ever tried to use.
6. Drop the documentation to use basic auth for GET entirely--it doesn't make sense over HTTPs, because URLs are already secret. I noticed that it's not actually required--you can use GET parameters, that's good. As part of that, give the API urls with HTTPS and maybe even have an explicit note about HTTPS in the docs.
7. Try to return errors as JSON if someone hits a JSON endpoint (yeah, I know it's a pain, maybe not worth it)

For the curious, Kira helped me out, and it looks like cloudflare blocks any user agent starting with "user" (at least on curl). Just got super unlucky, no parsing happens!

  • 1