Live data from Hacker News

Implementing Microsoft REST API Filter

sergeykibish.com

31–40 of 44 posts

Re: Implementing Microsoft REST API Filter

#31

Earlier quoted context omitted.

no, the whole media type thing was a moderately-interesting-idea-turned-ridiculous-navel-gazing turn that, among many other pedantic blind alleys, turned everyone away from the deeply innovative aspect of REST: the uniform interface, and, in particular, HATEOAS https://htmx.org/essays/hateoas/ any idiot (such as myself) who has ever made a web 1.0 app has created a better REST API than 99.9% of all REST API engineers…

I have created Hypermedia APIs using HTTP/JSON for service-to-service interactions, and it is definitely a lot of work for questionable benefit. The biggest problem with the bad style of RPC-style programming was the assumption that remote calls could be treated like local calls. Modern HTTP-based RPC APIs don't make that assumption and thr problems of distributed computing are handled explicitly. The semantics of HT…

My current take on the issue is that REST advantages can only be realized if there a sufficiently smart client (aka human) driving the interaction.

Re: Implementing Microsoft REST API Filter

#32

Earlier quoted context omitted.

I have created Hypermedia APIs using HTTP/JSON for service-to-service interactions, and it is definitely a lot of work for questionable benefit. The biggest problem with the bad style of RPC-style programming was the assumption that remote calls could be treated like local calls. Modern HTTP-based RPC APIs don't make that assumption and thr problems of distributed computing are handled explicitly. The semantics of HT…

My current take on the issue is that REST advantages can only be realized if there a sufficiently smart client (aka human) driving the interaction.

https://intercoolerjs.org/2016/05/08/hatoeas-is-for-humans.h...

Re: Implementing Microsoft REST API Filter

#33

Earlier quoted context omitted.

REST was the term Roy Fielding coined as description of the original web architecture. The big distinguishing feature of REST-ful systems vs. non-REST-ful systems was something called the uniform interface, where clients had zero knowledge about a given server's API surface beyond a URL entry point. Everything after that was encoded in hypermedia, giving us the term "Hypermedia As The Engine of Application State" (HA…

Thanks! I was really confused with this topic, and your post cleared things up. But from what I gather, proper REST API's wouldn't pair nicely with modern day UI development. Maybe this is because I usually work with APIs that wouldn't be considered restful (from my understanding, my company's public API is here [ https://developer.veevavault.com/api/22.1/ ]), I have a hard time seeing how a modern React webapp would…

That's right, REST concepts are largely wasted on modern SPA applications, which are fundamentally RPC-style clients.

Instead, REST should be used in its original context: hypermedia clients (browsers) exchanging hypermedia (HTML) with the server. I have written an alternative front end library that takes this exact approach:

https://htmx.org

Some more essays on the topic:

https://htmx.org/essays/spa-alternative/

https://htmx.org/essays/hypermedia-apis-vs-data-apis/

Re: Implementing Microsoft REST API Filter

#34

Earlier quoted context omitted.

Thanks! I was really confused with this topic, and your post cleared things up. But from what I gather, proper REST API's wouldn't pair nicely with modern day UI development. Maybe this is because I usually work with APIs that wouldn't be considered restful (from my understanding, my company's public API is here [ https://developer.veevavault.com/api/22.1/ ]), I have a hard time seeing how a modern React webapp would…

That's right, REST concepts are largely wasted on modern SPA applications, which are fundamentally RPC-style clients. Instead, REST should be used in its original context: hypermedia clients (browsers) exchanging hypermedia (HTML) with the server. I have written an alternative front end library that takes this exact approach: https://htmx.org Some more essays on the topic: https://htmx.org/essays/spa-alternative/ htt…

Thank you! This has been a point of confusion for me for a while, maybe I should get around to reading Roy's dissertation. Your post did clear things up :)

Re: Implementing Microsoft REST API Filter

#35

Earlier quoted context omitted.

Disclaimer: I work for Microsoft as an API Architect. I am not working on this specific API, so I am not going to comment on anyway. I hear your complains about Microsoft API guidelines (which is an entire different conversation) but I wanted to add my two cents with regards to JSON Schema. The problem that I have been having with JSON Schema since forever - is that the data that is being modeled is complected with c…

I’ve debated back and forth on whether it’s a good idea to have separate input and output models for each endpoint, because trying to have a generic structure that’s usable everywhere makes it really easy to pipe output back to input for a PUT, but it’s difficult to express constraints like, this field cannot be updated, only created or these fields are required but only for create and update supports a different sub…

Been there too. I'm a big fan of explicit data models (DTOs) for each endpoint, as I think any kind of interface description should be as sound, concise and precise as possible. That means never having any property sent that is redundant or unnecessary (=gets ignored by the backend). But I do see the problems and increased engineering effort to achieve this. Especially since a lot of BE frameworks and languages do not support union and intersection types (looking at you, C# and Java) while OAS does. The endresult is usually larger shared DTO models, where any given subset of properties is set to "null" depending on the endpoint it is used for. Not a clean interface design, but decreases a lot engineering effort.

Re: Implementing Microsoft REST API Filter

#36
post #3

Earlier quoted context omitted.

You can tap the sign as much as you want, that battle was lost a long time ago. REST is just the common term people use for HTTP+JSON RPC.

"Ugh... REST is too much work! We'll just change the meaning to suit us."

> "Ugh... REST is too much work! We'll just change the meaning to suit us."

See also: Agile. DevOps.

It's pretty common once you look.

Re: Implementing Microsoft REST API Filter

#37

don't make me tap the sign: https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypert... > I am getting frustrated by the number of people calling any HTTP-based interface a REST API. Today’s example is the SocialSite REST API. That is RPC. It screams RPC. There is so much coupling on display that it should be given an X rating. > What needs to be done to make the REST architectural style clear on the notion that…

If a teacher has one failing student, blame the student.

If a teacher has 99 failing students, blame the teacher.

Re: Implementing Microsoft REST API Filter

#38
post #37

don't make me tap the sign: https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypert... > I am getting frustrated by the number of people calling any HTTP-based interface a REST API. Today’s example is the SocialSite REST API. That is RPC. It screams RPC. There is so much coupling on display that it should be given an X rating. > What needs to be done to make the REST architectural style clear on the notion that…

If a teacher has one failing student, blame the student. If a teacher has 99 failing students, blame the teacher.

Or, in this case, maybe:

If the teacher has no students, blame the topic.

People just don't want HATEOAS as much as some would like.

Re: Implementing Microsoft REST API Filter

#39
post #18

Earlier quoted context omitted.

A true REpresentational State Transfer API would give each version of each of the API's L7-protocol request and response messages its own media-(sub)type; and would then rely on HTTP content negotiation to allow clients to specify which messages they're expecting to receive in response to a request; where the difference between throwing/nonthrowing, sync/async, new/old variant, etc., would all come down to which resp…

no, the whole media type thing was a moderately-interesting-idea-turned-ridiculous-navel-gazing turn that, among many other pedantic blind alleys, turned everyone away from the deeply innovative aspect of REST: the uniform interface, and, in particular, HATEOAS https://htmx.org/essays/hateoas/ any idiot (such as myself) who has ever made a web 1.0 app has created a better REST API than 99.9% of all REST API engineers…

HATEOAS is its own thing. A good thing, IMO, but not the same thing as REST. Saying that "the innovative aspect of REST is HATEOAS" is like saying "the unique thing about rectangles is that all four sides are the same length." That's squares, not rectangles. Rectangles have a uniqueness all their own, whether they're square or not. REST has innovative aspects all its own, whether you're doing HATEOAS or not.

REpresentational State Transfer is, like it sounds, a very specific concept: it's about how the semantics of HTTP verbs + headers (e.g. Cache-Control headers, Allow headers, Vary headers, etc.) interact with clients and gateways (esp. caching gateways, clients in offline mode, etc); and how these interactions work better and "in harmony with" those HTTP semantics — improving cachability, decreasing number-of-origin-fetches, improving PWA offline graceful degradation, avoiding inconsistency and any need for cache-busting, etc. — when you model your exposed state-representations a certain way.

A REST model — a projection of your data as "REpresentations of State" — is a transformation of your data along lines such that each representation becomes an ADT with semantics that recapitulate those of an object store / WebDAV folder / HTML page as edited in the original WorldWideWeb.app. Each representation can be PUT; POSTed to; PATCHed, DELETEd; GET-ted and then cached; and HEAD-ed without triggering heavy computation. REST's REpresentations are objects that work in harmony with being passed around through the HTTP protocol.

However! Every "RESTful" API you've ever seen (at least if you do CRUD web-dev), is very likely a trivial RESTful API, because it's taking abstractions — resources — that are already inherently ADTs with REST-alike semantics, and just 1-to-1 exposing them via HTTP. (A lot of work may have been put in by some dev at some point in the past, into coming up with a best-practice design for those internal data structures such that they can work for the business-domain while also being inherently RESTful; but it's not REST itself carrying that weight, and it's not REST itself that determines whether it's possible to do that.)

It's great if your internal data is such that you can do that ; but that's not what makes REST powerful; it's not what it means to wield REST as a tool.

REST is a thing like GraphQL: a gateway adapter that reformulates an internal data model into a different, outward-facing data model. It's what frontend devs would call a data-binding layer — but, like GraphQL, one done on the backend. This is why REST talks about representations: representations are to REST as graphs are to GraphQL. They're a modelling layer on top of your data, that reshapes it. Except that, unlike GraphQL, which is almost as bad for HTTP semantics as SOAP, REST is (by definition) whatever transformed form allows your data to be handled most optimally in an ecosystem of HTTP clients+servers+gateways.

This concept is most powerful when applied to things that aren't inherently very RESTful at all; where it's challenging to state them in RESTful terms. For example, an API for controlling an ephemeral pushdown-automata, like an SQL connection. Or an API for managing subscriptions and consumer-groups in a message-queue broker. Or an API for scheduling jobs onto a workload manager.

Re: that last one, Kubernetes is a great example of what it means to "do REST" in a nontrivial way: it takes resources that aren't inherently RESTful, and creates abstract REpresentations of these resources (YAML manifests) that work perfectly under HTTP semantics, transferring the state of these representations to clients in a way where the client can then do things like modify the representation and PUT or PATCH it back. You can stick a caching proxy between you and a Kubernetes control-plane, and everything keeps working. You can query a Kubernetes control-plane from your browser address bar.

But note how, when you create a nontrivial abstraction like this, you end up with very custom types for your REpresentations. Because there are no inherent REST-shaped resources in your backend to manipulate; and because you want your REpresentations to be long-lived documents in their own right (in caches; on the client as something for it to hold and manipulate and patch; etc), you have to define an application-layer formal semantics for what those documents are, and do. You have to ensure that a REpresentation a client fetched a year ago, and is pushing back as a PUT today, will either work as-is; be "migrated" in a forward-compatible way when received by the backend; or be able to be cleanly rejected, by your REST server, despite that document having a schema that is now older than the REpresentation you're currently emitting from that endpoint.

How do you do that? People who don't understand REST use ugly URL hacks for this — like putting the version in the URL, the format as a file extension in the URL, etc. But these hacks fight against the semantics of HTTP.

Say you have an internal Foo ADT, that you first exposed as a FooV1 representation, and then later additionally as a FooV2 representation. If you do that by exposing e.g. /foos_v1/1 and then /foos_v2/1; then a PATCH to /foos_v1/1 can't possibly inherently invalidate a reverse-proxy cached representation for /foos_v2/1. But if you've just got /foos/1, that Vary's on Allow? Then it all "just works."

To make that work, FooV1 and FooV2 have to send separate Content-Types.

QED? ;)

Re: Implementing Microsoft REST API Filter

#40

Earlier quoted context omitted.

My current take on the issue is that REST advantages can only be realized if there a sufficiently smart client (aka human) driving the interaction.

https://intercoolerjs.org/2016/05/08/hatoeas-is-for-humans.h...

That basically validates the conclusions I have come to as well.

However, I would add that I think you can build machine APIs using hypermedia, but the API contract would different. You would essentially define an OOP API with MIME Types as class definitions. That is partly I think why Toy Fielding put so much emphasis on defining those types.

But the real pwer of hypermedia - the ability to change those hypermedia relations dynamically - is really only useful for human-driven interactions.

Post reply on HN