REST API Usage Documentation / Examples #13334
Replies: 2 comments 2 replies
-
|
I guess this is better even if it's only one example. It gives me a vague idea of what to do https://argo-workflows.readthedocs.io/en/latest/rest-examples/ |
Beta Was this translation helpful? Give feedback.
-
|
Yea that example should help with the structure. The first page is pure OpenAPI spec, so it effectively assumes you know how to read & use them. And it lacks much API docs too 😕 You can also take the spec and plop it into Postman/Insomnia/Hopscotch (etc). Those and other tools can generate cURL commands from the spec. Also there are a few auto-generated SDKs as well (which are not that great) as well as custom SDKs like Hera (which are great). See https://argo-workflows.readthedocs.io/en/latest/client-libraries/ PRs welcome to improve docs! |
Beta Was this translation helpful? Give feedback.
-
|
Yeah, I was going to focus on the Java client, which has atrocious class names! but even then this seems to be a common problem with API docs from my experience. I want real world examples of Json bodies, not just a hypertextual list of all possible parameters and I have to use my imagination to figure out what is actually needed. I guess I'll manage. I'm only exploring Argo as a replacement for a homegrown system at the moment. Which is why API integration is important. I guess I'm just a different kind of neurodivergent from people that love swagger tho 🤷♀️
…On Thu, Jul 11, 2024, 11:33 AM Anton Gilgur ***@***.***> wrote:
Yea that example should help. The first page is pure OpenAPI spec, so it
effectively assumes you know how to read & use them. And it lacks much API
docs too 😕
You can also take the spec and plop it into Postman/Insomnia/Hopscotch
(etc). Those and other tools can generate cURL commands from the spec.
Also there are a few auto-generated SDKs as well (which are not that
great) as well as custom SDKs like Hera (which are great). See
https://argo-workflows.readthedocs.io/en/latest/client-libraries/
—
Reply to this email directly, view it on GitHub
<#13334 (reply in thread)>,
or unsubscribe
<https://github.com/notifications/unsubscribe-auth/AAMUMHOSA5UKKI27GP7UQ23ZL2QVZAVCNFSM6AAAAABKV6TCC6VHI2DSMVQWIX3LMV43URDJONRXK43TNFXW4Q3PNVWWK3TUHMYTAMBSGI3DMNY>
.
You are receiving this because you authored the thread.Message ID:
***@***.***
com>
|
Beta Was this translation helpful? Give feedback.
-
For sure; that's kind of what happens with generated docs and clients. Custom SDKs need a lot of maintenance (Hera has a whole team behind it, a substantial portion of which are paid by employer to work on it too), so it's non-trivial for every API to have them, especially in the often heavily under-resourced and volunteer-run world of OSS. The Argo API is also mainly an intermediary to k8s, so most of it inherits the same specs as the k8s CRs (which do have plenty of examples and docs).
Idk if anyone "loves swagger" 😅 It's just a standard API interface to follow that helps a heck of a lot with consistency, automated tooling, etc. Codegen ain't always great (and rarely perfect), but it can be a heck of a lot better than nothing or unmaintained, unidiomatic manual writing and makes integrations more straightforward at least (but not necessarily easy still). Argo has a lot of different codegen and it is not the most fun to use, but it does get the job done at least. In my experience, I think that applies to most generated tooling; "not perfect, but gets the job done" tends to be an expectation that isn't disappointing 😅 |
Beta Was this translation helpful? Give feedback.
-
I found the OpenAPI spec https://argo-workflows.readthedocs.io/en/latest/swagger/ but I can't make heads or tails of it. Maybe I'm stupid, but I don't have any idea how to translate this information into something useful like a cUrl command. Should I just focus on a client library and reverse engineer? What am I missing?
Beta Was this translation helpful? Give feedback.
All reactions