4 ms·

I think a conversation between a web browser (SPA RPC) and a back-end server is best thought of as an RPC. Procedure calls are verbs if you ask me. Here's my o

I think a conversation between a web browser (SPA RPC) and a back-end server is best thought of as an RPC. Procedure calls are verbs if you ask me. Here's my own code that is such an API: https://github.com/Clay-Ferguson/quantizr/blob/master/src/main/java/org/subnode/AppController.java https://github.com/Clay-Ferguson/quantizr/blob/master/src/ma... You can point out that 80% of those API methods are resulting in some kind of CRUD method, and I'd agree, but nonetheless trying to make it a true REST API would be super awkward and verbose, imo, because lots of those functions result in multiple CRUD ops on multiple different types of data. When I design an API, I think: "What is this operation called? What data is best to send upstream, and what do I want to get back." Then I design the API. The API is a wrapper around an abstraction layer of functionality. REST is all about removing that abstraction layer which is moronic.

tsimionescu 6y ago
This is all a matter of definitions. For example, from a syntactic point of view, Java has three verbs for all objects: "instantiate (new)", "call method" and "access field". An object has members, and you can use those 3 verbs to interact with the members of the object. In my experience, the nice part about designing APIs in a REST-like manner is that they encourage you to think in terms of observable operations. For example, instead of "calling" a long running blocking method, you create a resource that represents the long running operation, and now you can check its status while it is running, report progress, cancel it. Basically, when designing a REST API you think about the exact same things you are saying - what is the operation called? what data does it need, and what does it return? - and then you represent this as a resource that can be created with the right input, and that will point to a result resource for the final output. For example, my usual pattern for things outside of CRUD is something like this: --> POST .../operations/renderNode {ExecuteNodeRequest goes here} <-- 202 Accepted Location: .../operations/renderNode/891 --> GET .../operations/renderNode/891 <-- 200 OK {status: IN_PROGRESS, percentage: 78, ... (includes initial ExecuteNodeRequest params)} --> GET .../operations/renderNode/891 <-- 200 OK {status: SUCCESSFUL, percentage: 100, resultURL: .../operations/renderNode/891/result, ...} And then on GET .../operations/renderNode/891/result, you have the final result. Of course, if the operation finishes quickly enough, any of the polling steps can be omitted - e.g. it can directly return 200 OK and the result URL for the initial request. If you have WebSockets support, you can also be notified via WebSockets when execution finishes, instead of polling. It may look like more ceremony, but in general, for long running operations that will be called from a browser, this kind of approach is a requirement anyway, since the number of connections with a particular origin is extremely limited. Note that I also think your API would be much more concise as a REST API, since all of the miriad "setX", "getX", "createY" methods would be reduced to a few resources with multiple fields, that you can simply GET to see all fields, or PATCH to change a single field (or even change multiple fields in a single request).
- lmilcin 6y ago
  The goal of REST isn't to be the RPC protocol. It is to be lower level protocol which uses simple verbs to transfer state. For example, SQL has simple verbs because it doesn't want to know what are the actual operations executed by the application (for example, verifying status of an existing process, checking optimisting lock, etc.) Another example are some remote memory interfaces which basically transfer blocks of memory back and forth without knowing what is the operation for. You build your higher level, business logic-aware protocol on top of it. The same way, REST is about intentionally not getting involved with the imperative style and instead provide transport protocol that will make it possible to refer to the things as resources, discover resource graph through hyperlinks, etc. The business logic is supposed to introduce changes to the object but use REST to only transfer representation of the changed state (Representational State Transfer) without burdening it with RPC details. That is why so many APIs fail to use REST effectively, because designers do not understand the goal and limitations of REST. It is conscious decision not only what the API does but also what it is not supposed to do. To update the user the REST-ful way would be to allow the client to fetch the user document, introduce changes client side with whatever logic the client wants and then transfer the representation of modified state back to the server with a simple verb (same way we interact with filesystem through reads and writes without kernel ever knowing what this is). The server decides what to do with these changes. Trying to burden the kernel with information about what the operation is is futile but that's what usually happens when people design "REST"-ful APIs.
  - WClayFerguson 6y ago
    > The goal of REST isn't to be the RPC protocol I'd politely disagree with that. I think most REST fanatics ACTUALLY DO claim that their beautiful arrangement of nouns and their 4 CRUD verbs are capable of replacing RPC, because they've become convinced the "procedure" part of RPC, means that RPC is inherently built around functional programming which is verbs, and they think they've found a better way than using a custom vocabulary of verbs. So they're using REST instead of RPC, because "verbs are bad". I'll just restate my opinion that the concepts of "functional programming" are not somehow rendered obsolete whenever the machine you're talking to happens to be remote. Sure, there are certain challenges involved with designing a 'remote' API that can arise involving latency and bandwidth considerations, but those limitations in no way imply a solution where you throw out your entire set of "verbs", like REST does.

tsimionescu 6y ago

This is all a matter of definitions. For example, from a syntactic point of view, Java has three verbs for all objects: "instantiate (new)", "call method" and "access field". An object has members, and you can use those 3 verbs to interact with the members of the object. In my experience, the nice part about designing APIs in a REST-like manner is that they encourage you to think in terms of observable operations. For example, instead of "calling" a long running blocking method, you create a resource that represents the long running operation, and now you can check its status while it is running, report progress, cancel it. Basically, when designing a REST API you think about the exact same things you are saying - what is the operation called? what data does it need, and what does it return? - and then you represent this as a resource that can be created with the right input, and that will point to a result resource for the final output. For example, my usual pattern for things outside of CRUD is something like this: --> POST .../operations/renderNode {ExecuteNodeRequest goes here} <-- 202 Accepted Location: .../operations/renderNode/891 --> GET .../operations/renderNode/891 <-- 200 OK {status: IN_PROGRESS, percentage: 78, ... (includes initial ExecuteNodeRequest params)} --> GET .../operations/renderNode/891 <-- 200 OK {status: SUCCESSFUL, percentage: 100, resultURL: .../operations/renderNode/891/result, ...} And then on GET .../operations/renderNode/891/result, you have the final result. Of course, if the operation finishes quickly enough, any of the polling steps can be omitted - e.g. it can directly return 200 OK and the result URL for the initial request. If you have WebSockets support, you can also be notified via WebSockets when execution finishes, instead of polling. It may look like more ceremony, but in general, for long running operations that will be called from a browser, this kind of approach is a requirement anyway, since the number of connections with a particular origin is extremely limited. Note that I also think your API would be much more concise as a REST API, since all of the miriad "setX", "getX", "createY" methods would be reduced to a few resources with multiple fields, that you can simply GET to see all fields, or PATCH to change a single field (or even change multiple fields in a single request).

lmilcin 6y ago
The goal of REST isn't to be the RPC protocol. It is to be lower level protocol which uses simple verbs to transfer state. For example, SQL has simple verbs because it doesn't want to know what are the actual operations executed by the application (for example, verifying status of an existing process, checking optimisting lock, etc.) Another example are some remote memory interfaces which basically transfer blocks of memory back and forth without knowing what is the operation for. You build your higher level, business logic-aware protocol on top of it. The same way, REST is about intentionally not getting involved with the imperative style and instead provide transport protocol that will make it possible to refer to the things as resources, discover resource graph through hyperlinks, etc. The business logic is supposed to introduce changes to the object but use REST to only transfer representation of the changed state (Representational State Transfer) without burdening it with RPC details. That is why so many APIs fail to use REST effectively, because designers do not understand the goal and limitations of REST. It is conscious decision not only what the API does but also what it is not supposed to do. To update the user the REST-ful way would be to allow the client to fetch the user document, introduce changes client side with whatever logic the client wants and then transfer the representation of modified state back to the server with a simple verb (same way we interact with filesystem through reads and writes without kernel ever knowing what this is). The server decides what to do with these changes. Trying to burden the kernel with information about what the operation is is futile but that's what usually happens when people design "REST"-ful APIs.
- WClayFerguson 6y ago
  > The goal of REST isn't to be the RPC protocol I'd politely disagree with that. I think most REST fanatics ACTUALLY DO claim that their beautiful arrangement of nouns and their 4 CRUD verbs are capable of replacing RPC, because they've become convinced the "procedure" part of RPC, means that RPC is inherently built around functional programming which is verbs, and they think they've found a better way than using a custom vocabulary of verbs. So they're using REST instead of RPC, because "verbs are bad". I'll just restate my opinion that the concepts of "functional programming" are not somehow rendered obsolete whenever the machine you're talking to happens to be remote. Sure, there are certain challenges involved with designing a 'remote' API that can arise involving latency and bandwidth considerations, but those limitations in no way imply a solution where you throw out your entire set of "verbs", like REST does.