[HN Gopher] Analyzing the OpenAPI Tooling Ecosystem
___________________________________________________________________
Analyzing the OpenAPI Tooling Ecosystem
Author : handrews
Score : 129 points
Date : 2024-09-21 19:13 UTC (1 days ago)
(HTM) web link (modern-json-schema.com)
(TXT) w3m dump (modern-json-schema.com)
| throwaway2016a wrote:
| 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...
| handrews wrote:
| 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 wrote:
| > 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 wrote:
| > 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" :-)
| re-thc wrote:
| > 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.
| lionkor wrote:
| Those make great YouTube video titles.
| flessner wrote:
| The ethos I have seen around these is usually "It doesn't
| have to be proper if it isn't making money"
|
| I think it's a fair attitude if your only goal is to make
| money, but it completely misses "why" you should build
| something... if you truly care about a problem you wouldn't
| haphazard it anyway.
| throwaway2016a wrote:
| > I think it's a fair attitude if your only goal is to make
| money
|
| Short term, yes. But it's a bit short sighted as most of
| the AI code I have seen has security and scalability issues
| that long term have potential to blow up in your face
| costing even more money.
|
| Granted that _can_ usually be fixed by better prompts. But
| to right those prompts requires the person doing the
| "prompt engineering" (rolls eyes) to actually have a
| working knowledge of a lot of areas such as architecture,
| security, software engineering best practices, etc. And a
| lot of the influencers out there pushing AI openly admit to
| "not knowing how to code" let alone knowing the right way
| to build a technology product so that it scales and is
| safe.
| re-thc wrote:
| > "It doesn't have to be proper if it isn't making money" >
| I think it's a fair attitude if your only goal is to make
| money
|
| Is that why we often get so many posts about e.g. getting a
| huge bill on AWS or GCP? Or that so and so company shut
| them down or whatever else?
|
| I've seen far too many "temporary" solutions and "quick
| fixes" that always go beyond the scope and lifetime. Never
| have such a mindset.
| madeofpalk wrote:
| Maybe I don't _truely care_ about my problem? But I just
| care a little bit, and I 've done the risk analysis.
|
| I used a whole lot of "ChatGPT just wrote it all for me"
| for a rust program that watches for and renames video game
| clips for me. Maybe it's insecure or has subtle bugs, I
| don't really care all that much because it does the job for
| me.
| throwaway2016a wrote:
| To be fair I wasn't agreeing with the "API in 20 minutes
| approach" I was only pointing out the contrast between that
| and something like this.
|
| As I tried to allude too, AI written APIs often have
| security, performance, maintainability and a whole slew of
| other issues.
|
| But at the same time, I think "blank video on your phone for
| 20 minutes" is a bit of a stretch. These AI generated APIs
| have problems for certain but they are working software and
| in many cases better working software than a non-coder or
| junior engineer could have written in a much longer time.
|
| And while I don't like the idea of tons of insecure poorly
| architected APIs being out there, the realty is, people are
| using AI generated APIs in the real-world right now, it's not
| hypothetical.
| re-thc wrote:
| > but they are working software
|
| What is "working" software?
|
| Have we lost the meaning of that now too? Samsung Galaxy
| Note 7 is a "working phone" too - it just might explode.
|
| > but they are working software and in many cases better
| working software than a non-coder or junior engineer could
| have written in a much longer time.
|
| Imagine the nurse telling you that you've got an AI doctor
| operating on you that's better than the junior surgeon. I'm
| sure you'd be happy. We've been cheapening the industry for
| a long time. Not everyone needs to produce code.
|
| > the realty is, people are using AI generated APIs in the
| real-world right now, it's not hypothetical.
|
| The reality is there is contaminated cooking oil [1],
| noodles with opium [2] and a infinite amount of issues.
| Let's not make the world worse?
|
| [1]: https://www.abc.net.au/news/2024-07-13/cooking-oil-
| contamina...
|
| [2]: https://www.washingtonpost.com/news/morning-
| mix/wp/2014/09/2...
| throwaway2016a wrote:
| Working means you give it input and it produces the
| expected output for all your defined used cases. Don't
| confuse working with good.
|
| Let's keep your analogy: AI isn't producing software that
| is the equivalent of a AAA movie title by any stretch but
| it is producing far better than a bunch of kids in a
| garage with their cell phones can make. Which is orders
| of magnitude better than 20 minutes of blank video. Which
| means that people will use it whether you like it or not.
|
| Reality doesn't care if you think it is a bad idea... in
| fact I think you and I are on the same page, I do think
| it is a bad idea... but reality will continue to exist
| whether you and I like it or not.
|
| You're not helping anyone by arguing how crappy and
| harmful it is to someone who already knows how crappy and
| harmful it is.
| dgellow wrote:
| Excellent article, I really like the diagrams
| infocollector wrote:
| Thanks for writing this! This nicely breaks it down into boxes
| that OpenAPI deals with.
|
| I still think OpenAPI usage is a bit confusing in general. For
| example, I am still waiting for a better explanation of this
| diagram with relation to a choice of backend (Python WSGI) +
| frontend (JS) combinations. Perhaps someone here has a pointer
| for me to read?
| dgellow wrote:
| If you haven't yet, I highly recommend to check FastAPI for
| your python backend: https://fastapi.tiangolo.com/. OpenAPI is
| a core part of it, making it simple to integrate with other
| tools such as docs and clients generator
| matanyall wrote:
| +1 for fastAPI
| BerislavLopac wrote:
| Or you can go straight to Starlette [0], which is much more
| streamlined to develop with. FastAPI is based on it itself,
| and while it provides many additional bells and whistles I
| find it messes things up significantly.
|
| [0] https://www.starlette.io/
| zelcon wrote:
| Please, people, just use GRPC or Thrift. This stuff makes me want
| to vomit.
| cdelsolar wrote:
| ConnectRPC here but yeah same idea.
| sunshowers wrote:
| GRPC and Thrift can't express ADTs (enums with data) easily,
| but OpenAPI can. That's worth a lot in my book.
|
| Another advantage of OpenAPI is that you can write your
| specifications using Rust types (as we do at Oxide with
| Dropshot: https://docs.rs/dropshot)
|
| edit: Apparently protobuf 3 does have oneof:
| https://protobuf.dev/programming-guides/proto3/#oneof. They
| look like they solve the problem but I can't vouch for it, and
| they appear to have some edge cases ("only the last member seen
| is used in the parsed message"). Thrift doesn't appear to,
| still.
|
| And I do think being able to write the spec using Rust types is
| really nice -- you still get an OpenAPI document as an
| artifact, and (for external users) you get wide client
| compatibility.
| throwawaymaths wrote:
| If you're building maintainable servers you should write the
| doc first and the codegen from there. Otherwise you're gonna
| be in a world of hurt when some junior changes your datatype
| or if you need to version and maintained both versions
| simultaneously from the same or similar endpoints.
| sunshowers wrote:
| You're right that this is a very difficult problem, but
| writing the document first doesn't give you much over
| generating it from types.
|
| We actually have a plan for supporting multiple versions,
| and conversions between the corresponding types, using
| Dropshot as the place where that's coordinated.
| rswail wrote:
| This "stuff" allows for easy exchange of API definitions and
| Arazzo goes to the next level to define the semantics of the
| _process_ of combining API calls.
|
| gRPC requires brittle compilation of the protobuf definitions
| that has impacted every marshalling/serialization protocol for
| remote procedure calls since XDR.
|
| Whether you like it or not, HTTP/JSON are the lingua franca of
| the internet (at least the API side of things). Protobuf is
| good if you are in control of both sides of the API, less so if
| you are just the server. It also is much less self-documenting
| than JSON Schema/OpenAPI.
| chrisweekly wrote:
| Apples and oranges? gRPC might sometimes fit the bill for
| server-to-server use cases, but it's completely unsuitable for
| integration with SPAs; grpc-web was never well-supported, and
| is now dead. I don't understand the "want to vomit"
| perspective. That implies that adding protoc to your build
| toolchain and using an opaque binary format/protocol is somehow
| much more palatable than well-documented JSON / REST over HTTP.
| What am I missing?
| zurfer wrote:
| OpenAPI is great, we use it in combination with redoc
| (https://github.com/Redocly/redoc) to have a almost 0 effort API
| for our product.
|
| But man, my tokenizer is in trouble with OpenAPI and OpenAI.
| ljm wrote:
| I keep mixing them up now too.
|
| Realised that writing a consistent API was more effort than it
| was worth compared to the one-shot setup cost of creating a set
| of basic components and re-using them to generate interfaces.
| Most of the API layer is just boilerplate and we can focus more
| on biz logic instead.
| _fat_santa wrote:
| General question. I currently have a Node API that I am the solo
| dev on and am considering bringing up to OpenAPI spec to get nice
| docs and stuff. Wanted to ask others here, for a solo dev would
| it be worth it? Or is that sort of thing really geared for teams
| where multiple people are using and integrating the API?
| Swizec wrote:
| OpenAPI is only useful if you intend for your project to become
| bigger than what fits in your head or if you intend to keep a
| project alive for long enough to start forgetting things you
| did a while back.
| jlengrand wrote:
| Or if you deliver an API and any of your users / customers
| want to use anything else than a raw API. IMHO the top value
| of OpenAPI isn't for you, it's for the people who will use
| what you make
| salomonk_mur wrote:
| Agreed. Most of the value comes when people other than you
| need (or will need) to use it.
| ljm wrote:
| The output will only really be as good as what you describe,
| really, and if you're only using it for yourself it might feel
| like overkill, particularly if you want the spec as the source
| of truth and have to rewrite your API to fit a generated
| interface.
|
| It may have more use to you if your API is quite large or re-
| uses a lot of components (e.g if you follow something like the
| JSON:API spec), because you can generate boilerplate from it
| then.
|
| Can also be useful if there's another team consuming the API,
| so you can design new endpoints and figure out the requirements
| before getting to work. That spec can then be used to generate
| mock servers or used for e2e testing.
| nilslice wrote:
| The OpenAPI ecosystem is really impressive. We went through a
| major analysis of it recently when deciding whether or not to
| create a new, custom IDL from which to generate binding/glue code
| for our WebAssembly plugin system.
|
| We knew that OpenAPI is already great at describing the
| interaction points between a client and server, and this ended up
| being a perfect fit for the plugin definition too.
|
| Since there is already so much OpenAPI spec out there, I think
| more people should build tooling based on it. Being able to take
| types that a server application already knows well, and reuse
| them to just interact with the client code locally in-process vs.
| interact with a client over HTTP is pretty remarkable!
| candiddevmike wrote:
| What does everyone use for conformance testing? I'm currently
| generating my specs from code but the idea of defining a spec,
| building the code to spec, and testing that the code conforms to
| the spec would be very interesting.
| salomonk_mur wrote:
| I personally just rely on FastAPI + Pydantic.
| Sytten wrote:
| The code generators for OpenAPI are rarely good compared to what
| you find in GraphQL in my experience. The Swagger Generator /
| OpenAPI Generator (why the fork...) that is the "standard" is
| kinda of a mess.
|
| In rust Oxide had to write their own [1] which is actually
| decent, but you really need to know it exists.
|
| [1] https://github.com/oxidecomputer/progenitor
| salomonk_mur wrote:
| How is Swagger a mess? It produces perfectly readable
| documentation and testing mechanisms.
|
| Barebones? Sure. But far from "a mess".
| nicholasjarnold wrote:
| Since I don't see it mentioned here and it's complimentary
| information allow me to mention the OpenAPI Tools website[0]. It
| lists and categorizes a ton of different tooling options from SDK
| generators, to automatic testing frameworks, etc. From some
| personal experience they vary in spec support and quality widely,
| but the listing itself is a good starting point if you're in a
| position to start evaluating tooling for a team you're on or
| company you're working with.
|
| [0] https://openapi.tools/
| gunsch wrote:
| I spent a few years building OpenAPI-related tools at Google,
| collaborating with Apigee.
|
| One of the "open secrets" about OpenAPI's history was how
| Smartbear spun out the OpenAPI _spec_ to be a community-managed
| spec, but with the requirement that there wouldn 't be official
| _tooling_ offered with it --- arguably to protect Smartbear 's
| investment in Swagger. (it's been a minute so specifics are hazy
| but IIRC it was something like this). The tooling ecosystem feels
| pretty disjointed as a result.
|
| Compare to gRPC/protobuf, where the specification and tooling
| have been developed together. Parsers, static analyzers, code
| generators, documentation tooling all happen in lockstep with
| spec development, and the ecosystem feels much more cohesive.
| The_Colonel wrote:
| > but with the requirement that there wouldn't be official
| tooling offered with it --- arguably to protect Smartbear's
| investment in Swagger
|
| That kind of seems backwards. If there was a official tooling,
| it would be Smartbear's (who else would provide it?) This
| clause actually seems to be designed to limit Smartbear's
| ability to use OpenAPI to push their products (and at the same
| time push OpenAPI as a credibly vendor-independent spec).
|
| > Compare to gRPC/protobuf, where the specification and tooling
| have been developed together.
|
| Yes, because it's a protocol pushed by one company, not
| pretending to be independent.
___________________________________________________________________
(page generated 2024-09-22 23:01 UTC)