throwaway2016a
7 hours ago
I find it striking that in the same day I saw a video about how someone "Made an API in 20 minutes with one prompt" and this. The two approaches seem very divergent. One that is almost cavalier about things like security, standards, etc and another that is (almost) over engineered.
One observation, is that I there are two trains of thought. Using OAD (Open API Descriptions) as a source of truth and generating code from there or treating OAD as an artifact that comes out of some other tools.
I personally see OpenAPI as kind of a glue that can allow different tooling to be able to speak the same language.
Overall I found the linked Moonwalk[1] document to be more interesting. But there is some interesting analysis to be found in this article as well.
[1] https://www.openapis.org/blog/2023/12/06/openapi-moonwalk-20...
re-thc
a minute ago
> I find it striking that in the same day I saw a video about how someone "Made an API in 20 minutes with one prompt" and this
You can also record a blank video on your phone for 20 minutes and call that a movie. Would anyone watch it?
You can also build a house in days. Would it crack? Is it maintainable? What happens later? Who knows.
handrews
7 hours ago
Yeah this article is more about how we (the OpenAPI Initiative) are designing the next versions of the OpenAPI Specification than it is about how to use it. The diagram does include both an OAD generator and editor, intended to encompass both code-first and description-first (which doesn't make too much difference for this blog post). The Moonwalk article is definitely more general purpose! This is "OK Moonwalk has a great vision, but how do we actually make it a real spec?" I've been using variations of this diagram in the weekly Moonwalk calls for the past month or two.
throwaway2016a
7 hours ago
> OK Moonwalk has a great vision, but how do we actually make it a real spec?
I'm not sure the article really succeeds if that was the goal. I suspect that there might be some aspects of the discussion that are taking place that are missing from the article making it a little difficult for someone who wasn't in those discussions to connect the dots.
Don't get me wrong, I think the article had some useful pieces in it, I just think if that was the goal of the article it could possibly use some additional framing for people who don't have the full context.
With that said, I really appreciate transparency into the thought process!
handrews
6 hours ago
> I just think if that was the goal of the article it could possibly use some additional framing for people who don't have the full context.
It's always a struggle to figure out how much explanation to put in before people see something like "20 minute read" and just refuse to read it. (BTW I don't mind the critical feedback at all- I'm just glad you found something useful in it).
But keep in mind that _we_ haven't answered "how do we actually make it a real spec?" either! This is a snapshot of our efforts at this particular moment. Also, there's a reason that this is "part one in a series" :-)