Swagger.

[sorhed]

Прорекламирую Swagger. Это такая штука, которая позволяет на коленке специфицировать всякие там REST/JSON API.

Да, оно сырое, необтёсанное, и не во всех языках программирования есть адекватная поддержка. Но альтернативы я не знаю. Жизненно необходимая штука, коей будут вскоре пользоваться все.