Total n00b question here: I find myself having to manage mission-critical data about my farm via this JSON:API interface, which is more of a chore than i think it should be, so i am wondering: can i use Postman to build my own OpenAPI interface on top of that foundation?
I ask because, as non-technical owner of both that farmOS instance and the farm that is its subject, i am struggling mightily to learn (and relearn, every time i sit down to do my deskwork) my way around this API. Yet i was so inspired by this Getting Started with OpenAPI in Postman video, i found it surprisingly easy to build my own “Postmanauts” collection… Then it occured to me that if i could build a API to my farmOS instance in like fashion, leveraging those powerful built-in documentation affordances, that could make my job SO much easier!
So: tho i don’t know enough about all all the underlying tech in this stack (JSON:API on farmOS.org on Drupal on… etc!), this Postman implementation of OpenAPI seems so user-friendly, i’d just like to know if i can use it to build an interface for those few simple GET and POST requests that i am having to send routinely to my database -with sufficient documentation to enable delegation of the data admin tasks to others (so i can get back to playing farmer )
Is that a naive expectation, or what?
This is not something I have done personally but I know that if you have existing OpenAPI definitions then you can import them like this;
I’d have to do a bit of reading, but happy to try and help.
I would think that if it is just a “few simple GET and POST requests” you could simply create a collection and configure the GET and POST calls that way.
If you have the cURL commands you could literally just import them.
Interesting: tho i’ve been given to understand that this JSON:API is somehow compatible with Swagger, i’m not sure if it would qualify as OpenAPI 3.x compatible… But i will try that import facility, to see if it works.
Those few simple requests were scripted in Python by a farmOS developer who’s been helping me out -which scripts we have rolled-up into a Jupyter Notebook with some explanatory documentation, but… It’s a far cry from the elegance of those docs rendered automatically in Postman’s implementation of OpenAPI. That’s what i’m really pining for, is a well-documented user interface to this API that is the only affordance we have for uploading CSV data to farmOS, and creating custom reports.
I guess my question is essentially the same (tho not so succinctly stated) as this one over at StackOverflow -still unanswered >1month after pub date- so the Q remains: Given a .json response from a resource that implements JSON:API (as in the official example), what is the optimal way to generate a .yaml OpenAPI documentation from the given file?
That’s an encouraging thread indeed, @w4dd325 -which, besides the OP’s draft spec, is followed by another spec that looks to my uneducated eye quite substantial (at ~5k lines of YAML, it oughta be! =8-0…
Clearly i’ve got a pretty steep learning curve ahead of me, before i’m near ready to say i know how this is to be done, but this gives me enough reason to feel like i’m barking up the right tree, at least. Thanks for that, @w4dd325.
Meanwhile, i’ve just begun reading “The Design of Web API’s” by @arnaudlacour , and- following his sage advice about nailing down all important Goals for the API first, before giving any attention to what goes on under the hood- am busy filling out my “API Goals Canvas.” Excellent book, b/t/w; really helps to put all these specs & techs in proper context.
)