Trasy i CRUD

Trasy to punkty wejścia Pana/Pani API. Są pogrupowane według zasobu i może Pan/Pani je pisać ręcznie lub wygenerować z modelu.

Definiowanie trasy

Trasa posiada metodę, ścieżkę, parametry oraz odpowiedzi. Ścieżka używa składni {{param}} Restorm: gdy tylko wpisze Pan/Pani {{id}} w ścieżce, pojawia się odpowiadający parametr; jego usunięcie kasuje go.

Parametry

Karta Definicja trasy wymienia jej parametry — parametry ścieżki (tworzone z placeholderów {{param}}) oraz parametry zapytania / nagłówka, które dodaje Pan/Pani za pomocą Dodaj parametr. Każdy z nich ma nazwę, umiejscowienie (w), informację, czy jest wymagany, opis oraz opcjonalnie przykład.

Komórka Typ to lista rozwijana: proszę wybrać prymityw (string, integer, number, boolean) lub jeden z nazwanych enumów projektu jednym kliknięciem. W bogatszych przypadkach proszę wybrać Advanced…, aby otworzyć małe okno, w którym może Pan/Pani:

• uczynić parametr tablicą i wybrać jego typ elementu (array<string>, …) — wielowartościowy parametr zapytania;
• nadać mu wartości enuma inline (dozwolony zbiór, wypisany w postaci żetonów), gdy nie jest typowany nazwanym enumem;
• Wyodrębnij do nazwanego enuma — wypromować te wartości inline do współdzielonego enuma (zobacz Modele i enumy).

Parametr może być również powiązany z właściwością modelu (kolumna Powiązanie z modelem), po której dziedziczy typ, albo oznaczony jako przestarzały. Każdy parametr — jego typ, jego enum, jego deprecjacja — trafia do wygenerowanej dokumentacji i do każdej projekcji protokołu.

Generowanie CRUD

Z ustawień modelu Generuj CRUD tworzy jednym kliknięciem grupę tras nazwaną od liczby mnogiej modelu, z sześcioma trasami:

Trasa	Metoda i ścieżka	Odpowiedzi
Lista	GET / (stronicowana)	200
Pobierz	GET /{{id}}	200 · 404
Utwórz	POST /	201
Zastąp	PUT /{{id}}	200 · 404
Zaktualizuj	PATCH /{{id}}	200 · 404
Usuń	DELETE /{{id}}	204 · 404

Lista jest stronicowana (przesunięcie/offset, 20 elementów domyślnie, 100 maksymalnie). Każde {{id}} jest automatycznie powiązane z identyfikatorem modelu.

Okno dialogowe Generuj CRUD oferuje dwie opcje:

• Zastąp istniejące trasy — aby uniknąć duplikatów, gdy generuje Pan/Pani ponownie.
• Chroń trasy zapisu uwierzytelnianiem — tworzenie, zastępowanie, aktualizacja i usuwanie wymagają wtedy tokenu (bearer), podczas gdy odczyty pozostają publiczne.

Przypomina również, że CRUD jest serwowany w każdym protokole: trasy REST, zapytania i mutacje GraphQL, metody gRPC, zestaw encji OData oraz operacje SOAP (zobacz Serwowanie projektu jako mock).

Generowanie tras wyszukiwania

Dla każdej właściwości oznaczonej jako searchable, Generuj trasy wyszukiwania dodaje parametr zapytania powiązany z trasą listy modelu (i tworzy tę trasę, jeśli jeszcze nie istnieje).

Uwierzytelnianie

Uwierzytelnianie ustawia się na trzech poziomach: wartość domyślna projektu, wymagane uwierzytelnianie na grupę oraz nadpisanie na trasę (które dziedziczy domyślne ustawienie grupy). Dostępne tryby to Brak, Bearer (JWT), Klucz API (nagłówek) oraz Basic.

Tagi

Tagi grupują trasy na potrzeby dokumentacji i eksportu OpenAPI. Istnieją na dwóch poziomach: trasa nosi swoje własne tagi (jej karta Definicja), a grupa nosi tagi współdzielone (jej ustawienia) stosowane do każdej z jej tras. Efektywne tagi trasy to suma obu — dlatego tag wspólny dla całej grupy najlepiej ustawić raz na grupie. Gdy przekształca Pan/Pani zaimportowane API w projekt, tag obecny na wszystkich trasach grupy jest automatycznie podnoszony na grupę.

Deprecjacja

Trasa (jak właściwość lub parametr) może zostać oznaczona jako przestarzała w jej Ustawieniach. Przestarzała trasa pojawia się wyszarzona na liście Tras oraz w generowanych klientach i nosi ostrzeżenie o przestarzałości na swojej karcie. Flaga propaguje się do każdej projekcji protokołu — deprecated w OpenAPI, dyrektywy @deprecated w GraphQL, deskryptorów SOAP i gRPC oraz metadanych OData — aby konsumenci dowolnego serwowanego protokołu ją widzieli.