> APIs have been around for a while. For instance, the painful Simple Object Access Protocol (SOAP) used APIs in the early 2000s, but they really started getting interesting when representational state transfer (REST) came along. REST, which used the ubiquitous HTTP protocol, was lightweight and fun to work with.
Umm, yes, there were no APIs before the 2000s. Even ignoring non-web APIs there were plenty of pre-SOAP attempts at APIs on the web. XML-RPC was created in 1998 and is the direct predecessor to SOAP.
It feels like the author of this post has no historical perspective on the technology he is trying to explain, and if he skipped all the "What is an API" preamble that would be fine, but with it there it feels like an attempt at sounding like an authority that backfired.
I tried to see who this "Jesse Menning" is, but the author link goes to a twitter page for "Jeremy Menning" that hasn't seen use in 10 years. I'm not sure I should really put much trust in a blog post by an author that doesn't even know his own Twitter handle.
> Umm, yes, there were no APIs before the 2000s. Even ignoring non-web APIs there were plenty of pre-SOAP attempts at APIs on the web. XML-RPC was created in 1998 and is the direct predecessor to SOAP.
They didn't say SOAP was the first. They said APIs have been around for a long time, and brought up an older method that's probably relatable for many as an "old" attempt.
> I'm not sure I should really put much trust in a blog post by an author that doesn't even know his own Twitter handle.
Understanding of APIs and ability to avoid typos are likely extremely unrelated.
I worked on OpenAPI itself and have been working on the tooling since. I recently switched to GraphQL for a project and god damn! The GraphQL design is nearly perfect and achieves whatever OpenAPI or AsyncAPI was hoping to achieve. If you have an existing JSON over HTTP (Let's not call them RESTful) API then it's harder to switch to GraphQL, but if you have a new project and want type-safety and efficiency, you must give GraphQL a shot instead of writing "hopefully will be enforced in runtime API specs".
Is GraphQL useful to people who write a lot of custom-written JSON APIs? Things that are much more than cleanly mapping JSON to CRUD SQL?
Ie i often think of GraphQL as a DSL for translating JSON to SQL. To let the caller define the query and data needed. This looks great for SQL, but if i write a custom API with non-SQL generated data, maybe in some custom data structures, the idea of supporting arbitrary querying over my data structures seems .. difficult.
Is GraphQL applicable to more than basic SQL data querying?
Can someone tell me what the heck AsyncAPI actually does? I've had it bookmarked for a few years because it sounds relevant to the types of things I work on, and I often return to glance at the docs for a while.
Is there a benefit to describing APIs using YAML instead of just, y'know, prose? Seems like basically all you can do is generate HTML docs from YAML. Ok, so let me get this straight: instead of writing docs, I write YAML... --Either way I write 1 thing,--but now I can only create docs from the problem space of the known YAML schema. So it's a lossy abstraction.
Looking around I see you can now do some basic code gen of models in any language, as long as that language is python or matches the regex /java/ . But usually these messaging systems already use some data format with schemas and code gen tools like protobuff or avro! It's not just redundant, it's a collision, because something might not match up right.
Unless there's something else, it seems like something I'd advise to NOT use.
I think the core goal is to have one machine-readable source of truth for your API. You can write docs, the API interface, API input validation, API correctness tests, performance tests, and 10 per-language SDKs & clients all by hand, but then they very quickly get out of sync, and nobody knows which is 'right'. If you write docs as prose, good luck keeping it updated when management wants it translated into 10 languages and the API changes every week.
Meanwhile, at least in theory, with a good central spec you can generate at least the docs & much of this code, or alternatively automatically validate custom implementations & real traffic to get immediate warnings if there are discrepancies.
There's a lot of power in formal specifications.
That is all dependent on tooling though. OpenAPI is far ahead in that respect, and can achieve this goal for most HTTP APIs & a huge list of languages (see https://github.com/OpenAPITools/openapi-generator) pretty effectively. AsyncAPI is much newer though, and I think the ecosystem is still quite small, but hopefully they'll get there too eventually.
> Is there a benefit to describing APIs using YAML
"describing HTTP APIs using YAML" (or JSON) is OpenApi/Swagger.
AsyncAPI appears to be the "OpenApi, but for message queues" (and similar async communication mechanisms).
> Basically all you can do is generate HTML docs from YAML.
With OpenApi, you can generate interactive docs, where you can build and execute requests against a real API (not in prod, we hope)
You can generate code off OpenApi (and not just python and Java*). Anything from just DTOs to full clients. You can generate stub servers. You can inspect server code and flag up where it differs from the spec. You can test your API.
Outside of html docs, it's purpose is similar to swagger
* Auto generate mock / containers for testing
* Generate server interfaces
* Generate models that go across the wire
* Remove boiler plate to spin up an async client, sqs, kafka etc.
That being said most of the generators are from the node sides and left a bit to be desired. I also see it falling into the same issue as open api. Most places I've been dynamically generate the open api spec.
I had written a JVM async/open api gradle plugin. That generated all the above. The nice thing was that if your server didn't implement the agreed upon spec it would fail to compile. Allowing for asynchronous development, back end/mobile/front end agree on the spec and can work on the feature at the same time.
This can also be expanded into k6/gatling. Hit this endpoint, guarantee this sla and ensure everything functions as expected. By having the contract first, you can automate a majority of the down stream tasks.
I think it has a use for contract first development, and is good in conjunction with something like avro. But it serves best in a contract first flow. Where in you define a spec, if it compiles you match the spec. Most servers don't take in a spec and define routes off operation names.
Why not dynamic async api generation? A lot of the generators reflect at run time, slowing down startup, and don't provide the most human readable definitions. Also lagging behind the latest implementation, and miss potential new features.
let me give an example of how I wanted to use this. For fun I was working on the backend for Dogehouse (open source clubhouse clone) for a while, and for whatever reason the creator wanted the entire API to go over websockets. Ok, well, sounds like a fun thing to play around with [0]. Maintaining API consistency between the FE and BE was... very challenging, because there was very little discipline in the FE, because it was mostly into/junior programmers with not a lot of experience with API change management and feature discipline, testing, etc. So I really wanted to use AsyncAPI to create a contract between the FE and BE to be able to enforce that discipline - by auto-generating validators that get injected into the code and raise hell if invalid content is pushed by either FE or BE.
It wasn't really ready for that yet at the time, but I think over time AsyncAPI will be the way to go.
[0] in retrospect probably would have been better as a normal MVC app with only the chat and audio parts over ws, but... Again, not my project.
seems like we should just modify the openAPI spec to support async functionality. GRPC suports async in this fashion and it's much easier to reason about and adopt in specific cases.
very depends on your use case and what you want to achieve in the end. Code gen? types gen or entire app? docs only? discovery? It always all depends :)
I couldn’t find anything about it being on hiatus, though it hasn’t had any updates on the spec from the looks of it, assuming I have it right[0]. Though for a spec I don’t feel like that means it’s in hiatus, they tend to move slowly
AsyncAPI is about specifying push-based APIs (which are still far less standardized imho), and not about if a HTTP endpoint processes requests asynchronously (if that's what you meant). For example, if you let clients connect to your system via WebSocket - how do you specify the format of the push messages sent over the WebSocket channel?
I _think_ the reason that the comparison with OpenAPI feels weird is because OpenAPI uses one (and only one) communication interface in REST. AsyncAPI is trying to accomplish the same thing without a consensus in communication interface. This requires that any specs are far more abstract to encompass the possible options.
But consider what OpenAPI/Swagger actually changed - it made for a singular page to tell a user (or machine) all the possible ways to interact with the service and what the shape of the requests and responses would look like. AsyncAPI is meant to do the same, but it's much harder to grok with all the various protocols generalized into unnatural-looking fields/URIs/etc.
AsyncAPI and OpenAPI are different ways of defining application programming interfaces (APIs), also commonly known as API specs. Both API specs serve a crucial role in defining and governing distributed computing systems, but AsyncAPI and OpenAPI are used for different styles of integration...
AsyncAPI as spec is good but unfortunately tooling not yet on same level as for OpenAPI yet. During small project development with it I found few things that was Ok from spec perspective but doc generator not able to render docs with those features at all. And because tooling currently only following recent version of spec on any spec update you might find that any hosted tools not works for you anymore. But of course is just matter of time then tooling will be good enough.
From what I gather, AsyncAPI is an event-defining tool. So you can define specifically what sort of messages is expected from a service when you communicate with it. That sounds useful.
I don't understand, though, what it has to do with Async. Most messaging is done synchronously after establishing a live connection.
Why not call it EventAPI? Or MessageAPI? AsyncAPI implies it is the opposite of what it is. This name will uniquely cause a lot of confusion.
I’ve read through the spec, and there’s not really much here that you can’t accommodate with protobuf Service definitions. I do like the provider abstraction on top of push-based messaging services, but that’s just an isomorphism for a protobuf server streaming call. Given the rock solid implementation and wide acceptance, I don’t see any reason to use this over gRPC.
Suppose you are implementing a chat server that uses websockets with plain old json payloads. You want the simple human introspectability of json if you need to debug in prod via the web console. And you have a {big | distributed | lots of juniors} team so you want some code that validates the json payloads (via jsonSchema) in the two-way contract and limits errors being pushed to prod.
One major drawback is the lack of Java native tooling vs e.g. Swagger/OpenAPI springdoc project. Document generation + API validation can be part of the same build, instead of having to have a separate Node toolchain and build.
Since when does API only mean "web service"? The article talks about APIs being important to "modern" software development, SOAP being an "early" example of one, in the early 2000s, etc. I mean, the Win32 API comes to mind immediately.
[+] [-] VenTatsu|4 years ago|reply
> APIs have been around for a while. For instance, the painful Simple Object Access Protocol (SOAP) used APIs in the early 2000s, but they really started getting interesting when representational state transfer (REST) came along. REST, which used the ubiquitous HTTP protocol, was lightweight and fun to work with.
Umm, yes, there were no APIs before the 2000s. Even ignoring non-web APIs there were plenty of pre-SOAP attempts at APIs on the web. XML-RPC was created in 1998 and is the direct predecessor to SOAP.
It feels like the author of this post has no historical perspective on the technology he is trying to explain, and if he skipped all the "What is an API" preamble that would be fine, but with it there it feels like an attempt at sounding like an authority that backfired.
I tried to see who this "Jesse Menning" is, but the author link goes to a twitter page for "Jeremy Menning" that hasn't seen use in 10 years. I'm not sure I should really put much trust in a blog post by an author that doesn't even know his own Twitter handle.
[+] [-] staticassertion|4 years ago|reply
They didn't say SOAP was the first. They said APIs have been around for a long time, and brought up an older method that's probably relatable for many as an "old" attempt.
> I'm not sure I should really put much trust in a blog post by an author that doesn't even know his own Twitter handle.
Understanding of APIs and ability to avoid typos are likely extremely unrelated.
[+] [-] mirekrusin|4 years ago|reply
[+] [-] msoad|4 years ago|reply
[+] [-] lijogdfljk|4 years ago|reply
Ie i often think of GraphQL as a DSL for translating JSON to SQL. To let the caller define the query and data needed. This looks great for SQL, but if i write a custom API with non-SQL generated data, maybe in some custom data structures, the idea of supporting arbitrary querying over my data structures seems .. difficult.
Is GraphQL applicable to more than basic SQL data querying?
[+] [-] zzbzq|4 years ago|reply
Is there a benefit to describing APIs using YAML instead of just, y'know, prose? Seems like basically all you can do is generate HTML docs from YAML. Ok, so let me get this straight: instead of writing docs, I write YAML... --Either way I write 1 thing,--but now I can only create docs from the problem space of the known YAML schema. So it's a lossy abstraction.
Looking around I see you can now do some basic code gen of models in any language, as long as that language is python or matches the regex /java/ . But usually these messaging systems already use some data format with schemas and code gen tools like protobuff or avro! It's not just redundant, it's a collision, because something might not match up right.
Unless there's something else, it seems like something I'd advise to NOT use.
[+] [-] pimterry|4 years ago|reply
Meanwhile, at least in theory, with a good central spec you can generate at least the docs & much of this code, or alternatively automatically validate custom implementations & real traffic to get immediate warnings if there are discrepancies.
There's a lot of power in formal specifications.
That is all dependent on tooling though. OpenAPI is far ahead in that respect, and can achieve this goal for most HTTP APIs & a huge list of languages (see https://github.com/OpenAPITools/openapi-generator) pretty effectively. AsyncAPI is much newer though, and I think the ecosystem is still quite small, but hopefully they'll get there too eventually.
[+] [-] SideburnsOfDoom|4 years ago|reply
"describing HTTP APIs using YAML" (or JSON) is OpenApi/Swagger.
AsyncAPI appears to be the "OpenApi, but for message queues" (and similar async communication mechanisms).
> Basically all you can do is generate HTML docs from YAML.
With OpenApi, you can generate interactive docs, where you can build and execute requests against a real API (not in prod, we hope)
You can generate code off OpenApi (and not just python and Java*). Anything from just DTOs to full clients. You can generate stub servers. You can inspect server code and flag up where it differs from the spec. You can test your API.
[+] [-] soulnothing|4 years ago|reply
* Auto generate mock / containers for testing
* Generate server interfaces
* Generate models that go across the wire
* Remove boiler plate to spin up an async client, sqs, kafka etc.
That being said most of the generators are from the node sides and left a bit to be desired. I also see it falling into the same issue as open api. Most places I've been dynamically generate the open api spec.
I had written a JVM async/open api gradle plugin. That generated all the above. The nice thing was that if your server didn't implement the agreed upon spec it would fail to compile. Allowing for asynchronous development, back end/mobile/front end agree on the spec and can work on the feature at the same time.
This can also be expanded into k6/gatling. Hit this endpoint, guarantee this sla and ensure everything functions as expected. By having the contract first, you can automate a majority of the down stream tasks.
I think it has a use for contract first development, and is good in conjunction with something like avro. But it serves best in a contract first flow. Where in you define a spec, if it compiles you match the spec. Most servers don't take in a spec and define routes off operation names.
Why not dynamic async api generation? A lot of the generators reflect at run time, slowing down startup, and don't provide the most human readable definitions. Also lagging behind the latest implementation, and miss potential new features.
[+] [-] prionassembly|4 years ago|reply
Automatic generation of tests à la quickcheck.
Then, pydantic/fastapi does the YAML generation for me.
[+] [-] dnautics|4 years ago|reply
It wasn't really ready for that yet at the time, but I think over time AsyncAPI will be the way to go.
[0] in retrospect probably would have been better as a normal MVC app with only the chat and audio parts over ws, but... Again, not my project.
[+] [-] darepublic|4 years ago|reply
[+] [-] sigmonsays|4 years ago|reply
[+] [-] dnautics|4 years ago|reply
[+] [-] derberg|4 years ago|reply
[+] [-] pokoleo|4 years ago|reply
https://xkcd.com/927/
[+] [-] hardwaresofton|4 years ago|reply
[+] [-] no_wizard|4 years ago|reply
Would you mind elaborating if you know more?
[0]: https://json-schema.org/draft/2019-09/json-schema-hypermedia...
[+] [-] the_arun|4 years ago|reply
[+] [-] dominikbucher|4 years ago|reply
[+] [-] bassman9000|4 years ago|reply
https://www.asyncapi.com/docs/specifications/v2.1.0
[+] [-] dan_quixote|4 years ago|reply
But consider what OpenAPI/Swagger actually changed - it made for a singular page to tell a user (or machine) all the possible ways to interact with the service and what the shape of the requests and responses would look like. AsyncAPI is meant to do the same, but it's much harder to grok with all the various protocols generalized into unnatural-looking fields/URIs/etc.
[+] [-] derberg|4 years ago|reply
[+] [-] j4ah4n|4 years ago|reply
> Implementing OpenTelemetry typically means instrumenting code so that it can emit monitoring information.
> This information is then aggregated in a backend system, either on-premises or through monitoring as a service provider.
Was this part of the reasoning for Linux Foundation acquiring Swagger?
[edit] - formatting
[+] [-] Lagoni|4 years ago|reply
[+] [-] strobe|4 years ago|reply
[+] [-] m1ckey|4 years ago|reply
[+] [-] throwaway13337|4 years ago|reply
I don't understand, though, what it has to do with Async. Most messaging is done synchronously after establishing a live connection.
Why not call it EventAPI? Or MessageAPI? AsyncAPI implies it is the opposite of what it is. This name will uniquely cause a lot of confusion.
[+] [-] dpratt|4 years ago|reply
[+] [-] dnautics|4 years ago|reply
[+] [-] Thaxll|4 years ago|reply
[+] [-] bassman9000|4 years ago|reply
[+] [-] derberg|4 years ago|reply
[+] [-] moron4hire|4 years ago|reply
[+] [-] ducktective|4 years ago|reply
[+] [-] derberg|4 years ago|reply
[+] [-] crad|4 years ago|reply