Jak zaprojektować interfejs API REST do obsługi operacji innych niż CRUD?

Próbuję przekonwertować zestaw usług opartych na SOAP na interfejs API RESTful.

Zacząłem od identyfikacji zasobów, analizując nazwy operacji i dostałem zasób Subscription.

Kiedy muszę zaktualizować stan subskrypcji, nie mogę po prostu wysłać POSTżądania do serwera, ponieważ nie mam bezpośredniego dostępu do zasobów, ale muszę wywołać niektóre operacje w stylu RPC, aby zaktualizować ich właściwości. Dodatkowo tylko i tylko wtedy, gdy zmieniam stan subskrypcji na „aktywny”, wymagane jest dodatkowe połączenie z usługą zewnętrzną.

W takich przypadkach, jaka jest najlepsza praktyka obsługi podstawowych operacji?

Rozwiązaniem, które wymyśliłem, jest użycie parametrów zapytania, aby w razie potrzeby zadzwonić do usługi aktywacji, mogę użyć czegoś takiego:

POST /subscriptions/{subscriptionid}/?activate=true

Biorąc pod uwagę, że nie mogę bezpośrednio zaktualizować moich pól obiektów subskrypcji, czy istnieje jakaś najlepsza praktyka do obsługi tego rodzaju konwersji?

Aktualizacja 1:

Mogę podać w treści mojego żądania POST niektóre wartości, na przykład „stan”: „aktywny”

i sprawdź w mojej usłudze, jakie operacje mają zostać uruchomione.

Musisz obejrzeć ten wykład Jima Webbera.

Kiedy muszę zaktualizować stan subskrypcji, nie mogę po prostu wysłać żądania POST do serwera, ponieważ nie mam bezpośredniego dostępu do zasobów, ale muszę wywołać niektóre operacje w stylu RPC, aby zaktualizować ich właściwości. Dodatkowo tylko i tylko wtedy, gdy zmieniam stan subskrypcji na „aktywny”, wymagane jest dodatkowe połączenie z usługą zewnętrzną.

Pomyśl „wiadomości”; wyślij wiadomość do swojej domeny, opisując, co chcesz zrobić. Skutkiem ubocznym komunikatu jest fakt, że model domeny faktycznie zmienia swój stan. „Zasób” to kolejka komunikatów.

POST /subscriptions/{subscriptionid}/?activate=true

Pisownia nazwy zasobu nie ma znaczenia dla maszyn; ale ludzie robią się wybredni, gdy używane identyfikatory łamią konwencję, że zasoby to „rzeczowniki”.

Mówimy również o zasobie, który jest podporządkowany /subscriptions/{subscriptionid}, więc konwencja (patrz RFC 3986 ) wymaga wyrażenia tej relacji za pomocą segmentu ścieżki zamiast korzystania z części zapytania.

Więc te pisownie mogą być rozsądne

POST /subscriptions/{subscriptionid}/messages
POST /subscriptions/{subscriptionid}/activations

Jeśli jest to flaga logiczna do aktywacji / dezaktywacji rzeczy, powiedziałbym, że domyślnie jest użycie JSON:

POST /subscriptions/{subscriptionid}/
{
    format: 0,
    subscription: 
    {
        active: false
    }
}

Można to łatwo rozszerzyć, jeśli chcesz obsługiwać więcej właściwości. Innym podejściem jest nadanie mu własnego punktu końcowego:

POST /subscriptions/{subscriptionid}/active/
DELETE /subscriptions/{subscriptionid}/active/

Osobiście użyłbym tego tylko wtedy, gdy activestan tego zdarzenia wymaga / ma właściwości, które można przekazać / uzyskać w JSON, takie jak identyfikator użytkownika lub ustawienie.

Jeśli nie jest to wartość logiczna, ale tylko działanie, które musisz wyzwolić, ale nie potrzebujesz / nie masz żadnych informacji zwrotnych o stanie (z wyjątkiem natychmiastowego 200 OK), użyłbym takiego punktu końcowego, aby wywołać go podobnie jak RPC:

POST /subscriptions/{subscriptionid}/activate/

W razie wątpliwości przeczytaj to: http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api#restful (patrz „Co z działaniami, które nie pasują do świata operacji CRUD? „)

REST nie działa. Activatejest czasownikiem i nie może być stanem, Activejest stanem.

Ponieważ usługa RESTful nie działa, nie można powiedzieć usłudze RESTful, co ma robić, ale można dodać pracę do kolejki usługi.

Zobacz:

PUT /subscriptionQueue
subscriptionId={subscriptionId}
active=true

To żądanie jest RESTful i obsługuje wszystkie zalety RESTful (takie jak wydajność, kwas ...)