Code review REST API

magx2
Posty: 351
Rejestracja: śr maja 17, 2017 1:27 pm
Kontakt:

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
Java 4 Life :twisted:

API Java
GUI
Server Mock

Awatar użytkownika
pzygmunt
Posty: 18284
Rejestracja: wt sty 19, 2016 9:26 am
Lokalizacja: Paczków
Kontakt:

.... tak jakoś wyszło. Teraz już niezbyt możemy to zmienić.
magx2
Posty: 351
Rejestracja: śr maja 17, 2017 1:27 pm
Kontakt:

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

API Java
GUI
Server Mock

Awatar użytkownika
pzygmunt
Posty: 18284
Rejestracja: wt sty 19, 2016 9:26 am
Lokalizacja: Paczków
Kontakt:

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.
Awatar użytkownika
fracz
Posty: 2256
Rejestracja: pt paź 28, 2016 10:56 pm
Lokalizacja: Kraków

:P
magx2
Posty: 351
Rejestracja: śr maja 17, 2017 1:27 pm
Kontakt:

Spoko, to zanotuj sobie to w kajeciku jako TODO ;)
Java 4 Life :twisted:

API Java
GUI
Server Mock

Awatar użytkownika
pzygmunt
Posty: 18284
Rejestracja: wt sty 19, 2016 9:26 am
Lokalizacja: Paczków
Kontakt:

Awatar użytkownika
fracz
Posty: 2256
Rejestracja: pt paź 28, 2016 10:56 pm
Lokalizacja: Kraków

@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
Posty: 351
Rejestracja: śr maja 17, 2017 1:27 pm
Kontakt:

Super :). Dobrze słyszeć, że zmiany API są w planach
Java 4 Life :twisted:

API Java
GUI
Server Mock

magx2
Posty: 351
Rejestracja: śr maja 17, 2017 1:27 pm
Kontakt:

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.
Java 4 Life :twisted:

API Java
GUI
Server Mock

ODPOWIEDZ

Wróć do „CLOUD”