4 ms·

You can have as many verbs as you want, but they all need to be valid at every state of the application (i.e at every hypermedia target), because you still want

You can have as many verbs as you want, but they all need to be valid at every state of the application (i.e at every hypermedia target), because you still want a uniform interface. Responding with a standard error code is okay for verbs that are not supported at a particular state, but it's the uniform interface constraint that forces you to keep the set of verbs small. Also, HTTP has nine verbs: GET, POST, PUT, DELETE, HEAD, CONNECT, OPTIONS, PATCH, and TRACE.

WClayFerguson 6y ago
You can read most any good book on software development and API design, and OOP, and how to create good abstraction layers, and how to name functions, and pass parameters etc. Here's the thing: None of those concepts in those books are trumped once you happen to be communicating over HTTP/HTTPS. None of those books tell you to come up with 9 verbs, and make everything a noun operated on by those 9. That's silly. HTTP layer has a place in the tech stack. Let it do what it does. Your API RPC layer is a separate abstraction layer, that also needs to exist. Trying to merge RPC down into the HTTP layer is silly and is cramming a square peg into a round hole, just because the round hole already existed.
- noblethrasher 6y ago
  HTTP is one particular implementation of REST that happens to have nine verbs. Another implementation might only have two or three. But no RESTful architecture will have much more than nine. Why? Because your application is going to have thousands of nominal states, and each one is going to need to support all of the verbs because of the uniform interface constraint. Why a uniform interface? A lot to say about this, but basically, the set of verbs is an abstraction of the state machine that is your application. If you have a million states and a million verbs, then you have no abstraction. If you have ten states and a hundred verbs then you have too much abstraction (i.e. you ran afoul of YAGNI). A good degree abstraction is somewhere in between, but if you care about scale (which is the raison d'être for REST), then the size of set of verbs is going to have a logarithmic relation to the size of the set of nominal states.
  - jonahx 6y ago
    > A lot to say about this I'd like to read more about this way of thinking about it. Do you have any recommended resources?
    - noblethrasher 6y ago
      Most of what I have to say comes from Fielding’s dissertation, along with spending the past several years trying to take it as seriously as possible. Other good sources are McCarthy’s Situation Calculus and all of the stuff that Lamport has written on on TLA+ (especially Specifying Systems[1]). The big idea behind scalability (IMO) is that we want the pain of maintaining a system to grow logarithmically with respect to the size of the system. Now, size can mean many things (number of customers, lines of code, etc.), but pain is almost always complexity. A potent cure for complexity is symmetry, because every time that we discover a new symmetry, half of the complexity goes away. One way of finding symmetry is to look for invariants. Roughly speaking (very roughly), having lots of possible states is good (the more states, the more powerful/featureful the system), but having lots of state transitions is bad (especially with respect to security). REST “verbs” help to control complexity by imposing invariants on state transitions. For instance, one good invariant to enforce is that a GET transition mean that a state can always be a start state, whereas a POST must always have an antecedent state. Thus, a REST verb is just label for a set of invariants, and we’re free to choose whatever set of invariants we want. Obviously, the more invariants you have, the weaker they are since an invariant is supposed to be unchanging; i.e. if the size of set of invariants is close to the size of the set of states, then you effectively have no invariants. [1] https://lamport.azurewebsites.net/tla/book-02-08-08.pdf https://lamport.azurewebsites.net/tla/book-02-08-08.pdf
  - WClayFerguson 6y ago
    Most applications will have more "states" than there are molecules in the known universe. Number of states is meaningless, and doesn't play into anything. If I need to delete users I want a function called "deleteUser" (for example) and it will use an HTTP post to send up info, and it will stream back the response. Period, full stop. An HTTP "post" is your 'backbone'. Nothing else about HTTP needs to creep into your actual domain specific API language of method names in your RPC vocabulary of verbs. Also if non-HTTP REST can exist, that's fine, but I'm writing web apps so I will be doing HTTP-posts because, as Fielding himself would say, why redesign something that works.
- clhodapp 6y ago
  My experience is that the design considerations within a system are different from the design considerations between systems. Specifically, noun-oriented APIs with few generic verbs tend to be extremely effective at: 1) Being relatively fast for external developers to come up to speed with 2) Allowing (and in fact pressuring) you to make non-breaking evolutions to your API without it devolving into a total mess of confusing semi-overlapping operations 3) (As a result of the other two) Minimizing the bidirectional communication needed between groups of developers The major con is that they tend to require quite a bit more work and code to implement than operation-oriented APIs, especially when you are the only client. Others will certainly have different opinions, but the view I've been forming over the last few years is that resource-oriented (noun-oriented) APIs should be considered the default for "external" interfaces, while operation-oriented APIs are much better-suited for "internal" interfaces. Do note that, in this model, deciding what is "internal" vs "external" should be an active design choice. It should be made based on your expectations for code ownership/control, communication frequency, and project structure.
  - WClayFerguson 6y ago
    One of the reasons Amazon was successful as a cloud hosting company, and offers all the services it does is because of the famous Bezos email/memo to the entire company saying every API has to be designed as if it were external facing (usable by 3rd parties). I think what you are conflating is "good documentation" and "well designed APIs" as an attribute of REST, when it's really just an attribute of good engineering. Engineers have used functional interfaces for decades and there's just nothing at all in REST that's any kind of improvement over functional. There's a reason "functional programming" is a thing and "nounical programming" isn't even a word.
    - wolfgang42 6y ago
      “Nounical programming” is only not a word because it’s called “object-oriented” instead.
      - WClayFerguson 6y ago
u801e 6y ago
IMAP has many more verbs compared to HTTP, so wouldn't it be a better application layer protocol compared to HTTP for a REST API?
- WClayFerguson 6y ago
  For normal SPA JavaScript/TypeScript browser-based apps, I like the conventional approach of an HTTP "post" for every API call. You send JSON upstream and you get a JSON response back. Basically it's an Ajax call that gets data back to use to update the page.
- noblethrasher 6y ago
  REST doesn't care about the size of the set of verbs, only that the set be constant. HTTP as one particular implementation of REST just happens to have nine verbs. I tried to implement an IMAP server a few years ago, but otherwise I don't know much about it. However, I do recall that Mark Crispin admitted that he wasn't a very good API designer, and that much of the complexity of IMAP was due to it being intertwined with the complexity of MIME. But, I can't find the sources for those claims at the moment.
bmn__ 6y ago
> Also, HTTP has nine verbs http://webconcepts.info/concepts/http-method/ http://webconcepts.info/concepts/http-method/
- WClayFerguson 6y ago
  Right, I simplify REST it as a CRUD model, because nobody ever uses the full 9 verbs in REST architectures anyway. My who point is that having a fixed set of verbs is about as awkward as it gets in software design, even if there were 100 to choose from.

WClayFerguson 6y ago

You can read most any good book on software development and API design, and OOP, and how to create good abstraction layers, and how to name functions, and pass parameters etc. Here's the thing: None of those concepts in those books are trumped once you happen to be communicating over HTTP/HTTPS. None of those books tell you to come up with 9 verbs, and make everything a noun operated on by those 9. That's silly. HTTP layer has a place in the tech stack. Let it do what it does. Your API RPC layer is a separate abstraction layer, that also needs to exist. Trying to merge RPC down into the HTTP layer is silly and is cramming a square peg into a round hole, just because the round hole already existed.

noblethrasher 6y ago
HTTP is one particular implementation of REST that happens to have nine verbs. Another implementation might only have two or three. But no RESTful architecture will have much more than nine. Why? Because your application is going to have thousands of nominal states, and each one is going to need to support all of the verbs because of the uniform interface constraint. Why a uniform interface? A lot to say about this, but basically, the set of verbs is an abstraction of the state machine that is your application. If you have a million states and a million verbs, then you have no abstraction. If you have ten states and a hundred verbs then you have too much abstraction (i.e. you ran afoul of YAGNI). A good degree abstraction is somewhere in between, but if you care about scale (which is the raison d'être for REST), then the size of set of verbs is going to have a logarithmic relation to the size of the set of nominal states.
- jonahx 6y ago
  > A lot to say about this I'd like to read more about this way of thinking about it. Do you have any recommended resources?
  - noblethrasher 6y ago
    Most of what I have to say comes from Fielding’s dissertation, along with spending the past several years trying to take it as seriously as possible. Other good sources are McCarthy’s Situation Calculus and all of the stuff that Lamport has written on on TLA+ (especially Specifying Systems[1]). The big idea behind scalability (IMO) is that we want the pain of maintaining a system to grow logarithmically with respect to the size of the system. Now, size can mean many things (number of customers, lines of code, etc.), but pain is almost always complexity. A potent cure for complexity is symmetry, because every time that we discover a new symmetry, half of the complexity goes away. One way of finding symmetry is to look for invariants. Roughly speaking (very roughly), having lots of possible states is good (the more states, the more powerful/featureful the system), but having lots of state transitions is bad (especially with respect to security). REST “verbs” help to control complexity by imposing invariants on state transitions. For instance, one good invariant to enforce is that a GET transition mean that a state can always be a start state, whereas a POST must always have an antecedent state. Thus, a REST verb is just label for a set of invariants, and we’re free to choose whatever set of invariants we want. Obviously, the more invariants you have, the weaker they are since an invariant is supposed to be unchanging; i.e. if the size of set of invariants is close to the size of the set of states, then you effectively have no invariants. [1] https://lamport.azurewebsites.net/tla/book-02-08-08.pdf https://lamport.azurewebsites.net/tla/book-02-08-08.pdf
- WClayFerguson 6y ago
  Most applications will have more "states" than there are molecules in the known universe. Number of states is meaningless, and doesn't play into anything. If I need to delete users I want a function called "deleteUser" (for example) and it will use an HTTP post to send up info, and it will stream back the response. Period, full stop. An HTTP "post" is your 'backbone'. Nothing else about HTTP needs to creep into your actual domain specific API language of method names in your RPC vocabulary of verbs. Also if non-HTTP REST can exist, that's fine, but I'm writing web apps so I will be doing HTTP-posts because, as Fielding himself would say, why redesign something that works.
clhodapp 6y ago
My experience is that the design considerations within a system are different from the design considerations between systems. Specifically, noun-oriented APIs with few generic verbs tend to be extremely effective at: 1) Being relatively fast for external developers to come up to speed with 2) Allowing (and in fact pressuring) you to make non-breaking evolutions to your API without it devolving into a total mess of confusing semi-overlapping operations 3) (As a result of the other two) Minimizing the bidirectional communication needed between groups of developers The major con is that they tend to require quite a bit more work and code to implement than operation-oriented APIs, especially when you are the only client. Others will certainly have different opinions, but the view I've been forming over the last few years is that resource-oriented (noun-oriented) APIs should be considered the default for "external" interfaces, while operation-oriented APIs are much better-suited for "internal" interfaces. Do note that, in this model, deciding what is "internal" vs "external" should be an active design choice. It should be made based on your expectations for code ownership/control, communication frequency, and project structure.
- WClayFerguson 6y ago
  One of the reasons Amazon was successful as a cloud hosting company, and offers all the services it does is because of the famous Bezos email/memo to the entire company saying every API has to be designed as if it were external facing (usable by 3rd parties). I think what you are conflating is "good documentation" and "well designed APIs" as an attribute of REST, when it's really just an attribute of good engineering. Engineers have used functional interfaces for decades and there's just nothing at all in REST that's any kind of improvement over functional. There's a reason "functional programming" is a thing and "nounical programming" isn't even a word.
  - wolfgang42 6y ago
    “Nounical programming” is only not a word because it’s called “object-oriented” instead.
    - WClayFerguson 6y ago

u801e 6y ago

IMAP has many more verbs compared to HTTP, so wouldn't it be a better application layer protocol compared to HTTP for a REST API?

WClayFerguson 6y ago
For normal SPA JavaScript/TypeScript browser-based apps, I like the conventional approach of an HTTP "post" for every API call. You send JSON upstream and you get a JSON response back. Basically it's an Ajax call that gets data back to use to update the page.
noblethrasher 6y ago
REST doesn't care about the size of the set of verbs, only that the set be constant. HTTP as one particular implementation of REST just happens to have nine verbs. I tried to implement an IMAP server a few years ago, but otherwise I don't know much about it. However, I do recall that Mark Crispin admitted that he wasn't a very good API designer, and that much of the complexity of IMAP was due to it being intertwined with the complexity of MIME. But, I can't find the sources for those claims at the moment.

bmn__ 6y ago

> Also, HTTP has nine verbs http://webconcepts.info/concepts/http-method/ http://webconcepts.info/concepts/http-method/

WClayFerguson 6y ago
Right, I simplify REST it as a CRUD model, because nobody ever uses the full 9 verbs in REST architectures anyway. My who point is that having a fixed set of verbs is about as awkward as it gets in software design, even if there were 100 to choose from.