1y ago

Lemmy API documentation is challenging to work with

Lemmy's API documentation currently appears to be the JS client implementation found here: https://join-lemmy.org/api/

This is very misleading, as these docs document the behavior of the JS client and do not provide a language neutral way to figure out what's going on.

Compare Lemmy's docs with something like the ActivityPub docs https://www.w3.org/TR/activitypub/

Going off ActivityPub, I could actually start to see how it all works and looks together. With Lemmy, I can reason about how the JS client works and do my best, but working with Lemmy you sometimes have to consume the Rust source as well.

So, this raises the barrier of entry for someone wanting to do Lemmy integrations to someone that needs to consume the above docs, plus be comfortable reading JS and Rust.

I saw some older posts from the lemmy devs saying: "Well, writing docs is hard, so it's easier if we generate the docs from our JS client."

They aren't wrong, writing documentation IS hard. If Lemmy is serious about attracting a larger ecosystem, I consider better API documentation to be on the hot path. I'm concerned that the devs are happy with the autogenerated docs above and won't put any effort into improving them. Even worse, the people generating these docs are already familiar with Lemmy, so they probably think the current docs are adequate.

I don't know a quick solution -- raise money to pay someone to write docs? No clue. But, if you want to attract developers to this ecosystem, the current API documentation is insufficient.

18 comments

at this point the codebase is in daily flux, it really comes down to RTFS. the transition from websockets to http seems to be mostly in-place, so there may be some opportunity to begin normalizing the docs.
totally agreed on the need for more complete and accurate documentation, but without an auto-documenting sourcecode framework, I would expect API documentation to lag. in the meantime we just live life on the edge - it will improve over time.
edit: word
- Yes exactly - living on the edge!
  One way to learn the new API is - explore the code of (similar) extensions and browser scripts, to see how they build and send their calls.
- I was curious to see if the reply was going to be:
  We are happy with the state of docs (WONTFIX)
  OR
  The current situation is temporary and we will provide better docs at some point in the future

I agree. Rate-limiting 503 responses, parameters unclear.
I think a bash script with curl/wget showing all the API calls and also having it as a way to test servers would be good. The official testing scripts use the Javascript library, but I often have to go to the Rust code to really understand he parameters.
I also often just go to my own instance and grep the logs of lemmy_server to reverse-engineer lemmy-ui behavior.
- Your experience mirrors mine, where you must refer to the Rust and/or JS code to have a chance in hell.

I agree. I was planning on making an API library for dotnet, but having to copy the JS client types, manually convert them, it was all just a huge a hassle. It's in a half-completed state on my hard drive somewhere because I got bored.
- Yep... and if you and I got discouraged, how many other developers did as well? This is why good docs are essential for a healthy ecosystem.

Is there a specific API call you'd like to make?
Maybe someone can reveal that method and endpoint.
- No, I was just chewing on various ideas to integrate with Lemmy and was disappointed with the docs I saw. They seemed OK-ish if you wanted to use the JS client, but not great if you want to do something else.
  On similar projects, I'm used to seeing OpenAPI/Swagger/etc. where you have docs on the incoming bodies/fields, what values they can contain, etc.
  Right now it's really bare bones. I see things like 'auth' OPTIONAL but not really sure what would go in there.
  I can RTFS like another poster said, but of course that's not as convenient as "general purpose" API docs with examples / tutorial.
  
  Yeah, I understand what you mean (after a year of exploring the Web Socket).
  That lemmy auth value is pulled from a JWT cookie in the browser - which you can access in JS by document.cookie. It allows user-specific API calls (retrieving saved posts, subscribed communities, etc).

I'm sure with the recent increase in alternate apps being built on the Lemmy API recently there will be more issue tickets to polish the rough areas even with it being in flight. I'm sure we'll see a lot of third-party guides that will be written soon too and contributors will likely try merging the best parts of those into the official docs. Lemmy was a small project nearly fully developed by the core devs and community of only ~1k mostly technical people prior to May.
GitBounties + donating to the core devs via liberapay / opencollective would be great, but if you have a specific solvable problem in the docs, submitting a pull request with the suggested change yourself would likely be appreciated even more.

18 comments