mccPeople who design APIs. I am begging you. It doesn't matter how "simple" or "intuitive" or "elegant" your API is. You need to include sample code.
β΄β΄β΄ΓπΖ.Ζκβ΄π₯ΡΙΌπ©π»βπ»@mcc Or, you know, your API could tell you in its endpoints exactly how your API works.
@AeonCypher No!!! You need example code!! You make the endpoints clear and then 20 minutes later I'm scratching my head at why there's a thrown exception inside your code, or losing time because dotnet is insisting there's no package named "Mlem.Startup" because unbeknowst to me it's named "MLEM.Startup". There's always something!!!
@mcc I haven't made APIs in a long time. However, when I did I wrote them in such a way that the API would be self describing (hypermedia/HATEOS) and would be completely self documenting.
It was impossible for the API to incorrectly self-describe or have out of date specs, because the API was generated by introspection on the interface that handled the API.
Sample code: HTTP requests, would be identical to the description of the HTTP properties.
But, maybe I'm missing something.
It was impossible for the API to incorrectly self-describe or have out of date specs, because the API was generated by introspection on the interface that handled the API.
Sample code: HTTP requests, would be identical to the description of the HTTP properties.
But, maybe I'm missing something.
@AeonCypher Here is an example of something that couldn't be self-documenting in the endpoints, because it concerns something that exists outside the endpoints. https://mastodon.social/@mcc/111882244957795896 If I don't know what package/namespace UntexturedStyle is in, I don't even know what set of self-documenting endpoints to get out.
@mcc Ah. You are referring to in usecases like packages and libraries.
I agree, you should have example code.
I agree, you should have example code.
@AeonCypher An example of something for HTTP RPCs which exist "outside" of endpoint documentation however are things like how to obtain an API key, or what port you're running on.
@mcc Just to be clear, I'm not a fan of RCP.
There's no reason an HTTP endpoint can't also have text/html links to signup.
It's relatively common for hypermedia APIs to report back request information.
Everything you need to do from an endpoint should be available from that endpoint. You don't have to go look up instructions on how to use Amazon or Google. There are forms and links.
There's no reason an HTTP endpoint can't also have text/html links to signup.
It's relatively common for hypermedia APIs to report back request information.
Everything you need to do from an endpoint should be available from that endpoint. You don't have to go look up instructions on how to use Amazon or Google. There are forms and links.
Riley S. Faelan@AeonCypher "Endpoint" is a term from an entirely different realm of APIs. One that's so close to bordering absurdity that people who believe in them might as well talk about "Discord servers".
@AeonCypher @riley An RPC API is certainly a type of API. However, I do not understand why so many people have responded to my initial post on the assumption that the word "API" refers to an RPC API and not anything else.
@AeonCypher It's so insolent an answer that I must tirritate you by calling CONNECT an endpoint.
@AeonCypher @riley i disagree with this statement completely