Jak zbudować REST API: projekt, bezpieczeństwo i wdrożenie

Aby zbudować REST API, wypisz zasoby, którymi zarządza Twoja aplikacja (użytkownicy, zamówienia, rezerwacje), nadaj każdemu adres URL, na przykład /orders i /orders/{id}, a do działań użyj metod HTTP: GET do odczytu, POST do tworzenia, PATCH do aktualizacji, DELETE do usuwania. Zwracaj dane w JSON z sensownymi kodami statusu, waliduj każde wejście, wymagaj uwierzytelnienia i sprawdzania uprawnień do rekordu po stronie serwera oraz stronicuj listy. Następnie udokumentuj endpointy i wdróż API za HTTPS.

Ten poradnik opisuje decyzje projektowe, przykładowy zestaw tras, prompty dla narzędzia AI do budowania aplikacji oraz błędy, które prowadzą do luk bezpieczeństwa. Jeśli API jest dla Ciebie nowością, zacznij od czym jest API.

Kiedy potrzebujesz REST API

• Twój frontend webowy musi zapisywać i wczytywać dane z serwera
• Aplikacja mobilna, partner lub narzędzie automatyzacji potrzebuje dostępu do Twoich danych
• Inne usługi wysyłają do Ciebie zdarzenia (webhooki)
• Dzielisz pracę między zespołem frontendu a backendu

REST jest najpopularniejszym stylem, ale nie jedynym. REST kontra GraphQL wyjaśnia, kiedy lepiej sprawdza się jeden elastyczny endpoint zapytań.

Najpierw projekt: zasoby i trasy

Zapisz rzeczowniki występujące w Twojej aplikacji i to, co ludzie z nimi robią. Dla prostej aplikacji rezerwacji:

Te operacje odpowiadają tworzeniu, odczytowi, aktualizacji i usuwaniu; zobacz czym jest CRUD. Warte przestrzegania konwencje:

• Rzeczowniki w liczbie mnogiej, bez czasowników w adresach: /bookings, a nie /getBookings.
• Zagnieżdżaj tylko jeden poziom, gdy wyjaśnia to przynależność: /bookings/{id}/notes.
• Działania niebędące CRUD mogą być pod-zasobami: POST /bookings/{id}/cancel jest czytelniejsze niż tajemnicze PATCH.
• Spójne nazewnictwo pól, na przykład created_at wszędzie.

Kody statusu i błędy

Używaj standardowych kodów HTTP, aby klienci wiedzieli, co się stało, bez analizowania tekstu:

Zwracaj błędy w jednym, spójnym kształcie JSON, na przykład {"error": {"code": "slot_taken", "message": "Ten termin nie jest już dostępny."}}, i nigdy nie dołączaj do odpowiedzi śladów stosu ani błędów bazy danych.

Opcje i kompromisy

Krok po kroku

1. Wypisz zasoby i trasy jak wyżej, wraz z tym, kto może każdą wywołać.
2. Zamodeluj dane w bazie danych z polami i relacjami, których potrzebujesz.
3. Najpierw zbuduj trasy odczytu, potem tworzenie, aktualizację i usuwanie.
4. Waliduj dane wejściowe przy każdym zapisie za pomocą biblioteki schematów: pola wymagane, typy, długości, dozwolone wartości. Odrzucaj nieznane pola.
5. Dodaj uwierzytelnianie, a potem autoryzację per rekord: otwarcie /bookings/42 musi sprawdzić, czy rezerwacja 42 należy do wywołującego, a nie tylko to, czy ktoś jest zalogowany.
6. Stronicuj każdą listę i ogranicz rozmiar strony.
7. Ogranicz liczbę zapytań dla logowania i kosztownych tras. Zobacz limitowanie zapytań.
8. Skonfiguruj CORS tylko wtedy, gdy przeglądarki z innych domen muszą wywoływać API, i wymień te źródła jawnie. Jak naprawić błędy CORS wyjaśnia błędy, które zobaczysz.
9. Napisz dokumentację i testy dla każdej trasy, w tym przypadków błędów.
10. Wdróż z sekretami w zmiennych środowiskowych, HTTPS, logami i sprawdzaniem stanu.

Prompty dla narzędzia AI do budowania

Szkielet:

Utwórz REST API dla rezerwacji z tymi trasami: GET /api/health, GET /api/bookings (z paginacją, maks. 50 na stronę), POST /api/bookings, GET /api/bookings/:id, PATCH /api/bookings/:id, DELETE /api/bookings/:id. Przechowuj dane w naszej bazie danych. Waliduj treść zapytań za pomocą biblioteki schematów i odrzucaj nieznane pola. Zwracaj błędy JSON w postaci {"error": {"code", "message"}} z poprawnymi kodami statusu (400, 401, 403, 404, 409). Trzymaj sekrety w zmiennych środowiskowych.

Bezpieczeństwo:

Wymagaj logowania na każdej trasie bookings. Przy każdym odczycie, aktualizacji i usunięciu sprawdzaj po stronie serwera, czy rezerwacja należy do bieżącego użytkownika; jeśli nie, zwróć 404. Nigdy nie akceptuj identyfikatorów użytkowników ani ról z treści zapytania. Ogranicz POST /api/bookings do 20 na minutę na użytkownika. Zapisuj błędy na serwerze bez zwracania śladów stosu.

Dokumentacja:

Napisz opis OpenAPI tych tras oraz krótkie README z przykładowymi zapytaniami i odpowiedziami dla każdej z nich.

Testowanie API

Testuj z zewnątrz frontendu, bo zrobią to atakujący:

• Każda trasa działa dla poprawnych danych i zwraca opisany kształt oraz kod
• Brakujące lub nieprawidłowe pola zwracają 400 z czytelnym komunikatem
• Brak tokenu zwraca 401 na każdej chronionej trasie
• Użytkownik A żądający rekordu użytkownika B przez ID dostaje 404 lub 403
• Listy są stronicowane, a ogromny limit jest ograniczony
• Zduplikowane lub kolidujące tworzenie zwraca 409, a nie 500
• Limity zapytań zwracają 429
• Odpowiedzi błędów nie zawierają śladów stosu, SQL ani sekretów
• CORS zezwala tylko na zamierzone źródła

Częste błędy

• Sprawdzanie logowania, ale nie własności rekordu. Najczęstsza dziura w API: każdy zalogowany użytkownik może odczytać dowolny rekord, zmieniając ID.
• Ufanie klientowi. Ceny, role i identyfikatory użytkowników z treści zapytania można edytować.
• Zwracanie całych wierszy bazy danych. Hasze haseł i pola wewnętrzne wyciekają. Wybierz, co ma zawierać każda odpowiedź.
• Nieograniczone listy. Jedno zapytanie o wszystkie rekordy może spowolnić całą aplikację.
• 200 OK z komunikatem błędu w środku. Klienci i monitoring nie wiedzą, że coś się nie udało.
• CORS ustawiony na zezwalanie na wszystko w API, które używa ciasteczek.
• Brak sprawdzania stanu i logów, więc o awariach dowiadujesz się od użytkowników.

Aby zrobić szerszy przegląd przed startem, zobacz listę kontrolną bezpieczeństwa dla aplikacji zbudowanych z AI.

Budowanie REST API w Mythex

W Mythex możesz poprosić o API jako część aplikacji lub jako osobny serwis. Przepis w dokumentacji REST API backend zawiera gotowy prompt startowy: nazwij framework i trasy, poproś o czytelne błędy JSON, trzymaj sekrety w zmiennych środowiskowych i dołącz Dockerfile. Backendy kontenerowe w Node, Pythonie, C#, Javie i innych są publikowane przez Dockerfile, a wdrożeniem z menu Publish zajmuje się Mythex (backendy API). Projekt może uruchamiać stronę i serwer API obok siebie, a między nimi przełączać się w podglądzie. Klucze przechowuj jako sekrety projektu, a jeśli API potrzebuje bazy danych, poproś o nią w czacie. Pracę cykliczną wokół API opisuje jak uruchamiać zadania w tle.

Pytania