Code review REST API

[magx2]

Jako że mam pewne doświadczenie związane z projektowanie RESTowego API (no i miałem potrzebę użycia Supla API), to pozwolę sobie na małe code review.

Dla uproszczenia przyjmę że wszystkie URLe zaczynają się od www.supla.server.pl/api.

/iodevices - Czemu zwracana jest jedno elementowa mapa (słownik) z wpisem iodevices? Czy nie można od razu zwrócić listy?

Zamist tego

{
"iodevices": [ ...lista urządzeń... ]
}

można zrobić to

[ ...lista urządzeń... ]

/iodevices/$id - Tutaj z kolei zwracamy zawsze jedno elemntową listę zamiast zwrócić od razu obiekt IODevice

[
{ ...pola io device...}
]

można zrobić to

{ ...pola io device...}

/server-info - Tak samo jak w przypadku /iodevices. Zwracana jest mapa zamiast od razu obiekt

[pzygmunt]

.... tak jakoś wyszło. Teraz już niezbyt możemy to zmienić.

[magx2]

To może zacznijmy wersjonować API? Teraz wszystkie calle zaczynają się od /api, natomiast nowe api może zaczynać się od /api/v2.

[pzygmunt]

Można tak zrobić ale zmian musi się trochę nazbierać. Developerzy mogą się lekko poirytować, że ledwo udostępniliśmy jedną wersję, a już coś zmieniamy. Póki co chcemy wprowadzić linki bezpośrednie.

[fracz]

[magx2]

Spoko, to zanotuj sobie to w kajeciku jako TODO

[pzygmunt]

Tu jest "kajecik TODO"
https://github.com/SUPLA/supla-cloud/issues

[fracz]

@magx2, znamy te problemy i na nasze nieszczęście byliśmy ich świadomi przy wydawaniu 2.0, ale "siła wyższa".

Api będzie wersjonowane. Obecne będzie dostępne pod /api (kompatybilność wstecz) oraz pod /api/v1. Potem będzie już można robić dowolne rewolucje i wydawać jako /api/v2, /api/v3 itd.

https://github.com/SUPLA/supla-cloud/labels/API

[magx2]

Super . Dobrze słyszeć, że zmiany API są w planach

[magx2]

Podepnę jeszcze jedną rzecz pod ten temat. Czy planujecie jakąś żywą dokumentacje API? W Javie korzystamy ze swaggera, który buduje docs z kodu, nie wiem czy coś takiego jest dostępnego dla PHP.