Zrozumiałe jest, że jestem trochę zdezorientowany, jak prawidłowo używać REST w oparciu o wszystkie sposoby, w jakie widziałem, jak duże firmy projektują swoje API REST.
Masz rację, ponieważ REST to system gromadzenia zasobów. Oznacza Reprezentatywne przekazanie państwa. Niezbyt dobra definicja, jeśli mnie o to poprosisz. Ale głównymi pojęciami są 4 VERB HTTP i bycie bezpaństwowcami.
Ważną rzeczą do zapamiętania jest to, że masz tylko 4 CZASOWNIKI z RESZTĄ. Są to GET, POST, PUT i DELETE. Twoim resendprzykładem byłoby dodanie nowego czasownika do REST. To powinna być czerwona flaga.
Pytanie 1
Ważne jest, aby zdawać sobie sprawę, że osoba dzwoniąca do interfejsu API REST nie powinna wiedzieć, że wykonanie PUTw kolekcji spowoduje wygenerowanie wiadomości e-mail. To dla mnie pachnie wyciekiem. Mogli wiedzieć, że wykonanie a PUTmoże spowodować dodatkowe zadania, które mogą później wykonać zapytanie. Wiedzieliby to, wykonując GETniedawno utworzony zasób. To GETzwróci zasób i wszystkie Taskpowiązane z nim identyfikatory zasobów. Następnie możesz później wysłać zapytanie do tych zadań, aby ustalić ich status, a nawet przesłać nowe Task.
Masz kilka opcji.
REST - podejście oparte na zasobach zadania
Utwórz taskszasób, w którym możesz przesyłać określone zadania do systemu w celu wykonywania działań. Możesz następnie GETwykonać zadanie na podstawie IDzwróconego zadania , aby ustalić jego status.
Możesz też połączyć SOAP over HTTPusługę internetową, aby dodać RPC do swojej architektury.
zapytania do wszystkich zadań dla określonego zasobu
GET http://server/api/myCollection/123/tasks
{ "tasks" :
[ { "22333" : "http://server/api/tasks/223333" } ]
}
przykład zasobu zadania
PUT http://server/api/tasks
{
"type" : "send-email" ,
"parameters" :
{
"collection-type" : "foo" ,
"collection-id" : "123"
}
}
==> zwraca identyfikator zadania
223334
GET http://server/api/tasks/223334
{
"status" : "complete" ,
"date" : "whenever"
}
REST - używanie POST do wyzwalania akcji
Zawsze możesz dodać POSTdodatkowe dane do zasobu. Moim zdaniem naruszyłoby to ducha REST, ale nadal byłoby zgodne.
Możesz wykonać test POST podobny do tego:
POST http://server/api/collection/123
{ "action" : "send-email" }
Będziesz aktualizować zasób 123 z kolekcji o dodatkowe dane. Te dodatkowe dane są w zasadzie działaniem nakazującym backendowi wysłanie wiadomości e-mail dla tego zasobu.
Mam z tym problem, że a GETw zasobie zwróci te zaktualizowane dane. Jednak rozwiązałoby to Twoje wymagania i nadal byłoby ODPOWIEDNIE.
SOAP - usługa sieciowa, która akceptuje zasoby uzyskane z REST
Utwórz nową usługę WebService, w której możesz wysyłać wiadomości e-mail na podstawie poprzedniego identyfikatora zasobu z interfejsu API REST. Nie będę tutaj szczegółowo omawiał SOAP, ponieważ pierwotne pytanie dotyczy REST, a tych dwóch koncepcji / technologii nie należy porównywać, ponieważ są to jabłka i pomarańcze .
pytanie 2
Masz również kilka opcji tutaj:
Wydaje się, że wiele większych firm publikujących API REST udostępnia searchkolekcję, która jest tak naprawdę tylko sposobem na przekazanie parametrów zapytania w celu zwrócenia zasobów.
GET http://server/api/search?q="type = myCollection & someField >= someval"
Które zwróciłyby kolekcję w pełni kwalifikowanych zasobów REST, takich jak:
{
"results" :
{ [
"location" : "http://server/api/myCollection/1",
"location" : "http://server/api/myCollection/9",
"location" : "http://server/api/myCollection/56"
]
}
}
Lub możesz zezwolić na coś takiego jak MVEL jako parametr zapytania.
pytanie 3
Wolę pod-poziomy niż konieczność powrotu do poprzedniej wersji i zapytania do innego zasobu za pomocą parametru zapytania. Nie wierzę, że istnieje jakakolwiek zasada w taki czy inny sposób. Możesz zaimplementować oba sposoby i pozwolić dzwoniącemu zdecydować, który jest bardziej odpowiedni na podstawie tego, jak po raz pierwszy wszedł do systemu.
Notatki
Nie zgadzam się co do czytelności komentarzy innych osób. Pomimo tego, co niektórzy mogą sądzić, REST wciąż nie jest przeznaczony do spożycia przez ludzi. Przeznaczony jest na zużycie maszynowe. Jeśli chcę zobaczyć moje tweety, korzystam ze zwykłej strony internetowej Twittera. Nie wykonuję REST GET z ich API. Jeśli chcę programowo zrobić coś z moimi tweetami, używam ich interfejsu API REST. Tak, interfejsy API powinny być zrozumiałe, ale gtenie jest tak źle, po prostu nie jest intuicyjne.
Inną najważniejszą rzeczą w REST jest to, że powinieneś być w stanie rozpocząć w dowolnym punkcie API i przejść do wszystkich innych powiązanych zasobów BEZ znajomości dokładnego adresu URL innych zasobów z wyprzedzeniem. Wyniki GETVERB w REST powinny zwrócić pełny adres URL REST zasobów, do których się odwołuje. Zamiast zapytania zwracającego identyfikator Personobiektu zwróciłby w pełni kwalifikowany adres URL, taki jak http://server/api/people/13. Następnie zawsze możesz programowo nawigować po wynikach, nawet jeśli zmieni się adres URL.
Odpowiedź na komentarz
W prawdziwym świecie rzeczy, które muszą się wydarzyć, nie tworzą, nie czytają, nie aktualizują ani nie usuwają zasobów (CRUD).
Można podjąć dodatkowe działania dotyczące zasobów. Typowe relacyjne bazy danych obsługują koncepcję procedur przechowywanych. Są to dodatkowe polecenia, które można wykonać na zestawie danych. REST z natury nie ma tej koncepcji. I nie ma powodu, by tak było. Tego typu akcje są idealne dla RPC lub SOAP Web Services.
Jest to ogólny problem, który widzę z interfejsami API REST. Deweloperzy nie lubią ograniczeń koncepcyjnych otaczających REST, więc dostosowują go do robienia tego, co chcą. To jednak łamie go od bycia usługą RESTful. Zasadniczo te adresy URL stają się GETwywołaniami pseudo-REST-serwletów.
Masz kilka opcji:
- Utwórz zasób zadania
- Obsługa
POSTdodatkowych danych do zasobu w celu wykonania akcji.
- Dodaj dodatkowe polecenia za pośrednictwem usługi sieci Web SOAP.
Jeśli użyjesz parametru zapytania, którego VERB HTTP użyjesz do ponownego wysłania wiadomości e-mail?
GET- Czy to ponownie wysyła wiadomość e-mail ORAZ zwraca dane zasobu? Co jeśli system buforował ten adres URL i traktował go jak unikalny adres URL tego zasobu. Za każdym razem, gdy trafią w adres URL, ponownie wysyła wiadomość e-mail.POST - W rzeczywistości nie wysłałeś żadnych nowych danych do zasobu, tylko dodatkowy parametr zapytania.
W oparciu o wszystkie podane wymagania, wykonanie POSTna zasobie z action fielddanymi POST rozwiąże problem.