Thanks for taking the time to write down your thoughts! I deeply appreciate it!
My bad I was not concrete. What I've meant by "this/that" the entire "find the docs - read the docs - program/generate your client using the docs/OAS - maintain your client forever" when we can have application that will do all this without our intervention.
> I'm never not going to need API documentation because it's not just syntax. It also tells me how the vendor's object model works. It tells me the right order to make API calls, how to know my rate limit, and how to choose permissions for my API keys that are as narrow as possible.
Ideally, you should only need to understand the business logic of the API and not how to achieve it, that part can be figured out by your app.
Self-integration approach does not force you to harmonize the offerings. It just abstract you away from the APIs using the business layer (as you are already doing using you classes).
You might try to harmonize some of the vendors if that is what you like, but that is not the gist. With Some vendors and in certain domains it might make sense - that's why we see domain integrators. With others, it either does not make sense or it is not commercially viable. Either way, you can have your app integrating on the abstraction level without you caring about the technicalities.
The sad truth is that vendors in the first place don't want their offerings to be interchangeable. But that is for another discussion.
Also, it is great to hear that codegen from OAS works for you!
> losing first-party support from the API vendor and having yet another layer to have to debug
1. if your app self-integrates you will not loose that
2. you have this layer already in your hexagonal / clean architecture wrappers, what is worse, everyone is bikeshedding, writing this part over and over
Is it that you disagree on the topic? There is nothing subtle about the fact that most of the API tools development goes towards fixing something that does not even have to be there.
That's an excellent point! It's sure the case for the "building API to leverage (pardon me the word) the channels" scenario. These pre-agreed scenarios couldn't be automated. But other business drivers (direct data monetization or added value) would still benefit greatly from M2M approach.
That is my point: We don't need to understand the communication means. Instead, we should just declaratively say what we want the machine to do, and it will figure out the rest.
The results are relevant only if 1. the name of API contains the term or affordance you want to use 2. you are a human being (you cannot perform such discovery as a machine)
Thanks for the review! I didn't mean the article as a marketing post, but I wanted to share my (long) thought process.
Nothing in the article is new in the concept, but maybe™ the time is now right. Frankly, what the part I'm concerned about isn't the semantics sharing at runtime, but it's the de-coupled, declarative approach in writing the clients.
With hypermedia, we've failed at the gates of client development. The devs tend to tight-couple their code with APIs, ignoring the consequences. If there won't be an incentive on client's side, then nothing from the article will matter.
Fair point! I'll try to answer with a question: So why is it that Google, Microsoft & Yahoo cooperate on schema.org to establish shared vocabulary?
They don't have to make it interoperable per se. It'd be enough to use some terms from a shared vocabulary (user, account, address) and then have some business-specific terms.
This way the business can use an existing library that knows how to handle user profiles. It's not that the full client has to be generic, a UI component that knows how to present a portion of a dictionary is enough.
Swagger and API Blueprint are two different formats to describe web APIs. Until now Apiary and its tools supported only the API Blueprint. This has changed today.
/author of API Blueprint here/ I would not say this is the case. API Blueprint focuses on different data for various reasons (design-first, documentation-orinented). In order to bring the Swagger support we had to introduce some extension in the format. We are, however, trying to unify the tooling under the hood of the refract project (https://github.com/refractproject/refract-spec/blob/master/n...) through (de)serialization plugins for the Fury.js library (https://github.com/apiaryio/fury.js)
A hosted mock server is part of Apiary suite of tools for the entire API design lifecycle. Others would include interactive documentation, traffic inspector, backend testing and style guide validation. We hope to encourage collaboration and bring the design-first, documentation-oriented approach to the world of API development.
Yes and no. Depends how you "write" those tests. In this case, where you describe the scenarios, it is indeed true. However you can take a different approach – without writing explicit tests (and thus the client code). Rather you just describe your API in a sort of contract and then, as you iterate, you verify the implementation is living up to this contract...
This looks interesting! Might be worth taking a look at the library we have built to validate the HTTP messages using `curl-trace-parser` (https://github.com/apiaryio/gavel)
As discussed in the MSON README - there is this Markdown format for documenting APIs; discussing / describing API payloads and resources in JSON Schema felt complex and not suiting well the settings of a Markdown document.
Besides some payloads are not just a JSON. So there is a need to describe these data in a media-type agnostic form.
Brandur, this is indeed very actual topic (and will be even more with the rise of APIs).
As with everything, the issue is twofold. In the case of Heroku and your user-base it is reasonable to expect your users are closer-to-wire than an iOS guy hacking in Cocoa Touch.
From your point I can't agree more. A well designed HTTP APIs goes a long way here. Putting a Cocoa Touch developer's hat on and I can't be bothered learning HTTP, checking all the possible responses, handling redirects and errors when the only thing I need is to just fire a single Mixpanel track event...
Sort of C/C++ vs. let's say a Ruby. Assembler anyone? Stay on the metal or develop (and crash:) faster with some trade-offs.
Anyways, good stuff. Important bringing it on the table!
My bad I was not concrete. What I've meant by "this/that" the entire "find the docs - read the docs - program/generate your client using the docs/OAS - maintain your client forever" when we can have application that will do all this without our intervention.
> I'm never not going to need API documentation because it's not just syntax. It also tells me how the vendor's object model works. It tells me the right order to make API calls, how to know my rate limit, and how to choose permissions for my API keys that are as narrow as possible.
Ideally, you should only need to understand the business logic of the API and not how to achieve it, that part can be figured out by your app.
Self-integration approach does not force you to harmonize the offerings. It just abstract you away from the APIs using the business layer (as you are already doing using you classes).
You might try to harmonize some of the vendors if that is what you like, but that is not the gist. With Some vendors and in certain domains it might make sense - that's why we see domain integrators. With others, it either does not make sense or it is not commercially viable. Either way, you can have your app integrating on the abstraction level without you caring about the technicalities.
The sad truth is that vendors in the first place don't want their offerings to be interchangeable. But that is for another discussion.
Also, it is great to hear that codegen from OAS works for you!
> losing first-party support from the API vendor and having yet another layer to have to debug
1. if your app self-integrates you will not loose that 2. you have this layer already in your hexagonal / clean architecture wrappers, what is worse, everyone is bikeshedding, writing this part over and over