Standardowa odpowiedź RESTful API JSON

Hej!

Uczę się tworzyć proste resty. Znalazłem tego typu odpowiedź na SO, ale z tego co widzę tych standardów jest dosyć sporo. I mam parę pytań:

• Jak wygląda standardowa odpowiedź RESTful API w formie JSON?
• Jakie pola musi zawierać, jakie może zawierać?
• Co zwracać kiedy nie znalazłem resource? Tylko kod 404? Kod 404 i jakąś standardową odpowiedź?
• Co zwrócić po np. poprawnej operacji usunięcia resource? A co po niepoprawnej?
• Czy opcjonalne pola powinny występować, nawet kiedy w konkretnym przypadku ich nie używam?
  Przykład: mam pole flag, które może być puste, czy kiedy jest puste mam zwrócić "flag: empty" lub "flag null"?

1. Zwracasz wymagany content i response status ;)
2. Nie ma czegoś takiego, zwracasz pola które są okreslone w wymaganiach danej funkcjonalności. dla mnie jedynym wyjątkiem jest zwracanie id jako PK przy każdym obiekcie ale to taki mój przyjęty standard i dobra praktyka.
3. Tego pytania nie rozumiem, zazwyczaj jesli wbijasz pod endpoint który nie istnieje to się zwraca automatycznie 404. Jeśli wchodzisz na endpoint który istnieje ale który z jakiś powodów (brak obiektów w bazie/query) nic nie zwraca to zazwyczaj response jest poprawny 200 OK (endpoint dziala i reaguje na request), a w zwrotce zazwyczaj pojawia się pusta lista [ ], chociaż to podejrzewam może się różnic w zależności od frameworka z jakiego korzystasz.
4. 200 OK w drugim przypadku 400 BAD REQUEST
5. To zalezy od kontraktu na API, jeśli przykładowo z api korzysta apka mobila i ona oczekuje key flag to tak lepiej to zwracać nawet kiedy jest Null

Czym jest PK o którym wspomniałeś?
Co do punktu 3: chciałem zapytać czy mam tylko ustawić 'response status' na 404, czy ustawić 'response status' i zwrócić JSONa z np. wartością "status: 404"?
Tak samo z punktem 4 - tylko status czy status + JSON?

Nie, w punkcie 4 ja uwazam że lepiej zwrócić 204 NO_CONTENT -> czyli ok, ale nic nie zwraca. Np. tak masz na Githubie też:
https://developer.github.com/v3/reactions/ (sam dół)

Burdzi0 napisał(a):

• Co zwracać kiedy nie znalazłem resource? Tylko kod 404? Kod 404 i jakąś standardową odpowiedź?

404 wystarczy, no chyba, że biznes wymaga więcej.

• Co zwrócić po np. poprawnej operacji usunięcia resource? A co po niepoprawnej?

Po poprawnej 204, a co do niepoprawnej, to zależy. Jeśli np. dane w żądaniu były niepoprawne, to 400, jeśli zła metoda to 405, a jeśli coś po stronie kodu, to 500.
Ogólnie tu jest fajny artykuł o tym: https://www.codetinkerer.com/2015/12/04/choosing-an-http-status-code.html

• Czy opcjonalne pola powinny występować, nawet kiedy w konkretnym przypadku ich nie używam?
  Przykład: mam pole flag, które może być puste, czy kiedy jest puste mam zwrócić "flag: empty" lub "flag null"?

No ja zwracam, po pierwsze dlatego, że dla mnie struktura żądań i odpowiedzi to kontrakt, a kontrakt jest niezmienny - i tak też zapewne będą go widzieli konsumenci API, a po drugie dlatego, że usuwanie pustych wartości brzmi jak dodatkowa robota.