You need to know the mess that was SOAP before you go into REST, like you need to know about XML before you criticize JSON.
JSON is not a good place to put anything but data, to specify an API with a meta language has been disproven by SOAP already.
My approach to end all API fragmentation is to simply use JSON over HTTP with minimalism!
I do not conform to REST, but instead exclusively use GET and POST and return 200 everywhere and handle everything manually from there.
I also make HTML forms to all API entrypoints so you can test and learn how the API works by browsing and viewing source.