REST API 404: Zły URI lub brakujący zasób?

Tworzę interfejs API REST, ale napotkałem problem.

Wydaje się, że przyjętą praktyką w projektowaniu interfejsu API REST jest to, że jeśli żądany zasób nie istnieje, zwracany jest kod 404.

Jednak dla mnie powoduje to niepotrzebną dwuznaczność. HTTP 404 jest tradycyjnie kojarzony ze złym identyfikatorem URI. W efekcie mówimy „Albo trafiłeś we właściwe miejsce, ale ten konkretny zapis nie istnieje lub nie ma takiej lokalizacji w Internecie! Naprawdę nie jestem pewien, który…”

Rozważ następujący identyfikator URI:

http://mywebsite/api/user/13

Jeśli otrzymam 404, czy to dlatego, że Użytkownik 13 nie istnieje? A może dlatego, że mój adres URL powinien być:

http://mywebsite/restapi/user/13

W przeszłości zwracałem właśnie wynik NULL z HTTP 200 OKkodem odpowiedzi, jeśli rekord nie istnieje. To proste i moim zdaniem bardzo czyste, nawet jeśli niekoniecznie jest to akceptowana praktyka. Ale czy jest na to lepszy sposób?

404 to tylko kod odpowiedzi HTTP. Ponadto możesz podać treść odpowiedzi i / lub inne nagłówki z bardziej znaczącym komunikatem o błędzie, który zobaczą programiści.

Użyj, 404jeśli zasób nie istnieje. Nie wracaj 200z pustym ciałem.

Jest to podobne do undefinedpustego ciągu (np. "") W programowaniu. Chociaż są bardzo podobne, na pewno jest różnica.

404oznacza, że ​​nic nie istnieje przy tym URI (jak niezdefiniowana zmienna w programowaniu). Powrót 200z pustym ciałem oznacza, że ​​coś tam istnieje i że coś jest teraz puste (jak pusty ciąg w programowaniu).

404nie oznacza, że ​​był to „zły URI”. Istnieją specjalne kody HTTP przeznaczone do błędów URI (np 414 Request-URI Too Long.).

Jak w większości rzeczy „to zależy”. Ale dla mnie, twoja praktyka nie jest zły i nie jest wbrew specyfikacji HTTP per se . Wyczyśćmy jednak kilka rzeczy.

Po pierwsze, identyfikatory URI powinny być nieprzejrzyste. Nawet jeśli nie są nieprzejrzyste dla ludzi, są nieprzezroczyste dla maszyn. Innymi słowy, różnica pomiędzy http://mywebsite/api/user/13, http://mywebsite/restapi/user/13jest taka sama jak różnica między http://mywebsite/api/user/13i http://mywebsite/api/user/14nie znaczy to samo nie jest taki sam okres. Tak więc 404 byłoby całkowicie odpowiednie http://mywebsite/api/user/14(jeśli nie ma takiego użytkownika), ale niekoniecznie jedyna odpowiednia odpowiedź.

Możesz także zwrócić pustą odpowiedź 200 lub, bardziej precyzyjnie, odpowiedź 204 (bez zawartości). To przekazałoby klientowi coś jeszcze. Oznaczałoby to, że zasób zidentyfikowany przez http://mywebsite/api/user/14nie ma treści lub jest zasadniczo niczym. To znaczy, że nie jest taki zasób. Jednak niekoniecznie oznacza to, że twierdzisz, że jakiś użytkownik trwał w magazynie danych o identyfikatorze 14. To jest twoja prywatna sprawa, a nie klient zgłaszający żądanie. Jeśli więc ma sens modelowanie zasobów w ten sposób, śmiało.

Przekazywanie klientom informacji wiąże się z pewnymi konsekwencjami w zakresie bezpieczeństwa, które ułatwiłyby im odgadnięcie prawdziwych identyfikatorów URI. Zwrócenie 200 za chybienie zamiast 404 może dać klientowi wskazówkę, że przynajmniej http://mywebsite/api/userczęść jest poprawna. Złośliwy klient może po prostu próbować różnych liczb całkowitych. Ale dla mnie złośliwy klient i tak byłby w stanie odgadnąć tę http://mywebsite/api/userczęść. Lepszym rozwiązaniem byłoby użycie UUID. tzn. http://mywebsite/api/user/3dd5b770-79ea-11e1-b0c4-0800200c9a66jest lepszy niż http://mywebsite/api/user/14. W ten sposób możesz użyć swojej techniki zwracania 200, nie zdradzając zbyt wiele.

404 Not Found technicznie oznacza, że obecnie nie uri map do zasobu. W twoim przykładzie interpretuję żądanie, http://mywebsite/api/user/13które zwraca wartość 404, co oznacza, że ​​ten adres URL nigdy nie został zmapowany na zasób. Dla klienta powinien to być koniec rozmowy.

Aby rozwiać wątpliwości w niejednoznaczny sposób, możesz ulepszyć swój interfejs API, podając inne kody odpowiedzi. Załóżmy na przykład, że chcesz zezwolić klientom na wysyłanie żądań GET do adresu URL http://mywebsite/api/user/13, chcesz poinformować, że klienci powinni używać kanonicznego adresu URL http://mywebsite/restapi/user/13. W takim przypadku możesz rozważyć wydanie stałego przekierowania, zwracając 301 Przeniesiono na stałe i podając kanoniczny adres URL w nagłówku lokalizacji odpowiedzi. Mówi to klientowi, że w przypadku przyszłych żądań powinien użyć kanonicznego adresu URL.

Zasadniczo brzmi to tak, jakby odpowiedź mogła zależeć od tego, jak powstaje żądanie.

Jeśli żądany zasób stanowi część identyfikatora URI zgodnie z żądaniem, http://mywebsite/restapi/user/13a użytkownik 13 nie istnieje, wówczas 404 jest prawdopodobnie odpowiedni i intuicyjny, ponieważ identyfikator URI jest reprezentatywny dla nieistniejącego użytkownika / encji / dokumentu / itp. To samo dotyczy bezpieczniejszej techniki przy użyciu GUID http://mywebsite/api/user/3dd5b770-79ea-11e1-b0c4-0800200c9a66i powyższego argumentu api / restapi.

Jeśli jednak żądany identyfikator zasobu został zawarty w nagłówku żądania [dołącz własny przykład] lub rzeczywiście w URI jako parametr, np. http://mywebsite/restapi/user/?UID=13Wtedy URI nadal byłby poprawny (ponieważ koncepcja USER kończy się w http://mywebsite/restapi/user/); i dlatego można oczekiwać, że odpowiedź będzie wynosić 200 (z odpowiednio szczegółowym komunikatem), ponieważ określony użytkownik znany jako 13 nie istnieje, ale identyfikator URI tak. W ten sposób mówimy, że identyfikator URI jest dobry, ale żądanie danych nie zawiera treści.

Osobiście 200 nadal nie czuje się dobrze (chociaż wcześniej twierdziłem, że tak jest). Kod odpowiedzi 200 (bez pełnej odpowiedzi) może spowodować, że problem nie zostanie zbadany, gdy na przykład zostanie wysłany nieprawidłowy identyfikator.

Lepszym rozwiązaniem byłoby wysłanie 204 - No Contentodpowiedzi. Jest to zgodne z opisem w3c * Serwer spełnił żądanie, ale nie musi zwracać ciała-jednostki, i może chcieć zwrócić zaktualizowaną metainformację. * 1 Zamieszanie, moim zdaniem, jest spowodowane wpisem w Wikipedii z informacją 204 Brak treści - Serwer pomyślnie przetworzył żądanie, ale nie zwraca żadnej treści. Zwykle używany jako odpowiedź na pomyślne żądanie usunięcia .Ostatnie zdanie jest wysoce dyskusyjne. Rozważ sytuację bez tego zdania, a rozwiązanie jest łatwe - po prostu wyślij 204, jeśli jednostka nie istnieje. Istnieje nawet argument za zwróceniem 204 zamiast 404, żądanie zostało przetworzone i żadna treść nie została zwrócona! Pamiętaj jednak, że 204 nie pozwalają na treść w treści odpowiedzi

Źródła

http://en.wikipedia.org/wiki/List_of_HTTP_status_codes 1. http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html

To bardzo stary post, ale napotkałem podobny problem i chciałbym podzielić się z wami moimi doświadczeniami.

Buduję architekturę mikrousług z pozostałymi interfejsami API. Mam niektóre usługi GET odpoczynku, zbierają dane z systemu zaplecza na podstawie parametrów żądania.

Postępowałem zgodnie z pozostałymi dokumentami projektowymi API i odesłałem HTTP 404 z doskonałym komunikatem o błędzie JSON do klienta, gdy nie było danych, które pasowałyby do warunków zapytania (na przykład wybrano rekord zero).

Gdy nie było żadnych danych do wysłania z powrotem do klienta, przygotowałem doskonały komunikat JSON z wewnętrznym kodem błędu itp., Aby poinformować klienta o przyczynie „Nie znaleziono”, i został on odesłany z powrotem do klienta z HTTP 404. działa w porządku.

Później utworzyłem klasę spoczynkowego interfejsu API, która jest łatwym pomocnikiem do ukrycia kodu związanego z komunikacją HTTP i korzystałem z tego pomocnika przez cały czas, gdy dzwoniłem do pozostałych interfejsów API z mojego kodu.

ALE musiałem pisać mylący dodatkowy kod tylko dlatego, że HTTP 404 miał dwie różne funkcje:

• prawdziwy HTTP 404, gdy reszta interfejsu API nie jest dostępna w danym adresie URL, jest on generowany przez serwer aplikacji lub serwer WWW, na którym działa reszta aplikacji interfejsu API
• klient również zwraca HTTP 404, gdy nie ma danych w bazie danych w zależności od warunków zapytania.

Ważne: mój moduł obsługi błędów spoczynkowego interfejsu API przechwytuje wszystkie wyjątki pojawiające się w usłudze zaplecza, co oznacza, że ​​w przypadku każdego błędu mój spoczynkowy interfejs API zawsze zwraca doskonały komunikat JSON ze szczegółami komunikatu.

To jest pierwsza wersja metody pomocniczej mojego klienta, która obsługuje dwie różne odpowiedzi HTTP 404:

public static String getSomething(final String uuid) {
    String serviceUrl = getServiceUrl();
    String path = "user/" + , uuid);
    String requestUrl = serviceUrl + path;
    String httpMethod = "GET";

    Response response = client
            .target(serviceUrl)
            .path(path)
            .request(ExtendedMediaType.APPLICATION_UTF8)
            .get();

    if (response.getStatus() == Response.Status.OK.getStatusCode()) {
        // HTTP 200
        return response.readEntity(String.class);
    } else {
        // confusing code comes here just because
        // I need to decide the type of HTTP 404...

        // trying to parse response body
        try {
            String responseBody = response.readEntity(String.class);
            ObjectMapper mapper = new ObjectMapper();
            ErrorInfo errorInfo = mapper.readValue(responseBody, ErrorInfo.class);

            // re-throw the original exception
            throw new MyException(errorInfo);

        } catch (IOException e) {
            // this is a real HTTP 404
            throw new ServiceUnavailableError(response, requestUrl, httpMethod);
        }

    // this exception will never be thrown
    throw new Exception("UNEXPECTED ERRORS, BETTER IF YOU DO NOT SEE IT IN THE LOG");
}

ALE , ponieważ mój klient Java lub JavaScript może odbierać dwa rodzaje HTTP 404, muszę jakoś sprawdzić treść odpowiedzi w przypadku HTTP 404. Jeśli mogę przeanalizować treść odpowiedzi, to jestem pewien, że otrzymałem odpowiedź tam, gdzie była brak danych do odesłania do klienta.

Jeśli nie jestem w stanie przeanalizować odpowiedzi, oznacza to, że odzyskałem prawdziwy HTTP 404 z serwera WWW (nie z pozostałej aplikacji API).

Jest to tak mylące, że aplikacja kliencka musi zawsze wykonać dodatkowe parsowanie, aby sprawdzić prawdziwy powód HTTP 404.

Szczerze mówiąc nie podoba mi się to rozwiązanie. Jest to mylące, musi cały czas dodawać klientom dodatkowe bzdury.

Zamiast więc używać HTTP 404 w tych dwóch różnych scenariuszach, zdecydowałem, że wykonam następujące czynności:

• Nie używam już HTTP 404 jako kodu HTTP odpowiedzi w mojej pozostałej aplikacji.
• Zamierzam użyć HTTP 204 (bez zawartości) zamiast HTTP 404.

W takim przypadku kod klienta może być bardziej elegancki:

public static String getString(final String processId, final String key) {
    String serviceUrl = getServiceUrl();
    String path = String.format("key/%s", key);
    String requestUrl = serviceUrl + path;
    String httpMethod = "GET";

    log(requestUrl);

    Response response = client
            .target(serviceUrl)
            .path(path)
            .request(ExtendedMediaType.APPLICATION_JSON_UTF8)
            .header(CustomHttpHeader.PROCESS_ID, processId)
            .get();

    if (response.getStatus() == Response.Status.OK.getStatusCode()) {
        return response.readEntity(String.class);
    } else {
        String body = response.readEntity(String.class);
        ObjectMapper mapper = new ObjectMapper();
        ErrorInfo errorInfo = mapper.readValue(body, ErrorInfo.class);
        throw new MyException(errorInfo);
    }

    throw new AnyServerError(response, requestUrl, httpMethod);
}

Myślę, że to lepiej radzi sobie z tym problemem.

Jeśli masz jakieś lepsze rozwiązanie, udostępnij je nam.

Ten stary, ale doskonały artykuł… http://www.infoq.com/articles/webber-rest-workflow mówi o tym ...

404 Nie znaleziono - usługa jest zbyt leniwa (lub bezpieczna), aby dać nam prawdziwy powód niepowodzenia naszej prośby, ale bez względu na powód musimy sobie z tym poradzić.

Uniform Resource Identifier to unikalny wskaźnik do zasobu. Źle sformatowany identyfikator URI nie wskazuje zasobu, dlatego wykonanie GET na nim nie zwróci zasobu. 404 oznacza, że ​​serwer nie znalazł niczego pasującego do URI żądania. Jeśli podasz niewłaściwy lub zły identyfikator URI, to jest to twój problem i powód, dla którego nie dotarłeś do zasobu, czy to strony HTML, czy IMG.

W tym scenariuszu HTTP 404 jest kodem odpowiedzi dla interfejsu API REST, takim jak jednostka nieprzetworzona 400, 401, 404, 422

użyj obsługi wyjątków, aby sprawdzić pełny komunikat wyjątku.

try{
  // call the rest api
} catch(RestClientException e) {
     //process exception
     if(e instanceof HttpStatusCodeException){
        String responseText=((HttpStatusCodeException)e).getResponseBodyAsString();
         //now you have the response, construct json from it, and extract the errors
         System.out.println("Exception :" +responseText);
     }

}

Ten blok wyjątków zapewnia właściwy komunikat generowany przez interfejs API REST