Hacker News Reader

Comment by jrsj | Hacker News Reader

Typesafety is another big part of this imo. GraphQL and gRPC give you this out of the box, but with REST you have to cobble together some sort of solution for providing a schema & client libraries.

View on HN

True, but again this is a technical detail that should be secondary to who the client is and what they need.

Is the client always going to use a library to interact, is connecting without any code/schema published by the API provider a core requirement? Are clients going to be in languages with good protobuf/GraphQL support? Some don't have this. Is the code that talks to the API also owned by the API provider? Public vs private. Support lifecycles.

These factors all play into whether the type safety could even be utilised by clients. And it's not like REST doesn't have this – OpenAPI and Swagger can get a lot of the benefit with fairly minimal work. Both are very common.

I do agree that client requirements come first of course, but after that DX is at the top of my list.

They do differ fundamentally in that type safety is an afterthought with REST but is built in with some of the alternatives. That can have it's benefits too of course, it's easier to integrate with and more broadly supported in part because it doesn't concern itself with that.

OpenAPI can help but keeping your schema in sync with reality can be a pain depending on what libraries you have available. In the best case it really is minimal work, but if you don't have good tooling for whatever web framework you're using it can be a bit of a pain. In my experience it often requires more manual effort to maintain & more risk of mistakes causing the schema to be inaccurate.

That is true, but it has been very well solved and standardised by OpenAPI and JSON Schema.

This isn't 100% true - unless you're using a json-schema --> types package then there's a risk of your documentation not aligning with your types.

A common mistake I have noticed is that people identify API models with their business logic models. They may look similar, but they are very rarely identical, just as is the case with business logic models vs ORM models.

Unless your models are very simple, the best approach is to use three separate layers of model definitions:

  * API models for serde and conversion of external requests
  * business logic models that carry the actual internal functionality
  * (optionally) ORM models to convert the data for persistence to a RDBMS

An even worse mistake is treating all three of those model layers as one and the same, which tools like Django REST Framework make it so easy to do. It all seems well and good for a while, as developers build up a big codebase with ease, but then are confronted with an almost insurmountable amount of work when the need to refactor arises.

The thing I’ve noticed when stepping into a codebase where this problem has been allowed to occur is the lack of layers of abstraction. Having those different models built up from the start allows for an application to shift along with the needs of the product. Having a single layer, with the endpoints talking literally directly to the ORM models, almost inevitably leads to calcification, spaghettification, and disastrous performance.

It really depends on the language and framework you're using how convenient OpenAPI actually is to implement. In many cases there's a lot of additional manual effort involved if you can't auto generate a schema, or at least generate one that is good enough to then generate client libs from.

I've been disappointed with almost every OpenAPI spec I've come across for this reason. They're OK for documentation but can't auto generate clients due to errors.

There are three standard models of working with API schemas, in relation to the implementation:

  * manual:
    * schema is maintained manually, independent of the implementation
    * usually an afterthought and used mainly for documentation
  * implementation-first:
    * schema is autogenerated from the code
    * used as a reference, possibly to generate clients, and often to run tests
    * probably the most common approach, supported by many frameworks
  * schema-first:
    * schema is maintained manually, with client and server code generated from it
    * very rare, but the most correct approach

Is the image/jpeg media type "typesafe"?

How is using, for example, JSON Schema to define your types any better or worse than a "proto" file that requires a compiler, a parser, and a client and server library?

The difference is really that with something like protobuf type safety is built in & with JSON it's an afterthought. With JSON Schema or OpenAPI it's on you to keep things in sync with your API & there's often a significant amount of work that comes along with that too.

There's many tradeoffs of course, it's not like dealing with proto files is painless either.

What you're actually saying is that when you use the standard language bindings for a protobuf parser, the type safety is as built in as your language.

JSON has a limited set of types. There is object, array, string, number, boolean, and null. That's it.

JSON Schema adds to that by providing definitions of types that build on those basic JSON types.

gRPC does not give you any form of type safety. Even if you assume protobuf entities over gRPC, protobuf also does not give you any form of type safety.

Reply on news.ycombinator.com