Earlier quoted context omitted.
With HATEOAS you're supposed to return the list of available actions with the representation of your state. Neo4j's old REST API was really good about that. See e.g. get node: https://neo4j.com/docs/rest-docs/current/#rest-api-get-node
That API doesn’t look like REST level 3 API. For example, there’s an endpoint to create a node. It is not referenced by root or anywhere else. GetNode endpoint does include some traversal links in response, but those links are part of domain model, not part of the protocol. HAL does offer a protocol by which you enhance your domain model with links with semantics and additional resources.
Most RESTful APIs aren't really RESTful
451–460 of 580 posts
Re: Most RESTful APIs aren't really RESTful
#452Earlier quoted context omitted.
That's absolutely not what the essay is about. It's about the misassignment of credit for the success of a technology by people who think the minutiae of the clever implementation was important.
I think you bring up an interesting tangential point that I might agree with--that the people doing the misalignment are how architecture astronauts remain employed. But the core of Joel Spolsky's three posts on Architecture Astronauts is his expression of frustration at engineers who don't focus on delivering product value. These "Architecture Astronauts" are building layer on layer of abstraction so high that what…
I don't think this is tangential at all. This whole conversation is exactly the same as Spolsky's point about Napster: it's hard to know what to say to someone who thinks the reason the web was successful was REST, rather than HTML letting you make cool web pages with images in them. And this has played out exactly as you'd expect: nobody cares at all about REST, because it's pure architecture astronaut stuff.
Re: Most RESTful APIs aren't really RESTful
#453Earlier quoted context omitted.
The critical problem with gRPC is that it uses protocol buffers. Which are...terrible. Example: structured schema, but no way to require fields.
With Protobuf this is a conscious decision to avoid back-compat issues. I'm not sure if I like it.
That's exactly how these systems fail in the marketplace. You make one decision that's good for, say, 50% of cases but disqualifying for 50% of cases and you lose 50% of the market.
Make 5 decisions like that and you lost 31/32 of the market.
Re: Most RESTful APIs aren't really RESTful
#454Earlier quoted context omitted.
Amen. Particularly ISO8601.
Always thought that a standard like ISO8601 which always stores the date and time in UTC but appends the local time zone would beneficial.
Sometimes you need your timestamps to be in a named timezone. If I have a meeting at 9am local time next month, I probably want it to still be at 9am even if the government suddenly decided to cancel daylight time.
Re: Most RESTful APIs aren't really RESTful
#455Earlier quoted context omitted.
>> /things/:id/child/:child_id It seems that nesting isn't super common in my experience. Maybe two levels if completely composite but they tend to be fairly flat.
I see both. E.g. GitHub /repos/:owner/:repo/pulls/comments/:comment_id But flat is better than nested, esp if globally unique IDs are used already (and they often are).
Yes but /comments/:comment_uuid that has a parent to /pulls/:pull_uuid is harder to map the hierarchy it belongs to.
Re: Most RESTful APIs aren't really RESTful
#456Earlier quoted context omitted.
Always thought that a standard like ISO8601 which always stores the date and time in UTC but appends the local time zone would beneficial.
Sometimes you need your timestamps to be in a named timezone. If I have a meeting at 9am local time next month, I probably want it to still be at 9am even if the government suddenly decided to cancel daylight time.
unless the customer you're meeting is in another timezone where the government didn't cancel daylight time
Re: Most RESTful APIs aren't really RESTful
#457Earlier quoted context omitted.
I've seen some systems with a lot of pieces where teams have attempted to avoid repetition and arranged to use a single source of schema truth to generate various other parts automatically, and it was generally more brittle and harder to maintain due to different parts of the pipeline owned by different teams, and operated on different schedules. Furthermore it became hard to onboard to these environments and figure…
> it was generally more brittle and harder to maintain It depends on the system in question, sometimes it's really worth it. Such setups are brittle by design, otherwise you get teams that ship fast but produce bugs that surface randomly in the runtime.
Absolutely, it can work well when there is a team devoted to the schema registry and helping with adoption. But it needs to be worth it to be able to amortize the resources, so probably best for bigger organizations.
Re: Most RESTful APIs aren't really RESTful
#458Earlier quoted context omitted.
> The vision of API that is self discoverable and that works with a generic client is not practical in most cases. [..] Fielding's paper doesn't provide a complete recipe for building self-discoverable APIs. It is an architecture, but the details of how clients should really discover the endpoints and determine what these endpoints are doing is left out of the paper. To make truly discoverable API you need to specify…
> A true implementation of a REST client is simply not possible Sure it is, it's just not very interesting to a programmer. It's the browser. That's why there was no need talk about client implementations. And why it's hypermedia driven. It's implicit in the description that it's meant to be discoverable by humans. AirBnb rediscovered REST when they implemented their Server Driven UI Platform. Once you strip away all…
> It's the browser.
This cannot be overstated.
I'm watching with some interest to see if the LLM/MCP crowd gradually reinvents REST principles. LLMs are the only software we have invented yet which is smart enough to use a REST interface.
Re: Most RESTful APIs aren't really RESTful
#459Earlier quoted context omitted.
Brb, I'm off to invent another language independent IDL for API definitions that is only implemented by 2 of the 5 languages you need to work with. I'm joking, but I did actually implement essentially that internally. We start with TypeScript files as its type system is good at describing JSON. We go from there to JSON Schema for validation, and from there to the other languages we need.
anything I could read to imitate that workflow ?
I haven't written anything up - maybe one day - but our stack is `ts-morph` to get some basic metadata out of our "service definition" typescript files, `ts-json-schema-generator` to go from there to JSON Schema, `quicktype-core` to go to other languages.
Schema validation and type generation vary by language. When we need to validate schemas in JS/TS land, we're using `ajv`. Our generation step exports the JSON Schema to a valid JS file, and we load that up with AJV and grab schemas for specific types using `getSchema`.
I evaluated (shallowly) for our use case (TS/JS services, PHP monolith, several deployment platforms):
- typespec.io (didn't like having a new IDL, mixes transport concerns with service definition)
- trpc (focused on TS-only codebases, not multi language)
- OpenAPI (too verbose to write by hand, too focused on HTTP)
- protobuf/thrift/etc (too heavy, we just want JSON)
I feel like I came across some others, but I didn't see anyone just using TypeScript as the IDL. I think it's quite good for that purpose, but of course it is a bit too powerful. I have yet to put in guardrails that will error out when you get a bit too type happy, or use generics, etc.
Re: Most RESTful APIs aren't really RESTful
#460Earlier quoted context omitted.
Just use gRPC or ConnectRPC (which is basically gRPC but over regular HTTP). It's simple and rigid. REST is just too "floppy", there are too many ways to do things. You can transfer data as a part of the path, as query parameters, as POST fields (in multiple encodings!), as multipart forms, as streaming data, etc.
The critical problem with gRPC is that it uses protocol buffers. Which are...terrible. Example: structured schema, but no way to require fields.
Well the competition is REST which doesn’t have a schema or required fields, so not much of a problem.