The API docs on join-lemmy.org are actually JavaScript SDK docs, not API docs. I want to build an API client in a different language, not write a JavaScript thing using the SDK, and would prefer not to plumb the JS SDK code to understand the API.
Is there somewhere that has a language-agnostic description of Lemmy’s APIs?
This post is very old, but it’s what came up when I googled it, so for anyone else, here’s some basic scripts for logging in and then using the authentication to get something that may help you get started in exploring the API.
This is just what I was looking for! Thank you 🍋
The HTTP docs are what you want: https://join-lemmy.org/api/classes/LemmyHttp.html#getPost
It tells you the full input and output types, and if you click the defined in link, it shows you the endpoint you can use for curl.
Example from above:
return this.wrapper(HttpType.Get, '/post', form);We do it this way because the lemmy-js-client exactly matches what you need to build a client, and is completely auto-generated. Before we used to manually maintain other API docs, and it was a huge hassle to keep them updated.
Docs are pretty bad, let me give you a start,
To get the first page of post of a community,
curl "https://lemmy.ml/api/v3/post/list?community_name=lemmy&limit=2&page=1"You can paste that json object in a formater somewhere to get an idea of the shape of the data.
To find the other endpoints ignore the javascript docs. They are to hard to read.
Look at, the api_routes file. https://github.com/LemmyNet/lemmy/blob/main/src/api_routes.rs
Now you should be able to put two and two together to get the whole picture.
How are the docs bad? They exactly match what we are using.
Several ways:
- They don’t simply describe the API. The description of the API is embedded in a particular (JavaScript) implementation of the API client.
- There are almost no textual descriptions of anything, and the ones that do exist are useless, because all they do is repeat the name of the function. For example, the full documentation for
deleteCommunity()is “Delete a community.” In what circumstances may I delete a community? What authentication needs to be performed before this function is called? What response should I expect if the deletion failed? - The actual payload structs all have almost no documentation. What’s the difference between
DeleteCommunityandRemoveCommunity? Okay, so only an admin can remove a community, but like… what do these things actually do? - There’s no place to see everything about an endpoint: its URL, request/response types, etc. It’s strewn all over the place, making it harder to find.
likePosttells you part of the URL, and the method. You have to click through toCreatePostLiketo see the shape of the request body, andPostResponse(and thenPostView) to see the expected response… but only on success. For errors, I have no idea. I got down intowrapper(), but it looks like it simply may not implement error handling at all. Figuring out the URL is another slog, this time throughbuildFullUrl()and the constructor.
In short: The API isn’t really documented, and building a new API client requires reverse engineering the JavaScript one.
Before we used to manually maintain other API docs, and it was a huge hassle to keep them updated.
Certainly, writing documentation is work. But the decision to stop doing it externalizes and multiplies the hassle – it shifts from the Lemmy developers needing to maintain documentation once, to any programmer wishing to interact with Lemmy needing to RE the JS client, every time.
Autogenerating Swagger documentation may be one way to reduce the burden on the Lemmy maintainers.
For example, the full documentation for deleteCommunity() is “Delete a community.” In what circumstances may I delete a community? What authentication needs to be performed before this function is called? What response should I expect if the deletion failed?
Click on the form, and it tells you exactly what are the required fields, and the output type for what you’re getting back.
There’s no place to see everything about an endpoint: its URL, request/response types, etc.
Except for the exact endpoints (which are linked directly in every method description), every single input and output is fully expandable and described.
It doesn’t require reverse engineering anything, just click a few links.
Well, I can see that this isn’t going to be a productive conversation, so I’m out.
I’ll just leave you with this: you have two people here who agree that docs need significant work, and I gave a detailed list of specific things that need addressing. Ignoring half the issues to say, essentially, “you’re wrong, just click around” is not helpful.
Forgive me for being to dumb; it just doesn’t seem as clear as something like swagger
You link to some Java script instead of full path ways.
Listing a few curl examples would go a long way to making the api more understandable IMO.
But maybe I’m just to dumb to understand.
