Code review REST API

magx2
Posts: 312
Joined: Wed May 17, 2017 1:27 pm
Contact:

Tue Aug 01, 2017 7:05 am

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
User avatar
pzygmunt
Posts: 6866
Joined: Tue Jan 19, 2016 9:26 am
Location: Paczków
Contact:

Tue Aug 01, 2017 8:42 am

.... tak jakoś wyszło. Teraz już niezbyt możemy to zmienić.
magx2
Posts: 312
Joined: Wed May 17, 2017 1:27 pm
Contact:

Tue Aug 01, 2017 9:10 am

To może zacznijmy wersjonować API? Teraz wszystkie calle zaczynają się od /api, natomiast nowe api może zaczynać się od /api/v2.
User avatar
pzygmunt
Posts: 6866
Joined: Tue Jan 19, 2016 9:26 am
Location: Paczków
Contact:

Tue Aug 01, 2017 9:46 am

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.
User avatar
fracz
Posts: 1583
Joined: Fri Oct 28, 2016 10:56 pm
Location: Rybna

Tue Aug 01, 2017 10:46 am

:P
User avatar
pzygmunt
Posts: 6866
Joined: Tue Jan 19, 2016 9:26 am
Location: Paczków
Contact:

Tue Aug 01, 2017 11:09 am

User avatar
fracz
Posts: 1583
Joined: Fri Oct 28, 2016 10:56 pm
Location: Rybna

Tue Aug 01, 2017 11:25 am

@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
Posts: 312
Joined: Wed May 17, 2017 1:27 pm
Contact:

Tue Aug 01, 2017 1:04 pm

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.
Post Reply