Jak utworzyć REST URL bez czasowników?

Ogólne zasady dobrego projektowania URI:

• Nie używaj parametrów zapytania do zmiany stanu
• nie używaj ścieżek mieszanych, jeśli możesz pomóc; najlepiej jest stosować małe litery
• nie używaj rozszerzeń specyficznych dla implementacji w swoim Uri (.php,. py,. pl, itp.)
• nie wpadaj w RPC Z Twoim Uri
• czy ogranicz przestrzeń URI tak bardzo, jak to możliwe
• do keep path segmenty krótkie
• Do preferuj /resource LUB /resource/; Utwórz 301 przekierowań z tego, którego nie używasz
• W tym celu należy użyć parametrów kwerendy do podwyboru zasobu, np. paginacji, zapytań wyszukiwania [26]}
• Jeśli chcesz dowiedzieć się więcej o plikach cookie, skontaktuj się z nami.]}

(uwaga: nie powiedziałem "RESTful Uri design"; URI są zasadniczo nieprzezroczyste w spoczynku.)

Ogólne zasady metody HTTP wybór:

• Nie używaj GET, aby zmienić stan; jest to świetny sposób, aby Googlebot zrujnował ci dzień]}
• nie używaj PUT, chyba że aktualizujesz cały zasób
• Nie używaj PUT, chyba że możesz również legalnie zrobić GET na tym samym URI
• nie używaj postu do pobierania informacji, które są długotrwałe lub które mogą być uzasadnione do buforowania
• nie wykonuj operacji, która nie jest idempotent Z PUT
• Do użyj GET jak najwięcej
• Do use POST in preference to PUT when in doubt
• do użyj posta, gdy musisz zrobić coś, co przypomina RPC
• Do użyj PUT dla klas zasobów, które są większe lub hierarchiczne
• Do use DELETE in preference to POST to remove resources
• Do użyj GET do obliczeń, chyba że Twój wkład jest duży, w takim przypadku użyj POST

Ogólne zasady projektowania serwisów WWW z HTTP:

• Nie umieszczaj metadanych w treści odpowiedzi, która powinna znajdować się w nagłówku.]}
• nie umieszczaj metadanych w oddzielnym zasobie, chyba że włączenie go stworzy znaczne obciążenie
• Do użyj odpowiedniego kodu statusu
  • 201 Created Po utworzeniu zasobu; zasób musi istnieć w czas wysłania odpowiedzi
  • 202 Accepted Po pomyślnym wykonaniu operacji lub utworzeniu zasobu asynchronicznie
  • 400 Bad Request Gdy ktoś wykonuje operację na danych, które są wyraźnie fałszywe; dla Twojej aplikacji może to być błąd walidacji; generalnie zastrzegaj 500 dla nieobciążonych WYJĄTKÓW
  • 401 Unauthorized Gdy ktoś uzyskuje dostęp do twojego API bez podania niezbędnego nagłówka Authorization lub gdy poświadczenia w Authorization są nieprawidłowe; Nie używaj tego kodu odpowiedzi, jeśli nie oczekują poświadczeń za pomocą nagłówka Authorization.
  • Kiedy ktoś uzyskuje dostęp do twojego API w sposób, który może być złośliwy lub jeśli nie jest autoryzowany]}
  • 405 Method Not Allowed gdy ktoś używa postu, kiedy powinien był użyć PUT, itp
  • 413 Request Entity Too Large gdy ktoś próbuje wysłać Ci niedopuszczalnie duży plik
  • 418 I'm a teapot przy próbie zaparzenia kawy czajnikiem [39]}
• Do użyj buforowania nagłówków, gdy tylko can
  • ETag nagłówki są dobre, gdy można łatwo zredukować zasób do wartości hash
  • W związku z tym, że zasoby są aktualizowane w czasie rzeczywistym, nie należy ich aktualizować.]}
  • Cache-Control i Expires Należy podać sensowne wartości
• zrób wszystko, co możesz, aby uhonorować buforowanie nagłówków w żądaniu (If-None-Modified, If-Modified-Since)
• czy używaj przekierowań, gdy mają sens, ale powinny być rzadkie w sieci serwis

W odniesieniu do twojego konkretnego pytania, POST powinien być użyty dla #4 i # 5. Operacje te podlegają powyższej wytycznej "RPC-like". W przypadku #5 pamiętaj, że POST niekoniecznie musi używać Content-Type: application/x-www-form-urlencoded. Może to być równie łatwo ładunek JSON lub CSV.

Gdy wygląda na to, że potrzebujesz nowego czasownika, pomyśl o przekształceniu tego czasownika w rzeczownik. Na przykład zmień "Aktywuj" na "aktywacja", a "zweryfikuj" na "Walidacja".

Ale z tego co napisałeś, powiedziałbym, że Twoja aplikacja ma znacznie większe problemy.

Za każdym razem, gdy zasób o nazwie "parametr" jest proponowany, powinien wysyłać czerwone flagi w myślach każdego członka zespołu projektowego. "parametr" może dosłownie odnosić się do każdego Zasobu; nie jest wystarczająco szczegółowy.

Co czy dokładnie "parametr" reprezentuje? Prawdopodobnie wiele różnych rzeczy, z których każda powinna mieć dedykowany osobny zasób.

Inny sposób na to-kiedy omawiasz swoją aplikację z użytkownikami końcowymi (ci, którzy prawdopodobnie niewiele wiedzą o programowaniu), jakich słów używają wielokrotnie?

Oto słowa, wokół których powinieneś projektować swoją aplikację.

Jeśli nie miałeś jeszcze tej konwersji z potencjalnymi użytkownikami-zatrzymaj wszystko w tej chwili i nie pisz kolejnej linijki kodu, dopóki tego nie zrobisz! Tylko wtedy twój zespół będzie miał pojęcie o tym, co należy zbudować.

Nie wiem nic o oprogramowaniu finansowym, ale gdybym miał zgadywać, powiedziałbym, że niektóre zasoby mogą nosić nazwy takie jak" raport"," Płatność"," Przelew "i"waluta".

Istnieje wiele dobrych książek na temat tej części procesu projektowania oprogramowania. Dwa, które mogę polecić to Domain Driven Design i Analiza Wzory .

Projektowanie adresów URL nie ma nic wspólnego z tym, czy aplikacja jest RESTful, czy nie. Wyrażenie "RESTful URL" jest więc nonsensem.

To powiedziawszy, przejdźmy do twojego pytania: ostatnie dwa przypadki nie są Spokojne i nie pasują do żadnego rodzaju spokojnego planu. To jest to, co można nazwać RPC. Jeśli poważnie myślisz o odpoczynku, będziesz musiał przemyśleć, jak działa Twoja aplikacja od podstaw. Albo To, albo porzuć odpoczynek i po prostu zrób swoją aplikację jako aplikację RPC.

Chodzi o to, że musisz traktować wszystko jako zasób, więc gdy zestaw parametrów ma adres URL, z którego możesz się do niego odwoływać, po prostu dodaj:

GET [parametersurl]/validationresults

POST [paramatersurl]
body: {command:"activate"}

Ale znowu to aktywacja to RPC, a nie Odpoczywaj.

Wymagania aktywacji i walidacji to sytuacje, w których próbujesz zmienić stan zasobu. Nie inaczej jest w przypadku złożenia zamówienia "zrealizowanego", czy też innego żądania "złożonego". Istnieje wiele sposobów modelowania tego rodzaju zmian stanu, ale jednym z nich, który uważam, że często działa, jest tworzenie zasobów kolekcji dla zasobów tego samego stanu, a następnie przenoszenie zasobów między zbiorami, aby wpłynąć na stan.

Np. stworzyć pewne zasoby, takie as,

/ActiveParameters
/ValidatedParameters

Jeśli chcesz uaktywnić zestaw parametrów, dodaj ten zestaw do kolekcji ActiveParameters. Możesz albo Przekazać zestaw parametrów jako ciało encji, albo możesz przekazać adres url jako parametr zapytania, w następujący sposób:

POST /ActiveParameters?parameter=/Parameters/{Id}

To samo można zrobić z / ValidatedParameters. Jeżeli parametry NIE są poprawne, wtedy serwer może zwrócić" Bad Request " do żądania, aby dodać parametry do zbioru zweryfikowanych parametrów.

Sugerowałbym następujące zasoby Meta i metody.

Uaktywnić parametry i / lub zweryfikować je:

> PUT /parameters/<id>/meta HTTP/1.1
> Host: example.com
> Content-Type: application/json
> Connection: close
>
> {'active': true, 'require-valid': true}
>
< HTTP/1.1 200 OK
< Connection: close
<

Sprawdź, czy parametry są aktywne i ważne:

> GET /parameters/<id>/meta HTTP/1.1
> Host: example.com
> Connection: close
>
< HTTP/1.1 200 OK
< Content-Type: application/json
< Connection: close
<
< {
<     'active': true,
<     'require-valid': true,
<     'valid': {'status': false, 'reason': '...'}
< }
<

Trochę mi smutno, gdy widzę, że po ponad 10 latach nie ma odpowiedzi na pytanie, w jaki sposób można zaprojektować coś takiego, o co wnioskowano w OP, w architekturze odpoczynku, stąd czuję potrzebę zrobienia tego teraz.

REST jest w zasadzie uogólnieniem przeglądarki internetowej, którą wszyscy znamy, choć dotyczy WSZYSTKICH rodzajów aplikacji, a nie tylko przeglądarek. Dlatego te same pojęcia, które odnoszą się do sieci, odnoszą się również do architektury REST. Pytanie jak osiągnąć coś w "spokojny" sposób rozwiązuje się wokół odpowiedzi na pytanie, jak osiągnąć coś na stronie internetowej, a następnie zastosować te same pojęcia na warstwie aplikacji.

Kalkulator internetowy może Zwykle zaczynać się od jakiejś "strony", która pozwala wprowadzić pewne wartości do obliczenia przed wysłaniem wprowadzonych danych na serwer. W HTML jest to zwykle osiągane za pomocą elementów HTML <form>, które uczą Klienta o dostępnych parametrach do Ustawienia, docelowej lokalizacji do wysłania żądania jak również format reprezentacji, który należy zastosować przy wysyłaniu danych wejściowych. Może to tzn. wyglądać tak:

<html>
  <head>
    ...
  </head>
  <body>
    <form action="/../someResource" method="post" enctype="application/x-www-form-urlencoded">
      <label for="firstNumber">First number:</label>
      <input type="number" id="firstNumber" name="firstNumber"/>

      <label for="secondNumber">Second number:</label>
      <input type="number" id="secondNumber" name="secondNumber"/>

      <input type="submit" value="Add numbers"/>
    </form>
  </body>
</html>

Powyższa próbka stwierdza, że istnieją dwa pola wejściowe, które mogą być wypełnione przez użytkownika lub przez inny automat, i że po wywołaniu elementu wejściowego submit przeglądarka zajmuje się formatowaniem danych wejściowych do formatu application/x-www-form-urlencoded reprezentacji, który jest wysyłany do wspomnianej lokalizacji docelowej za pomocą określonej metody HTTP request, POST w tym przypadku. Jeśli wpisujemy 1 do pola wejściowego firstNumber i 2 do pola wejściowego secondNumber, przeglądarka wygeneruje reprezentację firstNumber=1&secondNumber=2 i wyśle ją jako ładunek ciała rzeczywistego żądania do zasobu docelowego.

Surowe żądanie HTTP wysyłane do serwera może więc wyglądać tak:

POST /../someResource
Host: www.acme.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 28
Accept: application/html

firstNumber=1&secondNumber=2

Serwer może wykonać obliczenia i odpowiedzieć kolejną stroną HTML zawierającą wynik obliczeń, ponieważ żądanie wskazywało, że klient to rozumie format.

Jak Breton już zauważył, nie ma czegoś takiego jak "RESTful" URL lub URI. URI / URL jest czymś własnym i nie powinien przekazywać żadnego znaczenia klientowi / użytkownikowi. W powyższym przykładzie kalkulatora użytkownik po prostu nie jest zainteresowany, gdzie wysłać dane do niego, jest tylko zainteresowany tym, że po uruchomieniu pola Wyślij zapytanie jest wysyłane. Wszystkie wymagane informacje potrzebne do wykonania zadania powinny być już podane przez serwer.

Przeglądarka też może nie należy pamiętać, że żądanie jest rzeczywiście karmienie kalkulatora z niektórych parametrów wejściowych, może to być również jakiś rodzaj formularza zamówienia, który zwraca tylko następną reprezentację formularza, aby kontynuować proces zamawiania lub jakiś zupełnie inny rodzaj zasobu. Po prostu wykonuje to, czego wymaga Specyfikacja HTML w takim przypadku i nie obchodzi go, co serwer faktycznie robi. Koncepcja ta umożliwia przeglądarce korzystanie z tego samego formatu reprezentacji do robienia wszelkiego rodzaju rzeczy, takich jak zamawianie niektórych rzeczy z preferowanego sklepu internetowego, rozmowy z najlepszymi przyjaciółmi, logowanie na konto online i tak dalej.

Wartość pewnych elementów, na przykład w polu submit, które jest zwykle renderowane jako przycisk, określa, co należy z nim zrobić. W przypadku przycisku lub linku w zasadzie mówi, aby go kliknąć. Inne elementy mogą przenosić różne ceny. Można to również wyrazić za pomocą relacji link-relations , jak np. z preload adnotowane linki, które w zasadzie mówią klientowi, że może już załadować zawartość połączonego zasobu w tle, ponieważ użytkownik najprawdopodobniej pobierze tę zawartość następnie. Takie relacje linków powinny być oczywiście ustandaryzowane lub zgodne z mechanizmem rozszerzenia dla typów relacji zdefiniowanym przez Web linking .

Są to podstawowe pojęcia, które są używane w sieci i które powinny być również stosowane w architekturze REST. Według "wujka Boba" Roberta C. Martina an w architekturze chodzi o intencję, a intencją stojącą za architekturą REST jest oddzielenie klientów od serwerów, aby umożliwić serwerom swobodną ewolucję w przyszłości bez obawy, że będą łamać klientów. To niestety wymaga dużej dyscypliny, ponieważ tak łatwo jest wprowadzić sprzężenie lub dodać rozwiązania quick-fix, aby wykonać zadanie i ruszyć dalej. Jak zauważył Jim Webber w architekturze REST, Ty, jako dostawca usług, powinieneś spróbować zaprojektować aplikację domenową protokół podobny do tekstowej gry komputerowej z Lat 70. , którą klienci będą przestrzegać, dopóki nie osiągną końca procesu.

To, co wiele tak zwanych API "odpoczynku" robi niestety w rzeczywistości, to wszystko poza tym. Widzisz wymianę głównie danych opartych na JSON, która jest określona w dokumentacji zewnętrznej specyficznej dla API, która zwykle jest trudna do dynamicznej integracji w locie. Format, jak żądanie musi wyglądać, jest również zakodowany na twardo w zewnętrznym dokumentacja, która prowadzi do wielu implementacji interpretujących Uri do zwraca predefiniowane typy zamiast używania wspólnego formatu reprezentacji, który jest negocjowany z góry. Zapobiega to zmianie serwerów, ponieważ klienci oczekują, że otrzymają określony format danych (Uwaga Nie format reprezentacji!) dla predefiniowanych Uri. Ta niestandardowa wymiana formatów danych ponadto uniemożliwia klientom interakcję z innymi interfejsami API, ponieważ" format danych " jest zwykle przypływem do określonego API. Wiemy o tym koncepcja z przeszłości z technologii RPC, takich jak Corba, RMI lub SOAP, które potępiamy jako jakoś złe, mimo że Peppol przeniósł się do niego ponownie zastępując AS2 z AS4 jako domyślny protokół transferu od niedawna.

W odniesieniu do zadanego pytania, wysyłanie danych jako pliku csv nie różni się niczym od używania reprezentacji application/x-www-form-urlencoded lub podobnych rzeczy. Jim Webber wyjaśnił, że w końcu HTTP jest tylko protokołem transportowym, którego domeną aplikacji jest transfer dokumentów przez sieć . Klient i serwer powinni przynajmniej wspierać {[13] } zgodnie z definicją w RFC 7111 . Ten plik CSV może być wygenerowany w wyniku przetwarzania typu nośnika, który definiuje elementy formularza, element docelowy lub atrybut do wysłania żądania, a także metodę HTTP do wykonania przesłania konfiguracji.

Istnieje kilka typów nośników, które obsługują formularze, takie jak HTML, HAL Forms, halform, ion lub Hydra . Obecnie nie jestem jednak świadomy typu nośnika, który automatycznie może kodować dane wejściowe bezpośrednio do text/csv, dlatego może być konieczne zdefiniowanie i zarejestrowanie w rejestru typu nośnika IANA.

Przesyłanie i pobieranie kompletnego zestawu parametrów nie powinno być problemem. Jak wspomniano wcześniej, docelowy URI nie ma znaczenia, ponieważ klient po prostu użyje URI do pobrania nowej zawartości do przetworzenia. Filtrowanie według daty biznesowej również nie powinno bądź trudny. Tutaj serwer powinien jednak klient ze wszystkimi możliwościami, które klient po prostu może wybrać. W ostatnich latach rozwinęły się GraphQL i RestQL, które wprowadzają język podobny do SQL, który może być ukierunkowany na określony punkt końcowy, aby uzyskać filtrowaną odpowiedź. Jednak w prawdziwym sensie REST narusza to ideę REST jako a) GraphQL tzn. używa tylko jednego punktu końcowego, który w jakiś sposób uniemożliwia optymalne wykorzystanie buforowania i B) wymaga znajomości dostępnych pól upfrong, które może prowadzić do wprowadzenia sprzężenia klientów z bazowym modelem danych zasobu.

Aktywacja lub dezaktywacja pewnych parametrów konfiguracyjnych jest po prostu kwestią wyzwalania kontrolek hypermedia, które zapewniają tę dostępność. W formularzach HTML może to być proste pole wyboru lub wybór wielowierszowy na liście lub tego rodzaju. W zależności od formy i metody, którą definiuje, może następnie potencjalnie wysłać całą konfigurację za pomocą PUT lub być inteligentnym o dokonanych zmianach i wykonaj tylko częściową aktualizację za pomocą PATCH. Ta ostatnia wymaga zasadniczo obliczenia reprezentacji zmian do zaktualizowanej i podania serwera wymaganymi krokami, aby przekształcić bieżącą reprezentację w pożądaną. Zgodnie ze specyfikacją ścieżki należy to zrobić w ramach transakcji, aby zastosować wszystkie lub żaden z kroków.

HTTP pozwala i zachęca serwer do walidacji otrzymanego żądania z góry przed zastosowaniem zmiany. Dla umieścić spec stwierdza:

Serwer origin powinien sprawdzić, czy reprezentacja PUT jest zgodne z wszelkimi ograniczeniami jakie serwer ma dla celu zasób, który nie może lub nie zostanie zmieniony przez PUT. To jest szczególnie ważne, gdy serwer origin wykorzystuje wewnętrzne informacje konfiguracyjne związane z URI w celu ustawienia wartości metadanych reprezentacji odpowiedzi GET. Kiedy PUT reprezentacyjne niespójne z zasobem docelowym, pochodzenie serwer powinien albo uczynić je spójnymi, przekształcając reprezentacja lub zmiana konfiguracji zasobu, lub odpowiedź z odpowiednim komunikatem o błędzie zawierającym wystarczające informacje aby wyjaśnić, dlaczego reprezentacja jest nieodpowiednia. 409 (Konflikt) lub sugerowane są kody stanu 415 (nieobsługiwany typ nośnika), z ten ostatni jest specyficzny dla ograniczeń dotyczących wartości typu Content.

Dla przykład, jeśli zasób docelowy jest skonfigurowany tak, aby zawsze miał Content-Typ "text / html" i umieszczana reprezentacja ma Zawartość-Typ "image / jpeg", serwer origin powinien wykonać jeden z:

W tym celu należy skonfigurować odpowiedni zasób, aby odzwierciedlał nowy typ nośnika.]}

B. przekształć reprezentację PUT do formatu zgodnego z tym zasobu przed zapisaniem go jako nowego stanu zasobu; or,

C. Odrzuć wniosek za pomocą 415 (nieobsługiwany typ nośnika) odpowiedź wskazanie, że zasób docelowy jest ograniczony do " text / html", być może w tym link do innego zasobu, który byłby odpowiedni cel dla nowej reprezentacji.

HTTP nie definiuje dokładnie jak metoda PUT wpływa na stan serwer origin poza tym, co może być wyrażone przez intencję użytkownika żądanie agenta i semantyka odpowiedzi serwera źródłowego. ...

Do sumy w tym poście powinieneś użyć istniejącego typu nośnika, który pozwala nauczyć Klienta o wymaganych lub obsługiwanych parametrach wejściowych, lokalizacji docelowej do wysłania żądania, operacji do użycia, a także rodzaju nośnika, w którym żądanie ma być sformatowane, lub zdefiniować swój własny, który rejestrujesz w IANA. Ta ostatnia może być konieczna, jeśli chcesz przekonwertować dane wejściowe na text/csv, a następnie przesłać reprezentację CSV na serwer. Walidacja powinna nastąpić przed zmianami są stosowane do zasobu. Rzeczywisty URI nie powinien mieć znaczenia dla klientów innych niż określenie, gdzie wysłać żądanie i jako takie może być dowolnie wybrany przez Ciebie, realizatora usługi. Wykonując te kroki, zyskujesz swobodę zmiany strony serwera w dowolnym momencie, a klienci nie pękną w konsekwencji, jeśli obsługują używane typy multimediów.

Edit: rzeczywiście URI uniemożliwiłoby GET żądania pozostałym idempotentnym.

Do walidacji jednak użycie kodów statusu HTTP do powiadamiania o ważności żądania (aby utworzyć nowy lub zmodyfikować istniejący "parametr") pasowałoby do modelu Restful.

Zgłoś z powrotem kod statusu 400 Bad Request, jeśli przesłane dane są / są nieprawidłowe, A żądanie musi zostać zmienione przed ponownym wysłaniem (HTTP / 1.1 kody statusu ).

To polega na Walidacja w czasie składania wniosku, a nie odroczenie go, jak w Twoim przypadku użycia. Pozostałe odpowiedzi mają odpowiednie rozwiązania dla tego scenariusza.

W środowisku REST każdy adres URL jest unikalnym zasobem. Jakie są Twoje zasoby? Kalkulator finansowy naprawdę nie ma żadnych oczywistych zasobów. Musisz zagłębić się w to, co nazywasz parametrami i wyciągnąć zasoby. Na przykład kalendarz amortyzacji kredytu może być zasobem. Adres URL kalendarza może obejmować datę rozpoczęcia, okres (w miesiącach lub latach), okres (gdy odsetki są kumulowane), stopę procentową i zasadę początkową. Z tymi wszystkimi wartościami, masz szczegółowy kalendarz płatności:

http://example.com/amort_cal/2009-10-20/30yrsfixed/monthly/5.00/200000