Comment by sunir | Hacker News Reader

Comment by sunir | Hacker News Reader

Parent Full thread

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.

Yeah 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...

This 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.

Going 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.

I 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. :)

Completely 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.

OpenAPI 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.

So I assume you do most of the serialization of deserialization of objects by hand in connexion?

Mostly, 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.

Respectfully, 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.

I 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)

Reply on news.ycombinator.com