5 ms·
APIs are interfaces (it’s right in the name!) and should never be directly tied to implementation because: 1. the interfaces must remain stable to the outside
by sunir 7y ago
APIs are interfaces (it’s right in the name!) and should never be directly tied to implementation because:
1. the interfaces must remain stable to the outside world that relies on them
2. They select what underlying resources and functionality is accessible by outside users, and what is hidden. A lot of your internal implementation is either a mess, “temporary”, insecure or intentionally internal.
3. They control access to the internal application through authentication, authorization, security, and translating data in both directions.
4. When the internal representation changes, they map the new implementation to the old interface to ensure the system remains reliable to API consumers.
5. They offer migration paths when change is necessary
That being said...
Auto API generators are really useful for internal systems where you control the underlying system, the API, and all systems relying on the API.
They are also useful to build an initial API that you plan to fork.
- deleted 7y ago[deleted]
- bsaul 7y agoCompletely agree. I like to design systems in that order : 1. my data model ( database schema ), because it gives you good questions to ask regarding the business side of your problem and let you go very deep just by asking « for each a, how many bs can we get » 2. my external api. Because it requires you to « dumb down » your problem, and see which part of your model you want to expose and how. 3. I actually start coding my business process, and then bind them to the model on one end and api on the other If i were to use code generation tool, it would need to generate both the db and the api stubs, together with the correct information exposure. I’m not aware of any tool that would let you do that.
- encima 7y agoOpenAPI and RAML both have some pretty cool tools to generate both the DB and the API stubs. For OpenAPI, Connexion by Zalando is one of the best implementations I have used. You just need to write the logic and provide the API spec.
- heavenlyblue 7y agoSo I assume you do most of the serialization of deserialization of objects by hand in connexion?
- encima 7y agoMostly, yeah. It is not perfect but we have a helper library we have written that handles most CRUD operations for objects and Connexion does the validation.
- bottled_poe 7y agoRespectfully, I somewhat disagree. APIs are indeed interfaces which should be seen as specifications and should not change. The problem is assuming that the API specification would be generated from the API implementation. The dependency is pointing the wrong way.
- sunir 7y agoI think we agree; if the API spec generated an implementation (a Proxy actually), it is much more stable, and the API endpoint can be an off-the-shelf library that adapts as protocols improve (e.g. XML -> JSON -> whatever)
- 013a 7y agoYeah I agree with your stance, but not the conclusion. The way that gRPC (and many other systems) handle this is beautiful and the way all APIs should be built: your API is a specification, not code, so you start with the spec (SDL), then generate the adapters your implementation needs to plug into it. This helps elevate changes to the API itself; you can easily write automated systems which detect changes to the specific SDL files. Or, the way companies like Namely [1] do it, keep those SDLs inside a separate repo, then publish the adapter libraries on private npm/etc to be consumed by your implementation. [1] https://medium.com/namely-labs/how-we-build-grpc-services-at-namely-52a3ae9e7c35 https://medium.com/namely-labs/how-we-build-grpc-services-at...
- remote_phone 7y agoThis has been around since the early 90s or previous. ONC-RPCs did this where you define the interface file and it generates the client and server stubs for you. NFS is based on this, as with other services. Conceptually it’s exactly the same, with some underlying differences.
- majewsky 7y agoGoing even further back in history, ASN.1 is also like this. It's a description language for data structures, and there are separate representations that can be derived from them. It's sort of like JSON, JSON Schema and Protobuf in one. TLS certs are encoded in ASN.1 DER, for instance, and LDAP messages are encoded in ASN.1 BER.
- sunir 7y agoI was reading the the OP's question as generating the API from the implementation. Your point about generating the implementation (i.e. a Proxy interface) from the API spec is right on. Thanks for the Namely case study as well. It was timely reading. :)