Handling różnicy między reprezentacją struktury relaksującego POST i GET

Question

Jestem projektowania REST API i mimo trałowania szereg przewodników najlepszych praktyk nie mogę znaleźć wiele dotycząca najlepszych praktyk obsługiwać rozbieżności między strukturą reprezentacji potrzebne dla POST w stosunku do tej samej struktury reprezentacji zwróconej z GET.

GET dla manekina user reprezentacji może wyglądać następująco:

{ 
    "id": 1234, 
    "created": "2012-04-23T18:25:43.511Z", 
    "username": "johndoe@example.com", 
    "name": "John Doe" 
} 

Jednak POST dla tego samego manekina user reprezentacji nie można określić pewne właściwości (czyli id i created)

{ 
    "username": "johndoe@example.com", 
    "name": "John Doe" 
} 

Oczywiście jest to zbyt uproszczony przykład, ale biorąc pod uwagę, że użytkownik nie może określić niektórych pól (i może nie zawsze czy są oczywiste, które z nich są istotne dla zastosowanej metody) czy jest to najlepsza praktyka, aby uzyskać oddzielne reprezentacje dla każdego lub oczekiwać najbardziej kompletnej wersji i obsługiwać dysparytet danych w sposób przezroczysty na serwerze?

Pomimo pozornej łatwości posiadania pojedynczej reprezentacji i obsługi strony serwera różnicowego obawiam się, że byłoby to złe doświadczenie dla użytkownika, gdyby nie było jasne, które wartości można określić (lub zmienić przy użyciu na przykład PUT). Jeśli tendencja polega na tworzeniu oddzielnych reprezentacji, czy istnieje konwencja nazewnictwa, którą należy zastosować do definicji reprezentacji?

np. i_user dla użytkownika przychodzącego i o_user dla użytkownika wychodzącego. Lub user_full i user_min lub user i .user itp

Aktualizacja: Moja nadmiernie uproszczonym przykładem może nie właściwie zilustrować problem. Wyobraź sobie reprezentację, która ma 50 właściwości (na przykład reprezentację serwera ze wszystkimi jego atrybutami monitorującymi - CPU, RAM, Temp, Storage_drive_a, Storage_drive_b, File_permission itd.) Z tych 50 właściwości, 30 to tylko właściwości do odczytu, a 20 z nich to wartości, które może być ustawiony.

Answer 1

Po pierwsze, ostateczna semantyka metody POST jest określana przez zasób celowany, a nie przez protokół HTTP, tak jak w przypadku innych metod, więc twoja metoda POST może zrobić wszystko, co chcesz, o ile ją dokumentujesz poprawnie, a ty nie powielasz funkcjonalności już znormalizowanej innymi metodami.

Krótko mówiąc, nie ma nic złego w posiadaniu innej reprezentacji dla metody POST i GET.

Jednak prośba o najlepszą praktykę w tym przypadku jest bezcelowa, ponieważ to, co definiuje format reprezentacji, to rodzaj mediów, a nie metoda, ale większość tak zwanych interfejsów REST API w Internecie używa generycznych typy mediów dla wszystkiego i klienci polegają na semantyzie URI, aby wiedzieć, z którym zasobem mają do czynienia, co nie jest w ogóle UŻYWANE. Zasadniczo, pytasz o najlepszą praktykę dla problemu, który tak naprawdę nie istnieje w REST, kiedy wszystko jest zrobione poprawnie.

Aby odpowiedzieć na Twoje pytanie, możesz mieć różne reprezentacje z różnymi typami mediów - np. Twoja pełna reprezentacja użytkowników może mieć typ mediów: application/vnd.mycompany.user.full.v1+json, a uproszczona reprezentacja użytkownika może mieć typ mediów: application/vnd.mycompany.user.min.v1+json - lub możesz mieć pojedynczą reprezentację, taką jak application/vnd.mycompany.user.v1+json, a twoja dokumentacja dla tego typu mediów może zawierać informacje o tym, jak niektóre właściwości mogą istnieć lub nie, lub może mieć wartości domyślne, jeśli nie zostały dostarczone. Twoja metoda POST będzie wymagać jednego typu mediów do pracy i odpowie z 415 Unsupported Media Type, jeśli klienci wyślą coś innego w nagłówku Content-Type. W ten sam sposób klient może wybrać żądaną reprezentację za pomocą nagłówka Accept.

Jak widać, to, o co prosisz, nie stanowi problemu, gdy naprawdę robisz REST, a nie tylko używasz go jako modnego hasła do API HTTP.