We are currently discussing general architectures of REST APIs as we're replacing our SOAP interface with something more light-weight. It appears to me that although modern and widely adopted APIs are using RESTful designs, the represented data definition is pretty much custom.<p>AtomPub is designed to define clear relations between resources in REST and allow for typing of data fields, but nobody really uses it (Google's Data API used to, but most of it is deprecated nowadays). So, do people just use a pragmatic approach and document the API manually, or is there something fundamentally wrong with AtomPub, beside failing to gain a critical audience?