Очень хорошая документация у
LinedIn. Это как пример оформления документации скорее.
Так же почитайте что такое ресурс. что такое uri.... Большая часть правил по которым нужно формировать API строятся как раз на этих принципах.
Если говорить о best practice, есть еще
HATEOAS и
Json Api. чем это все хорошо - позволяет автоматически генерировать клиентский код. Скажем помниться мне для angular.js есть модуль позволяющий легко и просто взаимодействовать с HATEOAS. Но если честно, я редко сталкивался с апишками где это используется. Сходу вспомню что Sun (oracle) использует в енто дело в своих апишках для работы с клаудами.
