REST API — odpowiedzi i błędy
Konfigurację dostępu, adresu i nagłówka z kluczem opisuje Rozpoczęcie pracy.
Sprawdzaj kod HTTP i wynik polecenia
Kod HTTP, na przykład 200 lub 401, opisuje obsługę żądania. Wynik samego polecenia może znajdować się w polu status odpowiedzi JSON, czyli tekstowego formatu danych. Odczytaj także treść odpowiedzi: HTTP 200 może towarzyszyć odrzuceniu polecenia, na przykład invalid_variable albo invalid_scene_num.
Listy i odczyty wartości nie muszą zawierać pola status. Tablica nazw, pusta tablica [] lub obiekt wartości mogą być prawidłowym wynikiem właściwej metody. Brak status sam w sobie nie oznacza błędu.
Typowe sytuacje i postępowanie
| HTTP | Sytuacja | Co zrobić |
|---|---|---|
401 |
Brak klucza, niepoprawny format nagłówka, wyłączone REST API albo nieważny klucz. Zwykle {"error":"invalid_access_token"}. |
Sprawdź potwierdzony stan REST API, aktualny klucz i nagłówek Authorization: Bearer KLUCZ_API. Po wymianie klucza zaktualizuj integrację. |
403 |
Źródłowy adres loopback; odpowiedź {"error":"access_denied"}, także przy poprawnym kluczu. |
Połącz integrację bezpośrednio przez sieć z adresem instalacji. Nie używaj 127.0.0.1 ani ::1. |
400 |
Niepoprawne parametry sceny lub format listy w operacji zbiorczej. | Sprawdź parametry i body właściwej metody. Nie zakładaj, że każdy brak parametru każdej metody daje 400. |
404 |
Nieznany object_id przy odczycie urządzenia. |
Pobierz aktualną listę urządzeń i skopiuj identyfikator dokładnie z jej odpowiedzi. Nie przenoś tej reguły na nieznaną zmienną lub scenę. |
413 |
Body przekracza limit 1 MiB. |
Zmniejsz treść żądania. Przy dzieleniu zapisu zbiorczego na mniejsze żądania uwzględnij brak transakcji. |
500 |
Błąd obsługi lub wymiany z serwerem automatyki. Oczekiwanie na odpowiedź jest ograniczone do około 5 sekund. | Sprawdź dostępność instalacji i treść błędu. Przed powtórzeniem polecenia uwzględnij możliwe wykonanie mimo utraty odpowiedzi. |
308 |
Przy aktywnym HTTPS żądanie HTTP bez włączonego wyjątku HTTP otrzymuje adres docelowy HTTPS. | Użyj adresu HTTPS z nagłówka Location i certyfikatu zaufanego przez klienta. Zasady opcji HTTP opisuje Rozpoczęcie pracy. |
200 z odrzuceniem w status |
Żądanie zostało obsłużone, ale polecenie zwróciło na przykład invalid_variable lub invalid_scene_num. |
Sprawdź nazwę zmiennej lub numer i istnienie sceny. Nie zapisuj takiej odpowiedzi jako sukcesu polecenia. |
Nieznana zmienna przy pojedynczym odczycie zwykle zwraca HTTP 200 ze statusem invalid_variable. Nieistniejąca scena może zwrócić HTTP 200 ze statusem invalid_scene_num. Oba przypadki różnią się od HTTP 404 dla nieznanego urządzenia.
Przykładowe postacie odpowiedzi
Nie ma jednego uniwersalnego formatu błędu. Odpowiedź może zawierać error, pola status i message albo postać właściwą danej metodzie. Poniższe przykłady pokazują pełne body JSON poszczególnych odpowiedzi.
Odrzucony dostęp:
HTTP/1.1 401 Unauthorized
Content-Type: application/json; charset=utf-8
{"error":"invalid_access_token"}
Przykład ogólnej odpowiedzi błędu; status jest tutaj liczbą odpowiadającą kodowi HTTP:
HTTP/1.1 500 Internal Server Error
Content-Type: application/json; charset=utf-8
{"status":500,"message":"Something went wrong"}
Odrzucony odczyt zmiennej mimo HTTP 200; tutaj status jest tekstowym wynikiem operacji:
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{"status":"invalid_variable"}
Przykład odpowiedzi na uruchomienie nieistniejącej sceny:
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{"logic_action":"on_scene","status":"invalid_scene_num"}
Nazwy pól i komunikaty protokołu zachowują swoją postać niezależnie od języka instrukcji. Nie opieraj obsługi wszystkich błędów wyłącznie na jednym polu lub jednym komunikacie.
Timeout, utrata odpowiedzi i ponawianie
Timeout oznacza, że oczekiwanie na odpowiedź przekroczyło limit czasu. Timeout, zerwane połączenie lub utrata odpowiedzi nie dowodzą, że operacja nie została wykonana. Serwer nie ponawia automatycznie wysłanego polecenia.
Odczyt można ponowić ręcznie po usunięciu przyczyny błędu. Przed ponowieniem polecenia zmieniającego stan sprawdź dostępny stan instalacji i rozważ jego skutki:
- Zapis zbiorczy zmiennych nie jest transakcją i nie wycofuje wcześniejszych zmian. Mógł wykonać się częściowo, a błąd może zakończyć całe żądanie bez częściowego wyniku. Limit oczekiwania około 5 sekund dotyczy kompletu odpowiedzi, a nie każdej pozycji osobno.
- Ponowne uruchomienie sceny może powtórzyć działania i odnowić terminy. Utrata odpowiedzi nie daje podstaw do uznania automatycznego ponowienia za bezpieczne.
Wywołania z przeglądarki
API nie udostępnia obsługi CORS dla wywołań z dowolnej strony WWW pod innym adresem. CORS to reguły zezwalające przeglądarce na takie wywołania między adresami. Poprawny klucz nie usuwa tego ograniczenia; publiczny REST nie jest uniwersalnym interfejsem do bezpośredniego wywoływania z obcych stron w przeglądarce.
Wróć do Rozpoczęcia pracy, aby sprawdzić ustawienia dostępu i pierwszy odczyt.