Each one of these have pros and cons but those are academic papers that I don't care to write right now. But I've worked and talked to a lot of frontend devs and they don't really care if we use any of the three examples that I gave.
For them, a good API:
- Is well documented - makes sense; I'm a fan of drfdocs. Also Swagger gets a lot of mentions.
- Is versioned - good point; because changes to existing ones break too many things
- Is idempotent - to be honest I had to look this one up but it's the same idea of pure functions. Given the same input, it should return the same value (output)
- Uses HTTP errors correctly - For example, don't return errors with 200 status. Oops.
- Uses HTTP verbs sensibly - they want none of that 'GET /v1.0/delete/100' because that shit is stupid.
- Is NOT SOAP - dear lord up above in heaven, not ever SOAP. Ever
I also don't like SOAP.