I Need A REST

REST is representational state transfer, and is in truth transport agnostic, but when people talk about RESTful APIs they're usually talking about REST over HTTP. And when you're talking about HTTP and REST, you need to think about your `goesintos` and `goesoutofs`, your verbs and your bodies. HTTP 1.1 only defines 8 verbs, and which one to use for a given method is pretty well defined. When you're defining your API think about safety and idempotence. Distributed systems live and die by idempotence, and we have a lot of distribution.

Think about your inputs. Are they all required? Are there reasonable defaults? Is there some set of values that are mutually exclusive? That might be OK, but be mindful of it. And don't accept inputs if there shouldn't be any. It's not an error to send a body with a GET request instead of using query parameters, but GET requests are supposed to ignore the body, so from the principle of least astonishment, it's a bad idea. You never know who's going to drop/ignore it along the way.

Think about your outputs. First of all, the HTTP spec has defined as set of return codes. Use them. And use them as they're intended. Not all successes are 200, but all 2XXs are successes. If you need to provide more details then use the body.

And of course, this doesn't apply to only REST over HTTP. Idempotence and not astonishing your users is important regardless of what your API is. If you're using gRPC it's not as clear what is idempotent, but minimize side-effects. Setters clearly change something, and Getters never should.