I don't know for web external APIs but for an internal network of services talking to each other I've found GraphQL to be very convenient. The "single entry point" and "describe what you want, you'll get what you described" mindset makes it powerful, when used with the graphiql trial and error interface. We barely have to document anything anymore. It seems a bit weird to use a twisted json for the queries but it works well after getting used to it. If someone wants to go this road, I'd suggest enforcing use of variables in queries (so high level caching works better) and do directly to the connection modelfor pagination.
http://graphql.org/learn/queries/#variables http://graphql.org/learn/pagination/