I still like REST. Most web applications are CRUD and don't need RPC. It also provides a standard and expected interface for 3rd party developers integrating with your code. If you're a small saas startup, nobody is going to waste their time learning the particularities of your protocol. Also makes the code very easy to read if you follow best practices for MVC style webapis with dependency injection. In my view, asp.net core is the apex of all RESTful frameworks
Precisely right. Standards work cause everyone understands them. I know a PUT request is almost certainly an update of some kind. I know a POST makes something.
For most shit you wanna do, its view, edit, delete, its really not that complicated.
One team got a stream of 404’s not because the requested objects did not exist in the DB, but because the service moved. Web server was saying: resource does not exist.
Another time, the server had the resource but didn’t like the state of the data, so refused to serve it. Debate ensued as to whether this was a 400 or 500 class error. People got religious.
Yes there’s an answer but it should be so obvious that we don’t have the debate. This isn’t sophisticated verbs, both happened with GET.
Am I the only one around here who hates the whole PUT PATCH nonsense? When I write APIs, you’re either querying data with a GET, or mutating data with a POST. Everything else is a waste of time.
It's become just a word that means "interface endpoints". And frankly that's fine, it's what it is in the end. Whether in an OS, a website, or another platform.
The other way around, the meaning of API standalone has been narrowed to mean HTTP APIs, as if it were redundant. Specially tedious if you're searching for non-HTTP API design notes.
Almost all my development has been in the fields I mentioned. I prefer to think of HTTP 'APIs' as end-points instead: you query a URL for some fields, and you receive some data—whether it be plaintext (JSON), or binary. That's essentially it. I feel narrowing the definition of an API to just 'HTTP end-points' is very reductive. The word stands for 'application programming interface', but I don't really need to program anything to use a HTTP end-point: I can navigate to it using a Web browser, if I want.
For me, an API is a lot more concrete: a set of data structures (whether they be classes, objects, pairs, tuples, lambda functions, etc.) with extensible functionality (member functions, pure functions accepting those data structures, etc.) that developers can use independently, or together, to produce some new functionality, i.e. program using interfaces.
So what I'd traditionally think of APIs are the .NET API, the C++ STL, the Java API, the Windows API, the Linux headers, Qt, GTK, even React.
I always thought of API in the sense of POSIX Or NFS etc. A common interface that existed across different libraries regardless of the vendors. Designed for interoperability.
Well, to be fair, libraries and SDKs do have APIs, it's what you mainly interact with when you use them, the defined interface that you programmatically use in your application.
REST is for noobs, JSON RPC is silent pro's choice :)
Make all requests POST and enjoy easy life without useless debates on should creation of resource be on POST or PUT or should you return HTTP status 404 or 200 if resource/document on server is not found (of course if should be 200 because request was a success, 404 should only be used it api method is not found).
> - JSON RPC code generators are non-existent or badly maintained depending on the language.
Very much so. It’s in a terrible state where I’ve looked. Most of the tooling is by OpenAPI or similar which comes with a bloatload of crap that is only marginally better than say SOAP. It needs to be much simpler.
> - Not binary like Protobufs or similar
Agreed. This is not an issue for small things that can be base64 encoded but once you need large blob transfers you don’t have any reasonable option. This is a problem in eg graphql which also misses the mark and you have to step outside for things like file uploads.
It feels like the whole standardization effort around json rpc is weak. It doesn’t address the needs of modern RPC-like systems. Which is unfortunate because there’s a real opportunity to improve upon the chaos of REST.
Thanks for this. I felt I was going crazy, decrying many professional and smart engineers work as not being 'expert' enough, as if they didn't weigh up and consider other options. Yes, there can be a bit of cargo culting, but to claim that only experts use JSON RPC is ridiculous.
i always fail to understand what kind of services there are that aren’t at least RPC-ish
thin CRUD wrappers obviously but usually when you are piping data from one source/format to another, you typically want to do something that is ever so slightly “not-CRUD” (call another API/service, etc.)
I don't like REST either, but JSON RPC is similarly hamstrung in some scenarios (examples: streaming, CDN caching, binary encoding).
I mostly dislike REST because nobody can agree on what it is and there are too many zealots who love to bikeshed. If you stick with the simple parts of REST and ignore the zealots, it's decent enough for many scenarios.
I've yet to find an RPC protocol that fills all requirements I've encountered, they all have tradeoffs and at this point you're better off learning the tradeoffs and how to deal with them (REST, JSON RPC, gRPC, WebSockets, etc.) and how they interact with their transports (HTTP/1.1, H2, QUIC, etc.), and then play the unfortunate game of balancing tradeoffs.
ReST makes sense in certain cases, where resources are a tree (like a typical web site is a tree), with collections of leaves, and these leaves make sense by themselves. Then you can go full HATEOAS and reap some actual benefits from that.
Most of the time (like 99.9%) what you happen to need is JSON RPC. Even if some parts of your API surface look like they would fit the ReST model, the bulk does not. Ignore that, build a protocol along the lines of your subject area. Always return 200 if your server did not fail or reject the request, use internal status signaling for details. Limit yourself to GET and POST. Use HTTP as a mere transport.
"Use internal status signaling" for example doesn't seem any better than deciding what status codes mean what; it's just a second layer of codes where the first one is now useless.
"Limit yourself to GET and POST." - delete and patch are pretty useful for documentation simplicity too. If there were a LIST verb that would be even handier, but nothing's perfect.
"build a protocol along the lines of your subject area" - I think you can do this (and well or badly) using REST or RPC forms.
+1 and I'll bump it up a notch... not only should you ignore REST you should ignore URLs. You want to write protocols, not APIs. Redis, for example, has a better "API" than any web API I've used. Easy to use, easy to wrap, easy to extend and version. HTTP is the other obvious example that I shouldn't have to go into.
This article defines REST incorrectly, and doesn't seem to understand the concept of HTTP methods, calling them verbs (arguably fine) and types (huh?) seemingly arbitrarily. Methods are a core part of HTTP -- just because you can't specify them explicitly in a browser as a user doesn't mean they're "cryptic curl arguments" or worth ignoring. I'm not sure I'd put too much stock into this perspective.
I want to emphasize that I was not thinking about JSON RPC as a specific protocol, but more as a JSON format to transfer data, similar to how REST APIs usually do, and some kind of "HTTP method agnostic remote procedure call", it does not have to be JSON RPC standard.
Personally, I am a fan of just having API Class-es + methods that automatically map to API calls with automatic api interface and doc builders. I find that it would be super strange if I had to prefix my internal methods with DELETE or PUT based on do they remove or add to some Array. Using that logic, why do that in APIs.
I just find it super strange that people want to mirror their app logic + error response codes to some protocol like HTTP – ridiculous :) Why not go even lower as TCP and use some of that spec for our client <> server API conn. Many people will laugh, but if you think about it, where is the difference?
> I find that it would be super strange if I had to prefix my internal methods with DELETE or PUT based on do they remove or add to some Array. Using that logic, why do that in APIs.
It's true that POST ends up being a bit of a grab bag for all the non-CRUD API calls.
But I find it very useful when looking over someonje's API to find them using PUT, or DELETE. PUT in particular provides really useful signals about the nature of the resource we are dealing with.
And lets not get started with the in-built caching etc. you throw away by not using GET.
> I just find it super strange that people want to mirror their app logic + error response codes to some protocol like HTTP – ridiculous :)
Why is this ridiculous?
HTTP is the default protocol for network services, so it seems to me that it is perfectly sensible to design your API to be compatible with HTTP semantics.
> Why not go even lower as TCP and use some of that spec for our client <> server API conn. Many people will laugh, but if you think about it, where is the difference?
Because HTTP is the only protocol that can reliably transit arbitrary networks (middle-boxes, NAT, etc.) in practice.
I've been a REST API developer for a few years now. For whatever reason, I've never bothered dipping my toes in the RPC realm. This article resonated with me. Looks like I'll be building an RPC API in the near future.
People are complimenting great technical writing here, but the first definition they provide is this:
> Technically, an API is just a set of rules (interface) that the two sides agree to follow. The company publishing the API then implements their side by writing a program and putting it on a server. In practice, lumping the interface in with the implementation is an easier way to think about it.
which is neither technically correct, nor easy to understand for a layperson. Compare to Wikipedia:
> An application programming interface (API) is a way for two or more computer programs to communicate with each other. It is a type of software interface, offering a service to other pieces of software.
This is the most difficult topic for me. I struggle to discover, understand and implement in my code highly linked resources. How an API is organized or designed should be its own chapter IMHO
“We'll skip the details…
[…] REST practitioners are split on how to solve the problem of associating resources.”
I think JSON [tree] data [with no fixed field for unique identifier, and no fkey referencing] is wrong. The lack of a proper type system+schema for data is wrong. The need for server-side query management makes any API supremely rigid.
Still some concerns to solve, for me, with REST APIs.
JSON covers syntax not semantics. This means you can build the formats you want on top of JSON by only describing the semantics without having to make decisions about syntax or write parsers.
Not taking care of the semantics and letting [mostly] code take care of it is what I don’t like about that format.
[standardization of @id and @type special attributes by JSON-LD sound like a good step forward, imho]
This article advocates for a traditional REST API design. At Seam, we use an API design that is like a RESTful RPC API, inspired by the API at Slack. I think that HTTP RPC and Slack-like APIs are much better than traditional REST because most consumers of an API use an SDK, and RPC-style HTTP APIs optimize for the SDK usage.
We also built a framework like trpc but for Next REST APIs[1] to get all the nice benefits of shared types but also the nice benefits of OpenAPI generation that typically come with RESTful frameworks https://github.com/seamapi/nextlove
Side point - has anyone got a better way to refer to a non-technical person than "non-technical"? I see they use that term in the intro and I use it to but seems a bit condescending.
Readit News
For most shit you wanna do, its view, edit, delete, its really not that complicated.
Another time, the server had the resource but didn’t like the state of the data, so refused to serve it. Debate ensued as to whether this was a 400 or 500 class error. People got religious.
Yes there’s an answer but it should be so obvious that we don’t have the debate. This isn’t sophisticated verbs, both happened with GET.
Desktop, embedded, video games, HPC suddenly cried out in terror and were suddenly silenced.
Like, this is a fundamental aspect of how I interact with my job and business has taken the term and elevated it into its own distinct thing
What leads you to believe that a HTTP API does not meet the definition of a API?
For me, an API is a lot more concrete: a set of data structures (whether they be classes, objects, pairs, tuples, lambda functions, etc.) with extensible functionality (member functions, pure functions accepting those data structures, etc.) that developers can use independently, or together, to produce some new functionality, i.e. program using interfaces.
So what I'd traditionally think of APIs are the .NET API, the C++ STL, the Java API, the Windows API, the Linux headers, Qt, GTK, even React.
Make all requests POST and enjoy easy life without useless debates on should creation of resource be on POST or PUT or should you return HTTP status 404 or 200 if resource/document on server is not found (of course if should be 200 because request was a success, 404 should only be used it api method is not found).
I 100% agree with Troy Griffitts beautiful take https://vmrcre.org/web/scribe/home/-/blogs/why-rest-sucks
- Everything is a POST, so normal HTTP caching is out of the question.
- JSON RPC code generators are non-existent or badly maintained depending on the language. Same with doc generators.
- Batching is redundant with HTTP2, just complicates things.
- Because everything is a POST normal logging isn't effective (i.e. see the url in logs, easy to filter etc). You'll have to write something yourself.
- Not binary like Protobufs or similar
But yeah, "the silent pro's choice"... Let's keep it silent.
JSON RPC is pretty much dead at this point and superseded by better alternatives if you're designing an RPC service.
Very much so. It’s in a terrible state where I’ve looked. Most of the tooling is by OpenAPI or similar which comes with a bloatload of crap that is only marginally better than say SOAP. It needs to be much simpler.
> - Not binary like Protobufs or similar
Agreed. This is not an issue for small things that can be base64 encoded but once you need large blob transfers you don’t have any reasonable option. This is a problem in eg graphql which also misses the mark and you have to step outside for things like file uploads.
It feels like the whole standardization effort around json rpc is weak. It doesn’t address the needs of modern RPC-like systems. Which is unfortunate because there’s a real opportunity to improve upon the chaos of REST.
thin CRUD wrappers obviously but usually when you are piping data from one source/format to another, you typically want to do something that is ever so slightly “not-CRUD” (call another API/service, etc.)
I mostly dislike REST because nobody can agree on what it is and there are too many zealots who love to bikeshed. If you stick with the simple parts of REST and ignore the zealots, it's decent enough for many scenarios.
I've yet to find an RPC protocol that fills all requirements I've encountered, they all have tradeoffs and at this point you're better off learning the tradeoffs and how to deal with them (REST, JSON RPC, gRPC, WebSockets, etc.) and how they interact with their transports (HTTP/1.1, H2, QUIC, etc.), and then play the unfortunate game of balancing tradeoffs.
Most of the time (like 99.9%) what you happen to need is JSON RPC. Even if some parts of your API surface look like they would fit the ReST model, the bulk does not. Ignore that, build a protocol along the lines of your subject area. Always return 200 if your server did not fail or reject the request, use internal status signaling for details. Limit yourself to GET and POST. Use HTTP as a mere transport.
"Use internal status signaling" for example doesn't seem any better than deciding what status codes mean what; it's just a second layer of codes where the first one is now useless.
"Limit yourself to GET and POST." - delete and patch are pretty useful for documentation simplicity too. If there were a LIST verb that would be even handier, but nothing's perfect.
"build a protocol along the lines of your subject area" - I think you can do this (and well or badly) using REST or RPC forms.
If you'd like a good back and forth on the idea the classic c2 page is a great resource. http://wiki.c2.com/?ApiVsProtocol
I want to emphasize that I was not thinking about JSON RPC as a specific protocol, but more as a JSON format to transfer data, similar to how REST APIs usually do, and some kind of "HTTP method agnostic remote procedure call", it does not have to be JSON RPC standard.
Personally, I am a fan of just having API Class-es + methods that automatically map to API calls with automatic api interface and doc builders. I find that it would be super strange if I had to prefix my internal methods with DELETE or PUT based on do they remove or add to some Array. Using that logic, why do that in APIs.
I just find it super strange that people want to mirror their app logic + error response codes to some protocol like HTTP – ridiculous :) Why not go even lower as TCP and use some of that spec for our client <> server API conn. Many people will laugh, but if you think about it, where is the difference?
It's true that POST ends up being a bit of a grab bag for all the non-CRUD API calls.
But I find it very useful when looking over someonje's API to find them using PUT, or DELETE. PUT in particular provides really useful signals about the nature of the resource we are dealing with.
And lets not get started with the in-built caching etc. you throw away by not using GET.
Why is this ridiculous?
HTTP is the default protocol for network services, so it seems to me that it is perfectly sensible to design your API to be compatible with HTTP semantics.
> Why not go even lower as TCP and use some of that spec for our client <> server API conn. Many people will laugh, but if you think about it, where is the difference?
Because HTTP is the only protocol that can reliably transit arbitrary networks (middle-boxes, NAT, etc.) in practice.
Deleted Comment
> Technically, an API is just a set of rules (interface) that the two sides agree to follow. The company publishing the API then implements their side by writing a program and putting it on a server. In practice, lumping the interface in with the implementation is an easier way to think about it.
which is neither technically correct, nor easy to understand for a layperson. Compare to Wikipedia:
> An application programming interface (API) is a way for two or more computer programs to communicate with each other. It is a type of software interface, offering a service to other pieces of software.
This is the most difficult topic for me. I struggle to discover, understand and implement in my code highly linked resources. How an API is organized or designed should be its own chapter IMHO
“We'll skip the details… […] REST practitioners are split on how to solve the problem of associating resources.”
UUUG
Still some concerns to solve, for me, with REST APIs.
We also built a framework like trpc but for Next REST APIs[1] to get all the nice benefits of shared types but also the nice benefits of OpenAPI generation that typically come with RESTful frameworks https://github.com/seamapi/nextlove
This avoids classification of the reader. To refer to someone who lacks the knowledge of a domain, they are a “layman”.
https://dictionary.cambridge.org/dictionary/english/layperso...
someone who is not an expert in or does not have a detailed knowledge of a particular subject
"bluffer" would be a humorous alternative.
Non-technical = not technical = does not have technical expertise.
Seems pretty logical to me
I find it hard to call a data analyst (for example), who can be highly technical, as a non-technical person.
Deleted Comment
Deleted Comment