Microsoft REST API Guidelines

I really don’t want to worry about setting http headers to make an add-if-not-exists call for example. The API in a client library with a method “TryAdd(...)” is understandable as an API, and the setting of headers and 4XX code you might receive on a duplicate is just returned as false.

That means your CDN, your load balancers, and finally your actual applications-- any any other intermediaries -- all communicating via HTTP/2.

Not to say that HTTP/2 isn't the solution, but it's going to be slower than looking up "number of sites using HTTP/2", since you can't easily inspect the behavior of the intermediary servers.

For one, having it be transactional.

>With HTTP2 you can send a ton of requests in parallel.

That's orthogonal. And they still have a cost (in time and size of transfer).

If your ids are UUIDs, each has a length of 36. If your URL consisted of nothing but UUIDs, you could safely delete 55.5(repeating) of them.

[0]: https://stackoverflow.com/questions/417142/what-is-the-maxim...

Probably in violation of some standard, but seems sensible enough.

Edit: I was wrong. It's allowed to put a body in a GET request, but it isn't OK to use it according to the HTTP spec (which admittedly kind of weird). Source: https://stackoverflow.com/a/983458

Edit2: according to an edit int the SO response, it looks like I wasn't actually wrong: or at least not since 2014 when these RFCs[1][2] became the standard for HTTP.

[1]: https://tools.ietf.org/html/rfc7231#section-4.3.1 [2]: https://tools.ietf.org/html/rfc7230#section-3.3

Was recently dealing with a list of 100+ simple text fields each with unique identifying meta info.

Most usage of the form would only involve updating a few at a time, but on initial entry or a large update all of them could be updated or deleted.

A RESTful approach would have me submit 100+ individual PUT requests. However for a smaller instance of our server it would likely be affected by 100s of requests at a time and it would significantly complicate the client code to make all of these requests at a time and do the error handling for it.

It’s actually a small payload, even with 100 items, so it’s ridiculous to send them individual in order to be “correct” if it

- leads to a worse user experience. - increases load on the server. - complicates the codebase.

Italics works fine for quote IMO.

Continuing to use code formatting after being made aware of the problem wouldn't be civil disobedience either. It would merely inconvenience the large number of people who read HN on mobile devices, for no purpose.

(Edited to remove a somewhat unrelated philosophical note.)

See section 13.

So why were they in the original HTTP spec if they weren't supported by original HTTP agents?

Top down mandate cannot align 130k employees on every topic, even if that attempt were an appropriate thing for upper management to spend their time on.

There might be a more interesting conversation if context were given. If the comment about management not caring about RESTful APIs is coming from someone working as part of a team focused on public APIs, it’s a lot more interesting than someone working on desktop clients.

Edit: You know what, you’re right. I read the comment as a flippant “pft, that’s not my experience” and responded as such. I should have assumed better intent. Maybe the commenter was questioning why their experience doesn’t match up with this. Maybe they were asking why management isn’t pushing this effectively. I assumed a specific intent and should have considered different potential intentions.

Apart from being able to tell the client what functions they are allowed to use and a very superficial form of documentation I don’t really get the advantage of it.

I think that's a good idea, just like REST and HATEOAS are both ideas trying to solve problems.

I'm just skeptical that it'd work in practice. It seems vanishingly unlikely that consumers will use it correctly enough that changing the URLs in that mechanism wouldn't result in making the breakage even more mysterious.

When I say "it only makes sense if you've got a browser on the other end," the issue is you need a client approaching the complexity of a browser to do all the redirection and such that makes this level of flexibility for the API implementer to work.

I believe something like that is possible, but this isn't the way.

It's only toilsome when you try to shoe-horn it into a traditional data API, rather than accept it as a unique descriptive aspect of the early web architecture.

But in short, Protobuf is inherently a language of its own. Like JSON or etc. But it's feature rich enough that it can cause a fair number of incompatibilities between a language's preferred style or usage of features.

Where the incompatibility shows up depends on the language. I found it to be very different between Rust and Go, for example.

Sure, take Go for example. Protobuf to Go works well, but there are some features of the Protobuf language that just don't exist in Go. Enums, for example. While Go does have constructs that are similar to Enums, they're just different enough to make it a bit weird.

This basic problem gets worse when you try to use it though. The `One of` construct, for example, is sort of impossible in Go. Iirc the Go implementation had to use runtime type checking to give some resemblance to the Protobuf spec.

Rust (which I focus on now) was far better with Protobufs. As far as I remember, there wasn't much of Protobufs that broke idiomatic Rust. However, there was plenty of idiomatic Rust that broke Protobufs iirc. Things like complex data structures behind enum variants. Enum variants as structs, tuple values, etc. iirc it was bad enough that I usually used an abstraction library to write my idiomatic data structures and convert to/from the Protobuf structs.

Which, is how I left it all together. I realized I had a ton of glue code trying to make up for the incompatibilities in Protobufs + (Go|Rust), such that it would just be easier to drop it - at least as far as my code is concerned.

We now struggle with documentation, something Protobuf did excellently, but at least the code smell is gone.

It doesn’t mean “do the same thing” or “get the same response”, only “end up in the same place”.

You can do a delete x, get an OK response, and the important state is that x is now deleted on the server. Then the next call to delete x does nothing (which is different from the first which deleted x!). So to be idempotent it has to do something different. The response in the second case can be both “ok” (because the thing is deleted) but also e.g “x doesn’t exist”.

Also allows you to implement optimistic concurrency. See: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/If...

edit: ah you must be referring to the GP. But the anecdote just says format change.

Of course you want to mention that a new field was added and what it is for, but why do you need a big notice? Your clients should just continue to work.