I've decided to finally get off my ass and make a proper OpenAPI spec for the api here like I've wanted to for months

You can find the source here: https://github.com/DonovanDMC/E621OpenAPI
And the rendered/usable version here: https://e621.wiki

This is intended to be helped by community contributions if people feel so inclined, so feel free to open pull requests in the repository, or mention issues/incorrect documentation you find in this topic
The documentation file is currently almost 11,000 lines so I'm sure it's got a few issues here and there

donovan_dmc said:
I've decided to finally get off my ass and make a proper OpenAPI spec for the api here like I've wanted to for months

You can find the source here: https://github.com/DonovanDMC/E621OpenAPI
And the rendered/usable version here: https://e621.wiki

This is intended to be helped by community contributions if people feel so inclined, so feel free to open pull requests in the repository, or mention issues/incorrect documentation you find in this topic
The documentation file is currently almost 11,000 lines so I'm sure it's got a few issues here and there

Wow, cool!

I mean, the JSON stuff is pretty easy to understand the fields of, but actual documentation is great to have, to. Thanks!
There's also the already existing notes on it like "use a unique UA so we can manage client misbehavior (bugs or intentional) without banning users entirely" bit. I assume you added that, too. I'll check it out, later.

Nice job! Can confirm the spec is also parseable in IntelliJ/RubyMine, which is a really nice bonus.

Would you mind if I made a PR to make the openapi.yaml publically accessible on https://e621.wiki? A lot of tools can use external schemas like that.

ailurus said:
Nice job! Can confirm the spec is also parseable in IntelliJ/RubyMine, which is a really nice bonus.

Would you mind if I made a PR to make the openapi.yaml publically accessible on https://e621.wiki? A lot of tools can use external schemas like that.

Presuming it's a simple change, go for it

This looks good! I especially like the built-in "try it out" functionality.

Here are some comments. All of this is based on trying it with Firefox 115.15.0esr, on Linux, desktop.

If you can have "free text" at the top (I think the OpenAPI definition for E621's API... line is that way), it might be good to include a link to https://status.e621.ws/ up there, along with an explanation that when Cloudflare is mitigating an attack, or the API is otherwise unavailable for some reason, the "try it out" links on this page won't work.

Some of the rendering is a little slow, but then again, there's a lot of markup for some of the endpoints. For example, I clicked on the GET /artists/{idOrName}.json Get Artist header line; it immediately opened the detail box below that line, with a "loading" partial-circle spinner, but it took about 4 to 5 seconds for the detail box to display in full. It does seem to cache - if I click on the header to close the detail box, and then click on the header again to re-open the detail box, the detail box renders in immediately. (I tried blocking the Plausible analytics and clicking some other header lines, but it didn't make any difference, so I don't think the delay is coming from Plausible.)

At least one of the text boxes is kind of slow. I clicked on the POST /dtext_preview.json Preview DText line, and then tried to replace the "string" in the request body with my own DText. The screen echo lagged my keystrokes by several seconds.

Also, does dtext_preview.json only work with a login/API key? Even when I leave it at the default "body": "string" request body, and click Execute, I get a Code Undocumented and Details TypeError: NetworkError when attempting to fetch resource..

When I click on GET /mod_actions.json Search Mod Actions, and the detail box expands, the simple comma-separated list for search[action] is kind of hard to read. I think it would be better as a couple of columns or something - BUT - I realize this may be automatically formatted from the source, without a good way to reformat it. If I click the Try it out button in that section, that comma-separated list goes away, and the drop-box presents a normal one-column list, which is easier to use.

This might be out of scope for the API documentation, but maybe it could link to some other documentation (Github changelog for the main e621 code?) that explains that some of the possible responses have changed over time. For example, the mod_actions.json API documentation correctly mentions tag_implication_create as a possible search key - BUT - the last action with that key was in December 2021. I assume there was some kind of code change to the main e621 code that took it away.

Thanks!

Furbitron

furbitron said:
This looks good! I especially like the built-in "try it out" functionality.

Here are some comments. All of this is based on trying it with Firefox 115.15.0esr, on Linux, desktop.

If you can have "free text" at the top (I think the OpenAPI definition for E621's API... line is that way), it might be good to include a link to https://status.e621.ws/ up there, along with an explanation that when Cloudflare is mitigating an attack, or the API is otherwise unavailable for some reason, the "try it out" links on this page won't work.

I do have the ability to put anything up there, I'll put some info about it in there

furbitron said:
Some of the rendering is a little slow, but then again, there's a lot of markup for some of the endpoints. For example, I clicked on the GET /artists/{idOrName}.json Get Artist header line; it immediately opened the detail box below that line, with a "loading" partial-circle spinner, but it took about 4 to 5 seconds for the detail box to display in full. It does seem to cache - if I click on the header to close the detail box, and then click on the header again to re-open the detail box, the detail box renders in immediately. (I tried blocking the Plausible analytics and clicking some other header lines, but it didn't make any difference, so I don't think the delay is coming from Plausible.)

Plausible was an afterthought (and it was as slow previously) so it definitely isn't plausible, SwaggerUI is just slow, probably due to everything being done via javascript rather than in the html (if you view the source of the page there's practically nothing there, and the javascript bundle is 1.7MB), I haven't looked into it much but I'm sure something that builds html directly would be leagues faster

furbitron said:
At least one of the text boxes is kind of slow. I clicked on the POST /dtext_preview.json Preview DText line, and then tried to replace the "string" in the request body with my own DText. The screen echo lagged my keystrokes by several seconds.

Also, does dtext_preview.json only work with a login/API key? Even when I leave it at the default "body": "string" request body, and click Execute, I get a Code Undocumented and Details TypeError: NetworkError when attempting to fetch resource..

Same story as above with the slowness, the request not working is due to e621's api not having CORS headers, the OPTIONS requests fails (anything but GET requests will fail)
I've considered proxying requests to ensure everything could work, but that's dangerous for me and my servers

EDIT: I've made the discovery that while the dtext preview route does not require authorization per se, it does require a CSRF token if you aren't logged in... so for all intents and purposes it requires auth, and I'm going to add that to the spec

furbitron said:
When I click on GET /mod_actions.json Search Mod Actions, and the detail box expands, the simple comma-separated list for search[action] is kind of hard to read. I think it would be better as a couple of columns or something - BUT - I realize this may be automatically formatted from the source, without a good way to reformat it. If I click the Try it out button in that section, that comma-separated list goes away, and the drop-box presents a normal one-column list, which is easier to use.

Not much I can do about that, in the definition it's just a huge list

furbitron said:
This might be out of scope for the API documentation, but maybe it could link to some other documentation (Github changelog for the main e621 code?) that explains that some of the possible responses have changed over time. For example, the mod_actions.json API documentation correctly mentions tag_implication_create as a possible search key - BUT - the last action with that key was in December 2021. I assume there was some kind of code change to the main e621 code that took it away.

If you'll notice in the link above I do separate the legacy actions to the end, but I never added any notice in the description of the route, I never really put much thought into it