Konwencja REST URI - pojedyncza lub mnoga nazwa zasobu podczas jego tworzenia

Dla mnie lepiej mieć schemat, który można mapować bezpośrednio do kodu (łatwo zautomatyzować), głównie dlatego, że kod jest tym, co będzie na obu końcach.

GET  /orders          <---> orders 
POST /orders          <---> orders.push(data)
GET  /orders/1        <---> orders[1]
PUT  /orders/1        <---> orders[1] = data
GET  /orders/1/lines  <---> orders[1].lines
POST /orders/1/lines  <---> orders[1].lines.push(data) 

Ja też nie widzę sensu w robieniu tego i uważam, że nie jest to najlepszy projekt URI. Jako użytkownik usługi RESTful spodziewałbym się, że zasób listy będzie miał taką samą nazwę, niezależnie od tego, czy uzyskam dostęp do listy, czy konkretnego zasobu " na " liście. Należy używać tych samych identyfikatorów bez względu na to, czy chcesz użyć zasobu listy, czy określonego zasobu.

Liczba mnoga

• Simple - wszystkie adresy URL zaczynają się od tego samego prefiksu
• logiczne - orders/ dostaje listę zamówień.
• Standard - najczęściej przyjmowany standard, po którym następuje przytłaczająca większość publicznych i prywatnych API.

na przykład:

GET /resources - zwraca listę pozycji zasobów

POST /resources - tworzy jedną lub wiele pozycji zasobów

PUT /resources - aktualizuje jeden lub wiele pozycji zasobów

PATCH /resources - częściowo aktualizuje jedną lub wiele pozycji zasobów

DELETE /resources - usuwa wszystkie elementy zasobów

i dla pojedynczych pozycji zasobów:

GET /resources/:id - zwraca określony element zasobu na podstawie parametru :id

POST /resources/:id - tworzy jeden element zasobu o podanym id (wymaga walidacji)

PUT /resources/:id - aktualizuje konkretny element zasobu

PATCH /resources/:id - częściowo aktualizuje określony element zasobu

DELETE /resources/:id - usuwa określony element zasobu

Do zwolenników liczby pojedynczej, pomyśl o tym w ten sposób: czy poprosisz kogoś o order i oczekujesz jednej rzeczy, lub listy rzeczy? Dlaczego więc oczekujesz, że serwis zwróci listę rzeczy po wpisaniu /order?

Podczas gdy najbardziej rozpowszechnioną praktyką są RESTful API, w których używa się liczby mnogiej, np. /api/resources/123, istnieje jeden szczególny przypadek, w którym użycie nazwy pojedynczej jest bardziej odpowiednie/ekspresyjne niż nazwy mnogie. Tak jest w przypadku relacji jeden do jednego. W szczególności, jeśli element docelowy jest obiektem wartości(w paradygmacie Domain-driven-design).

Załóżmy, że każdy zasób ma jeden do jednego accessLog, który może być modelowany jako obiekt wartości, tzn. nie encja, więc nie ma ID. Można ją wyrazić jako /api/resources/123/accessLog. Zwykłe czasowniki (POST, PUT, DELETE, GET) odpowiednio wyrażają intencję, a także fakt, że związek jest rzeczywiście jeden do jednego.

Liczba pojedyncza

Wygoda Rzeczy mogą mieć nieregularne liczby mnogie. Czasami ich nie ma. Ale pojedyncze imiona zawsze tam są.

Np. CustomerAddress nad Customeradress

Rozważ ten powiązany zasób.

To /order/12/orderdetail/12 jest bardziej czytelne i logiczne niż /orders/12/orderdetails/4.

Tabele Baz Danych

Zasób reprezentuje encję jak tabela bazy danych. Powinna mieć logiczną, pojedynczą nazwę. Oto odpowiedź nad tabelą nazwiska.

Class Mapping

Klasy są zawsze pojedyncze. Narzędzia ORM generują tabele o takich samych nazwach jak nazwy klas. W miarę jak coraz więcej narzędzi jest używanych, pojedyncze nazwy stają się standardem.

Przeczytaj więcej o a REST API Developer ' s Dilemma

Dlaczego nie podążać za powszechnym trendem nazw tabel w bazie danych, gdzie forma pojedyncza jest ogólnie akceptowana? Już to przerabiałem. wykorzystajmy to ponownie.

Dylemat nazewnictwa tabel: liczba pojedyncza a liczba mnoga

Z punktu widzenia konsumenta API, punkty końcowe powinny być przewidywalne, więc

Idealnie...

1. GET /resources powinien zwrócić listę zasobów.
2. GET /resource powinien zwrócić kod statusu poziomu 400.
3. GET /resources/id/{resourceId} powinna zwracać zbiór z jednym zasobem.
4. GET /resource/id/{resourceId} powinien zwrócić obiekt resource.
5. POST /resources powinno wsadowo tworzyć zasoby.
6. POST /resource powinien utworzyć zasób.
7. PUT /resource powinien zaktualizować zasób obiekt.
8. PATCH /resource powinien zaktualizować zasób, publikując tylko zmienione atrybuty.
9. PATCH /resources powinna wsadowo aktualizować zasoby publikując tylko zmienione atrybuty.
10. DELETE /resources powinien usunąć wszystkie zasoby; tylko żart: 400 kod statusu
11. DELETE /resource/id/{resourceId}

Powiedziawszy to wszystko, z jakiegokolwiek powodu najczęściej używaną praktyką deweloperów jest użycie formy liczby mnogiej. To jest ostatecznie trasa, którą wybrałem i jeśli spojrzysz na popularne interfejsy API, takie jak github i twitter, To właśnie one robią.

Niektóre kryteria decydowania mogą be:

Jakie są moje ograniczenia czasowe?
1. na jakie operacje pozwolę moim konsumentom?
2. Jak wygląda żądanie i wynik ładunku?
3. czy chcę móc używać reflection i analizować URI w moim kodzie?

Jestem zaskoczony, widząc, że tak wiele osób wskoczyłoby na rzeczownik liczby mnogiej bandwagon. Czy realizując konwersje liczby pojedynczej na mnogą, dbasz o nieregularne rzeczowniki liczby mnogiej? Lubisz ból?

Zobacz http://web2.uvcs.uvic.ca/elc/studyzone/330/grammar/irrplu.htm

Istnieje wiele rodzajów nieregularnej liczby mnogiej, ale są to najczęściej:

Rodzaj rzeczownika tworzący przykład liczby mnogiej

Kończy się na-Fe Zmień f na v wtedy Add-s knife noże life lives żony żony Kończy się na-F Zmień f na v wtedy Add-es pół połówki wilki wilki bochenki chleba Kończy się na-O Add-es ziemniaki ziemniaki pomidory pomidory wulkany kończy się na-nas Zmień-nas na-i kaktusy Kaktusy jądro jąder focus foci kończy się na-jest zmiana-jest do-es analizy analizy kryzys kryzys prace dyplomowe kończy się na-na zmianę-na-zjawisko zjawiska kryteria Wszystkie rodzaje zmieniają samogłoskę lub Zmień słowo lub Dodaj inne zakończenie man men stopy stopy dzieci dzieci person people ząbki myszki Niezmienne liczby pojedynczej i mnogiej czy te same Owce jeleń ryby (czasami)

Wolę używać formy pojedynczej zarówno dla prostoty, jak i spójności.

Na przykład, biorąc pod uwagę następujący url:

/klient/1

Będę traktował klienta jako kolekcję klienta, ale dla uproszczenia część kolekcji zostanie usunięta.

Inny przykład:

/sprzęt/1

W tym przypadku sprzęt nie jest poprawną formą liczby mnogiej. Tak więc potraktowanie go jako kolekcji sprzętu i usunięcie kolekcji dla uproszczenia sprawia, że jest on spójny z klientem case.

Moje dwa centy: metody, które spędzają czas zmieniając się z liczby mnogiej na liczbę pojedynczą lub viceversa są stratą cykli procesora. Może i jestem staroświecki, ale w moich czasach rzeczy nazywały się tak samo. Jak szukać metod dotyczących ludzi? Żadna regularna ekspresja nie obejmie zarówno osoby, jak i osób bez niepożądanych skutków ubocznych.

Liczby mnogie w języku angielskim mogą być bardzo dowolne i niepotrzebnie obciążają kod. Trzymaj się jednej konwencji nazewnictwa. Języki komputerowe miały być o matematyczna jasność, a nie naśladowanie języka naturalnego.

Z konwencjami nazewnictwa, zwykle można powiedzieć "po prostu wybierz jedną i trzymaj się jej", co ma sens.

Jednak, po wyjaśnieniu REST wielu osobom, reprezentowanie punktów końcowych jakościeżek w systemie plików jest najbardziej wyrazistym sposobem na to.
Jest bezpaństwowy( pliki istnieją lub nie istnieją), hierarchiczny, prosty i znajomy - wiesz już, jak uzyskać dostęp do plików statycznych, czy to lokalnie, czy przez http.

I w tym kontekście reguły językowe można dostać się tylko do następujących:

Katalog może zawierać wiele plików i / lub podkatalogów, dlatego jego nazwa powinna być w liczbie mnogiej.

Ważne jest to, że jeśli umieścisz plik o nazwie "123" w katalogu o nazwie " resourceS" (w wyniku /resourceS/123), nie można oczekiwać, że będzie on dostępny przez /resource/123.

Nie staraj się uczynić go mądrzejszym niż musi być - zmiana z liczby mnogiej na pojedynczą w zależności od liczby zasobów, do których obecnie uzyskujesz dostęp, może być dla niektórych estetyczna, ale nie jest skuteczna i nie ma sensu w hierarchicznym systemie .

Uwaga: technicznie, można tworzyć "dowiązania symboliczne" , tak aby /resources/123 można było również uzyskać poprzez /resource/123, ale to pierwsze nadal musi exist!

Wiem, że większość ludzi decyduje, czy używać liczby mnogiej czy pojedynczej. Problem, który nie został tutaj rozwiązany, polega na tym, że klient będzie musiał wiedzieć, którego z nich używasz i zawsze może popełnić błąd. Stąd pochodzi moja sugestia.

A może jedno i drugie? I przez to mam na myśli używanie liczby pojedynczej dla całego API, a następnie tworzenie tras do przekazywania żądań w liczbie mnogiej do liczby pojedynczej. Na przykład:

GET  /resources     =     GET  /resource
GET  /resources/1   =     GET  /resource/1
POST /resources/1   =     POST /resource/1
...

Dostajesz zdjęcie. Nikt się nie myli, minimalny wysiłek, a klient zawsze będzie miał rację.

Używanie liczby mnogiej dla wszystkich metod jest bardziej praktyczne przynajmniej w jednym aspekcie: jeśli tworzysz i testujesz API zasobów za pomocą Postmana (lub podobnego narzędzia), nie musisz edytować URI podczas przełączania z GET do PUT do POST itp.

Obie reprezentacje są użyteczne. Używałem singular dla wygody od dłuższego czasu, przegięcie może być trudne. Moje doświadczenie w tworzeniu ściśle pojedynczych interfejsów API REST, deweloperzy zużywający punkt końcowy nie mają pewności, jaki może być kształt wyniku. Teraz wolę używać terminu, który najlepiej opisuje kształt odpowiedzi.

Jeśli wszystkie twoje zasoby są na najwyższym poziomie, możesz ujść na sucho z pojedynczymi reprezentacjami. Unikanie przegięcia jest dużym wygraj.

Jeśli robisz jakieś głębokie linkowanie, aby reprezentować zapytania dotyczące relacji, wtedy deweloperzy piszący przeciwko twojemu API mogą być wspomagani przez bardziej rygorystyczną konwencję.

Moja konwencja jest taka, że każdy poziom głębi w URI opisuje interakcję z zasobem macierzystym, a pełny URI powinien domyślnie opisywać to, co jest pobierane.

Załóżmy, że mamy następujący model.

interface User {
    <string>id;
    <Friend[]>friends;
    <Manager>user;
}

interface Friend {
    <string>id;
    <User>user;
    ...<<friendship specific props>>
}

Gdybym potrzebował dostarczyć zasób, który pozwoli klientowi w tym celu należy skontaktować się z menedżerem danego znajomego konkretnego użytkownika, może to wyglądać mniej więcej tak:

GET /users/{id}/friends/{friendId}/manager

Oto kilka przykładów:

• GET /users - lista zasobów użytkownika w globalnej kolekcji użytkowników
• POST /users - Utwórz nowego Użytkownika w globalnej kolekcji użytkowników
• GET /users/{id} - pobranie konkretnego użytkownika z globalnej kolekcji użytkowników
• GET /users/{id}/manager - Pobierz menedżera konkretnego użytkownika
• GET /users/{id}/friends - Pobierz listę znajomych z użytkownik
• GET /users/{id}/friends/{friendId} - znajdź konkretnego znajomego użytkownika
• LINK /users/{id}/friends - Dodaj znajomego do tego użytkownika
• UNLINK /users/{id}/friends - Usuń skojarzenie znajomych z tego użytkownika

Zwróć uwagę, jak każdy poziom mapuje się do rodzica, który może działać. Używanie różnych rodziców dla tego samego obiektu jest sprzeczne z intuicją. Pobranie zasobu w {[10] } nie pozostawia wskazówek, że tworzenie nowego zasobu powinno odbywać się w POST /resources

A może:

/resource/ (nie /resource)

/resource/ oznacza to, że jest to folder zawierający coś o nazwie "zasób", jest to folder "resouce".

A także myślę, że konwencja nazewnictwa tabel baz danych jest taka sama, na przykład tabela o nazwie 'user' jest "tabelą użytkownika", zawiera coś o nazwie"user".

Dla mnie liczby mnogie manipulują zbiorem , podczas gdy liczby mnogie manipulują elementem wewnątrz tego zbioru.

Zbiór pozwala na metody GET / POST / DELETE

Item pozwala na metody GET / PUT / DELETE

Na przykład

POST on / students doda nowego ucznia w szkole.

DELETE on / students usunie wszystkich uczniów w szkole.

DELETE on /student/123 usunie studenta 123 ze szkoły.

Aby jeszcze bardziej rozszerzyć przykład, jeśli API miało ujawniać wiele szkół, to coś w stylu

DELETE on / school / abc / students will remove wszystkich uczniów w szkole abc.

Wybór odpowiedniego słowa Czasami jest wyzwaniem samym w sobie, ale lubię zachować mnogość dla zbioru. Np. cart_items lub cart/items wydaje się właściwe. W przeciwieństwie do usuwania cart, usuwa sam obiekt koszyka, a nie elementy w Koszyku ;).

Wolę używać zarówno liczby mnogiej (/resources), jak i pojedynczej (/resource/{id}), ponieważ myślę, że to wyraźniej oddziela logikę między pracą nad zbiorem zasobów i pracą nad jednym zasobem.

Jako ważny efekt uboczny może również pomóc zapobiec niewłaściwemu użyciu API. Na przykład, rozważ przypadek, w którym użytkownik błędnie próbuje uzyskać zasób, podając Id jako parametr taki jak:

GET /resources?Id=123

W tym przypadku, gdzie używamy wersji mnogiej, serwer najprawdopodobniej zignoruje parametr Id i zwróci listę wszystkich zasobów. Jeśli użytkownik nie będzie ostrożny, pomyśli, że połączenie się powiodło i użyje pierwszego zasobu na liście.

Z drugiej strony, przy użyciu formy liczby pojedynczej:

GET /resource?Id=123

Serwer najprawdopodobniej zwróci błąd, ponieważ identyfikator nie jest podany we właściwy sposób, a użytkownik będzie musiał zdać sobie sprawę, że coś jest nie tak.