> google and microsoft moving forward api standardization
Google maybe.
Microsoft never - if it's one thing that is in their DNA than it's they always have undocumented API edge cases, so they can change them right in front of a competitor - they have a very long history doing that. Ask Apple (Word, IE, etc), DOS-competitors (DR-DOS, etc), IBM (OS/2, DOS, OpenOffice, Lotus, etc), "open" Office format (docx, xlsx, pptx = weird XML serialization of their old binary OLE2 based Office format), Win16API, Win32API, NTkernel API, and many more.
The API definitions (even the good ones, like Azure) do not contain sufficient information to be able to build a declarative tool. Google seem to view their internal annotations about what is mutable or not as some kind of competitive advantage (bizarre). The AWS API is wildly poorly specified for building anything except 1-1 API wrappers. (Cloud Control improves it, but covers few important resources).
I didn't say that they had to. But, having a single API is preferable to writing everything twice but in a slightly different way. Although, Microsoft aren't doing themselves any favours by not even trying a standardisation path.
> If your only response to this is "go cry to various small tech publications", then you're doing it wrong.
I don't think so. The main issue is that people think that there are APIs because companies promote their interoperability to gain developers. Companies are not being sincere and nobody is taking notice. To not repeat this and other opinions I post one of my recent posts on the subject: "Reverse Engineering and The Cloud" http://blog.nektra.com/main/2012/06/01/reverse-engineering-a...
> Interoperability requirements can be easy as mandating documentation and legal permission for interaction with API and it can be up to the competitors to implement the easy switching experience.
This is a misunderstanding of the problem. Once there is an API it can’t be changed without breaking the clients.
Therefore independent progress is no longer possible. This destroys innovation.
> Any other choice and I'd have customers API integrations breaking, because many of them would not have specified their version mimetypes correctly and would therefore get the default version, which would at some point diverge from their expectations.
"Some other people might write code that does things incorrectly and then their software might break" is something you can say about any API style, it's nothing special to media type versioning. If many of your customers are writing code that integrates with your API incorrectly, you don't have an API design problem, you have a poor communication problem, and that's going to hurt you in all kinds of ways.
> In real life URI aren't as static as we pretend.
They are static if you don't deliberately break them; I'm just pointing out some of the consequences if you choose to.
> How many companies would make sure the resource urls are still valid after changing the company and domain name?
Companies are laser focused on this if they rebrand. Companies love their search rankings. But how common is it to rebrand? Optimise for the common case, not the uncommon ones.
> The real identifier in your case is "foo" and "people" is the type.
You're turning URIs from an opaque identifier clients can use as-is to a compound structure that clients have to parse, manipulate, and (re)generate. You're putting more logic on the client, and thus giving client developers more rope to hang themselves with immediately after saying they can't be trusted to get things right.
This is not designing for maximum simplicity. Designing for maximum simplicity is to have an API that says "here's a link; follow it", not an API that says "here's an ID, generate a URI from it according to these rules we set out in our documentation, that are different for every type of resource". The latter is more work and more error prone.
> The reason competitors want to copy an API is because it's inherently necessary for compatibility. That need has nothing to do with how good the API is. It exists even if the API is terrible.
The other way to look at it is that people want to copy an API to extract value from a market or ecosystem someone else did the hard work of creating, without investing the resources into creating their own.
>Do I not know the latest API design principles yet or why are the examples for a de facto industry standard so lousy?
Swagger/OpenAPI is not really a standard, it's just a way to document an API. JsonAPI [1] is an example of a standard.
I only have a few years of API development under my belt, but something I have learned is that consumers of APIs really don't care about any of the points you listed. No one really cares if your API does not strictly follow ReST principles. They care that it works, that it's fast, and that it's well documented, in that order. Sure, using all the different HTTP verbs feels nice as a developer, but you know what is much simpler for everyone? GET for all reads and POST for all writes.
To be clear, I am not saying that you should give up on following best practices in your APIs. What I am saying is that you should design your APIs to meet your clients' needs, not to satisfy "principles of good API design."
> I think you aren't using the term API correctly.
I am. Public or private an API is an API. You seem to be under the impression that only a public API can be called an API which is nonsense.
> This discussion is about APIs for third party developers to write apps.
Which doesn't change the fact they have private APIs. My point was that they already have these APIs but they aren't public. They could be opened with minimal effort (compared to writing entirely new ones for PDS2).
> The fact that banks own mobile apps often use REST to communicate with their backend does not make such a protocol an API.
Of course it does, you know by definition[1].
> For one it's not documented, for another it may change without notice.
They are documented, but just like the APIs the documentation isn't public.
> Of course if you define "API" to mean literally any form of communication between processes or devices then sure. But then you'd have to consider GSM or FTP or TCP/IP itself to be APIs and I never saw them described that way.
No because I'm not an idiot. Those are protocols not APIs.
> My main point is that an interface that's just being driven by human interaction has very predictable load characteristics. If you open up a true API to third party developers they may come up with new uses that aren't directly human driven or may even be batch jobs. You don't have much control over your inbound workloads anymore.
Your case falls apart when you consider that there are already screen scraping services used by companies like Mint, Emma etc... these use way more resources than hitting an API and are already in use by hundreds of thousands of people.
Which is why I added "not saying I agree with them".
But requiring an open API (or at least not placing restrictions on an existing API) isn't conceptually all that different from requiring Microsoft to allow browsers other than IE on Windows, and apparently a lot of people think that's a good idea.
> I've tried both in the past and found that APIs are rarely as static as typed API systems require. Many APIs have fields that are required conditionally based on the value of other fields. Other times the schema is dynamic and workarounds are required like stuffing things into a JSON object and making it a "string" in the API.
There are big advantages to strict, mostly-static, clearly typed APIs, but you're right that adoption is often tricky. The problem isn't the nature of typed APIs, or missing capabilities in the data transfer formats/communication libraries themselves.
The problem is tooling.
Put another way: the tipping point (between untyped/whatever-you-like JSON and something structured like gRPC) is not how easy it is to use already-existent strict/typed APIs, but how easy it is to add, deploy, and change them.
API and client developers will stop pushing back on a structured format, or adding workarounds (like stuffing random JSON into string fields) if the tooling that supports changing API definitions is excellent: if they can easily change the minimum of code or type definitions to make the data-"shape" (schema) changes they want, and immediately be able to exercise their changes across multiple backend APIs and frontend clients (with obvious and predictable behaviors around versioning and backwards/forwards compatibility), and can have confidence that they can deploy those changes to real users in a seamless and low-touch way (e.g. no "everyone please update your endpoints to /api/v804.7/"), then resistance/workarounds to structured API patterns will disappear.
There's some expertise/discipline involved in getting those things right, but they need to be easy first.
The companies that have really gotten huge benefits from stricter, more uniform, generated and/or typed API definitions (for both internal service interactions and external clients) aren't all huge companies, they aren't all using the same tech stacks, and they aren't all in the same kinds of markets. The thing they have in common is a huge investment in good tooling around how to create, modify, and deploy cross-platform typed APIs.
Well, given the choice between a world where the only APIs in existence are "true platforms", backed by enormous corporations with tons of resources who pledge to make them absolutely backwards-compatible for ten years... and a world where, in addition to the true platforms, every half-assed hack also has some sort of API so that other people can build upon it with half-assed hacks of their own, my first instinct is still to prefer the second world.
Yes, this means that the word API no longer connotes "true platformness". That's a branding problem for the "true platforms", but I'm sure Microsoft and Oracle can handle it. They have resources.
So they built a new product to a competitor's API spec? There is nothing wrong with that, the API itself is a plug - you need to implement the backend to compete.
It is super lame and dumb to have ripped off their doc, but the API format itself is not an issue to me. If I were going to implement a competitor to Google Maps, it would make sense to copy the Maps API so people can migrate seamlessly. That is the nature of SaaS.
The core value proposition is not in API design, it's in the implementation.
> I think that issue here is, and it's almost bound be the same for most other APIs, it's the data that's interesting.
I love building APIs. The biggest hurdle I see is that you need two active parties on both ends of the API to convince: There is a user, which needs to be convinced to use the API, and a supplier, which also needs to use the API. And there is no incentive to use the API for one or another.
Google maybe.
Microsoft never - if it's one thing that is in their DNA than it's they always have undocumented API edge cases, so they can change them right in front of a competitor - they have a very long history doing that. Ask Apple (Word, IE, etc), DOS-competitors (DR-DOS, etc), IBM (OS/2, DOS, OpenOffice, Lotus, etc), "open" Office format (docx, xlsx, pptx = weird XML serialization of their old binary OLE2 based Office format), Win16API, Win32API, NTkernel API, and many more.
You are right with AWS.
reply