Generator nazw punktów końcowych API

Podstawy nazewnictwa punktów końcowych API

Nazwy punktów końcowych znajdują się pomiędzy językiem produktu a szczegółami implementacji. Dobra etykieta punktu końcowego powinna informować członka zespołu o działaniu trasy, zanim ktokolwiek otworzy kontroler, specyfikację lub dziennik zmian. W interfejsie API w stylu REST sformułowania zazwyczaj zapewniają równowagę między przejrzystością zasobów, intencją metody, zakresem, wersjonowaniem i regułami dostępu. Nazwa taka jak „Pobierz status zadania eksportu” wskazuje na inny model mentalny niż „Uruchom starą procedurę rozliczeniową”. Jedna brzmi ogranicznie i można ją przeglądać, podczas gdy druga sugeruje przestarzały zestaw działań. Ten generator analizuje zarówno dopracowane, jak i problematyczne wzorce, dzięki czemu można rozpoznać, co należy do publicznego interfejsu API, co znajduje się za bramą administracyjną, a co prawdopodobnie powinno zostać zmienione, zanim dotrze do klienta.

Jak korzystać z wygenerowanych nazw punktów końcowych

Mapowanie nazwy na rzeczywisty zasób

Zacznij od pytania, który rzeczownik jest właścicielem działania. Użytkownicy, faktury, przesyłanie, sesje, organizacje, eksporty i webhooki – wszystkie te pojęcia sugerują różne konwencje. Jeśli wygenerowana nazwa zawiera właściwy rzeczownik, ale niewłaściwy czasownik, zachowaj rzeczownik i przepisz działanie. Jeśli czasownik wydaje się właściwy, ale zasób jest niejasny, zawęź go do momentu, aż nazwa będzie miała sens w tabeli referencyjnej API.

Szanuj zakres i dostęp

Trasy tylko dla administratorów, publiczne trasy tylko do odczytu, wyzwalacze zadań w tle i wewnętrzne punkty końcowe narzędzi nie powinny być używane zamiennie. Ich nazwy niosą ze sobą ryzyko operacyjne. Działanie destrukcyjne powinno wyraźnie wskazywać na usunięcie, odwołanie, oczyszczenie lub anulowanie. Kontrola stanu powinna być obserwowalna, a nie mutująca. Wywołanie zwrotne webhooka powinno wskazywać na przychodzące zdarzenie.

Utrzymuj widoczną wersję, gdy jest to istotne

Trasy z wersjonowanymi i wycofanymi wersjami wymagają nazw, które ułatwią zespołom migrację. Użyj wygenerowanych nazw wycofanych do oznaczania punktów końcowych zgodności, ostrzeżeń o wycofaniu, usuniętych map pól lub podglądów zastępczych. Celem nie jest nadawanie nazw dekoracyjnych. Celem jest zmniejszenie niejednoznaczności w przypadku nakładania się starych i nowych klientów oraz narzędzi wewnętrznych.

W przypadku użytku zespołowego, traktuj wybraną nazwę jako kontrakt między kodem a dokumentacją. Jeśli nazwa nie może wyjaśnić zasobu, efektu, poziomu dostępu i cyklu życia w kilku słowach, prawdopodobnie wymaga od ścieżki, schematu lub specyfikacji wykonania zbyt wielu napraw.

Praktyczne wskazówki dotyczące wyboru nazwy

• Preferuj silny rzeczownik określający zasób zamiast niejasnego obiektu, takiego jak element, rzecz, dane lub rzeczy.
• Używaj czasowników, które pasują do zachowania trasy, szczególnie w przypadku mutacji, eksportów i zadań w tle.
• Oznaczaj wyraźnie operacje administracyjne, wewnętrzne, niebezpieczne lub o zasięgu dzierżawcy.
• Unikaj nazw, które ukrywają skutki uboczne za neutralnymi słowami, takimi jak proces lub akcja.
• Nazwy webhooków powinny koncentrować się na odbieranym lub obsługiwanym zdarzeniu.
• Sprawdź, czy nazwa nadal ma sens w logach, dokumentacji i notatkach pomocy technicznej.

Monity o dopracowaniu języka punktów końcowych

Gdy wynik przyciągnie Twoją uwagę, przetestuj go na otaczającej go powierzchni API. Nazwy punktów końcowych najlepiej sprawdzają się jako rodziny, a nie izolowane etykiety. Użyj tych pytań, aby przekształcić wstępne założenia w konwencję, którą Twój zespół może powtórzyć.

• Jaki dokładnie zasób pojawiłby się w ścieżce lub kontrolerze o tej nazwie?
• Czy punkt końcowy jest tylko do odczytu, mutujący, destrukcyjny, wewnętrzny, publiczny czy o zasięgu dzierżawy?
• Czy to samo sformułowanie byłoby nadal jasne w podsumowaniu OpenAPI?
• Czy nazwa ujawnia wystarczające ryzyko dla zespołów ds. bezpieczeństwa i wsparcia?
• Czy przyszła wersja mogłaby zachować ten wzorzec bez kłopotliwych wyjątków?
• Które sąsiednie punkty końcowe powinny mieć ten sam wzorzec czasownika lub rzeczownika?

Jakie Nazwy punktów końcowych API są dobre?

Ten generator zawiera tysiące losowych Nazwy punktów końcowych API. Oto kilka przykładów na początek:

• Create Customer Profile
• List Project Comment Threads
• Admin Suspend User Login
• Browse Public Catalog
• Bulk Import Customer Records
• Receive Payment Settled Webhook
• Fetch Deprecated V1 Profile
• Begin OAuth Authorization
• Export Daily Usage Metrics
• Create Direct Upload URL