У меня уже было много проблем с несоответствием эндпоинтов, указанных в этой документации, правилам REST. Я чуть не вырвал все волосы на голове, пока пытался понять стандарт (структуру) API и написать wrapper-librarry. Потом я заметил, что структуры то вовсе и нет, что меня сильно удивило.
Давайте вспомним, какими принципами следует руководствоваться при написании RESTfull API:
- Использование существительных, а не глаголов
- Одно слово - один ресурс
- Использование множественного числа
- Иерархия ресурсов
- Использование ID для конкретных ресурсов
- Избегайте вложенности глубже двух уровней
- Использование query-параметров для фильтрации, сортировки и поиска
- Использование версий API
- Использование HTTP-методов для действий
Теперь конкретнее, пройдемся по тем эндпоинтам, что есть в API Stalcraft’а. Именно по тем, что не соответствуют пунктам хорошего тона REST.
Ошибки в запросной группе Clans
Повсеместная проблема. Она буквально в каждой запросной группе.
GET https://eapi.stalcraft.net/{region}/clan/{clan-id}/info
Почему clan, а не clans?
Хотя вот буквально рядышком есть вот такой эндпоинт:
GET https://eapi.stalcraft.net/{region}/clans
И зачем в конце нужна лишняя вложенность в виде /info? Если сам по себе смысл этого запроса - получить детальную информацию о клане. Т.е. можно было ограничиться:
GET https://eapi.stalcraft.net/{region}/clans/{id}
И это бы никак не помешало существованию следующего запроса:
GET https://eapi.stalcraft.net/{region}/clans/{clan-id}/members
# Хотя и тут нужна правка в виде `clan-id` -> `id`
Наоборот, это бы подчеркнуло иерархию. А уж тем более сделало бы интуитивно понятный метод, которые напрямую связан с запросной группой, но доступный только по User Access key.
Ошибки в запросной группе Сharacters
Здесь все те же самые ошибки, хотя можно было бы еще использовать query-параметризацию.
Так, вместо запроса:
GET https://eapi.stalcraft.net/{region}/character/by-name/{character}/profile
Можно было бы использовать запрос:
GET https://eapi.stalcraft.net/{region}/character/{id}/profile
А почему именно такой? Потому что в первом случае это буквально имя метода в запросе, чего в REST попросту быть не должно.
Если все таки нужно использовать 2 метода получения (по имени и по id), то сделайте еще один запрос:
GET https://eapi.stalcraft.net/{region}/character/{name}/profile
В современных фреймворках роутеры работают по принципу очереди. Если сначала запрос будет сравниваться по первому пути и там не будет возможности преобразовать данные из запроса в id: integer, то он перейдет ко второму пути и попробует преобразовать данные в name: string, что у него уже должно получиться.
Уважаемые разработчики! Я надеюсь, что я буду услышан и в конце концов API следующей версии придет в норму.
@Рупоры @Команда проекта
Подобный Issue я уже оставил в Issue Tracker на GitHub Stalcraft API: https://github.com/EXBO-Studio/stalcraft-api/issues/55
