Programming

17479 readers

320 users here now

Welcome to the main community in programming.dev! Feel free to post anything relating to programming here!

Cross posting is strongly encouraged in the instance. If you feel your post or another person's post makes sense in another community cross post into it.

Hope you enjoy the instance!

Rules

Follow the programming.dev instance rules
Keep content related to programming in some way
If you're posting long videos try to add in some form of tldr for those who don't want to watch videos

Wormhole

Follow the wormhole through a path of communities [email protected]

founded 1 year ago

MODERATORS

snowe

Ategon

[email protected]

Question: How to curl the lemmy API? (lemmy.world)

submitted 4 months ago by [email protected] to c/programming

19 comments fedilink hide all child comments

I've seen these posts

But actually I haven't been able to figure out exactly how to get the posts a user has made in lemmy. I've seen this page but I think this is for a different lemmy instance, I'm not sure https://join-lemmy.org/api/interfaces/GetPosts.html

Can anyone point me to a documentation on how to make this?

you are viewing a single comment's thread
view the rest of the comments

[–] testAccount 2 points 4 months ago (1 children)

I do not see how critisms for the JS API docs are relevant for my openapi documentation.

This documentation aims to solve all those problems in a language agnostic way. It descibes the endpoints, the request object, the status, the response object, the authentication needed in visual/text. It allows you test it right from the browser, allows you to copy a working curl command, search for endpoints based on keywords, allows you to import the entire spec into postman/alts.

I ve never had any problems with CF instances but I mostly test with voyager.lemmy.ml

[–] refalo 2 points 4 months ago (1 children)

Yours is a little bit easier to read, but my main problems remain the same. Here's some initial comments looking at your swagger link from the perspective of a user who is brand new to the lemmy API (and doesn't use Javascript):

I can't tell what the general flow of the API usage in general is. Am I supposed to login/authorize somehow first? Some common examples, especially in at least one programming language (whether that's curl or python or whatever) I think would go a long way to help people understand what they're supposed to do.
How do I know if I need to authorize for a particular endpoint?
What is the entire URL for any given endpoint? It's never really explained clearly.
What is this "servers" dropdown? What's the difference between those?
Endpoint descriptions are often unhelpful. /user says "Get the details for a person." It doesn't tell me this is actually how I'm supposed to find their comments or posts. Nothing tells us this.
We have to guess what endpoint we might need for a lot of things. Example: /post/like is also for dislikes, but it doesn't tell you that. It also never tells you HOW to like or dislike anything, the valid values of score do not appear to be documented. And you're left to assume that's the right field to even use for it.
What is the content type of the request supposed to be? JSON is never mentioned anywhere.
What are these named "parameters"? Is that a query parameter? Why does it say "object" and "(query)"? Does this parameter go in the request body instead? /user shows a parameter called "GetPersonDetails" except in reality this name is (I guess) supposed to be completely ignored, because no part of the request actually uses the string "GetPersonDetails".
Schema is missing for many endpoints, like the request part of /user.
What are all these fields under "GetPersonDetails"? Are they all required? Only some? It doesn't say anything about it.
Many of the possible error codes are undocumented.

There's probably more but that's the main stuff I think.

[–] testAccount 0 points 4 months ago

I can’t tell what the general flow of the API usage in general is. Am I supposed to login/authorize somehow first? Some common examples, especially in at least one programming language (whether that’s curl or python or whatever) I think would go a long way to help people understand what they’re supposed to do.

This could use indeed some work

How do I know if I need to authorize for a particular endpoint?

openapi spec allows one to specify the authentication, this has not be done already because there is an open issue to include auth in lemmy-js-client (I use this to generate the spec) + Need to figure the best approach to convey "elevated" auth endpoints. Endpoints like GetSite where authentication enhances the response.

Endpoint descriptions are often unhelpful.

They are actually summaries, they are fine imo. There is an open issue to add the descriptions though.

We have to guess what endpoint we might need for a lot of things. Example: /post/like is also for dislikes, but it doesn’t tell you that. It also never tells you HOW to like or dislike anything, the valid values of score do not appear to be documented. And you’re left to assume that’s the right field to even use for it.

Yes indeed, things like this should be documented in the description.

What is the content type of the request supposed to be? JSON is never mentioned anywhere.

This is explicitly mentioned on every request, visually and in the spec.

What are these named “parameters”? Is that a query parameter? Why does it say “object” and “(query)”? Does this parameter go in the request body instead?

Query is mentioned when they are query parameters, else it just a request body. This is pretty clear in the text (spec) or visually imo.

/user shows a parameter called “GetPersonDetails” except in reality this name is (I guess) supposed to be completely ignored, because no part of the request actually uses the string “GetPersonDetails”.

GetPersonDetails is the name of the object if you scroll all the way to the bottom you can inspect it. This more clear in the spec.

Schema is missing for many endpoints, like the request part of /user.

There is not a single endpoint missing nor its requests.

What are all these fields under “GetPersonDetails”? Are they all required? Only some? It doesn’t say anything about it.

This could be improved.

Many of the possible error codes are undocumented.

Status codes? or the 400 lemmy error? ex: { error: "report_reason_required" } Status codes are the same everywhere, 200/201 or 400 with Lemmy error as response. There is one exception that is 401 that can be thrown for every auth required endpoint where auth fails. But these are standard. Ig this should documented.

Now the "LemmyErrorTypes". This could be improved, but it is hard to, not possible to be automated and tedious to add and frequently changes.

Thanks for the feedback.