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.