Tworzenie API na zamówienie: własny interfejs do danych firmy
Własne API przydaje się, gdy dane firmy mają być dostępne dla aplikacji, partnerów albo kilku systemów naraz w uporządkowany sposób. Jeśli chcesz tylko połączyć dwa istniejące programy, to inny temat.
Autor: Szymon Łakomy. Aktualizacja:
Kiedy własne API jest potrzebne, a kiedy nie
Potrzebne
Kilka aplikacji korzysta z tych samych danych, na przykład panel, aplikacja mobilna i strona. Partnerzy albo klienci mają pobierać dane automatycznie. Chcesz udostępnić dane ze starego systemu nowym narzędziom.
Zbędne
Chcesz tylko przekazywać dane między dwoma systemami, które mają własne API. Wtedy wystarczy integracja, opisana na stronie integracje API. Nie buduj własnego interfejsu, z którego nikt poza jedną aplikacją nie skorzysta.
Z czego składa się porządne API
| Element | Po co | Co ustalamy |
|---|---|---|
| Dokumentacja | odbiorca wie, jak korzystać, bez dzwonienia do wykonawcy | opis zasobów, przykłady zapytań, kody błędów |
| Uwierzytelnianie | dostęp mają tylko uprawnione systemy i osoby | klucze lub tokeny, zakres dostępu dla każdego odbiorcy |
| Wersjonowanie | zmiana nie psuje cudzych integracji | jak długo działa stara wersja i jak zapowiadamy zmiany |
| Limity zapytań | jeden odbiorca nie zablokuje reszty | limit dla każdego klucza i komunikat po jego przekroczeniu |
| Obsługa błędów | odbiorca rozumie, co poszło nie tak | spójne komunikaty zamiast ogólnego „błąd serwera” |
| Testy | nowa funkcja nie łamie istniejących | testy automatyczne na kluczowych zasobach |
Wersjonowanie bez łamania cudzych integracji
W tym miejscu własne API najczęściej sprawia kłopot po roku. Odbiorca zbudował coś na obecnym formacie danych i nie chce zmian. Dlatego nowe pola dodaje się obok starych, a zmiany łamiące zgodność trafiają do nowej wersji, z okresem, w którym działają obie. Z góry ustalamy, jak długo utrzymujesz starą wersję i kto informuje o tym odbiorców. Zapowiedź zmiany powinna dotrzeć do nich wcześniej niż komunikat o błędzie.
Bezpieczeństwo i dane
- każdy odbiorca ma osobny klucz, który można wyłączyć bez wpływu na resztę,
- dostęp obejmuje zasoby potrzebne odbiorcy, a nie całą bazę,
- logi zapytań pokazują, kto i kiedy pobrał dane,
- dane osobowe są zwracane tylko wtedy, gdy odbiorca naprawdę ich potrzebuje.
Przy danych osobowych zakres udostępniania ustalasz jako administrator danych, najlepiej z prawnikiem. To nie jest porada prawna.
Jak przebiega praca
- Spisujemy zasoby, czyli rzeczy, o które pytają odbiorcy, na przykład zamówienie, klient, produkt.
- Opisuję interfejs w dokumentacji przed napisaniem kodu, żebyś mógł go ocenić razem z odbiorcami.
- Buduję API i testy, a odbiorcy sprawdzają je na środowisku testowym.
- Uruchamiamy z monitoringiem błędów i ustaloną osobą, która przyjmuje zgłoszenia.
Technologicznie opieram to zwykle na Django. Koszt łączenia istniejących systemów opisuję w poradniku ile kosztuje integracja API.
Najczęstsze pytania
Czym API różni się od integracji?
Integracja łączy istniejące systemy, korzystając z ich interfejsów. Własne API to nowy interfejs do Twoich danych, z którego mogą korzystać inni.
W jakim formacie będą dane?
Najczęściej REST z danymi w formacie JSON, bo jest powszechnie zrozumiały. Jeśli odbiorca wymaga innego formatu, ustalamy to na początku.
Czy dostanę dokumentację dla odbiorców?
Tak, w formie, którą odbiorca może otworzyć w przeglądarce i na jej podstawie przetestować zapytania. Dokumentacja jest częścią zakresu, a nie dodatkiem.
Co jeśli odbiorca nie ma programisty?
Wtedy zwykle lepiej podać gotowy plik albo połączyć systemy przez narzędzie typu n8n. API jest wygodne dla odbiorcy z zespołem technicznym, więc nie wymuszam go tam, gdzie nikt z niego nie skorzysta.
Powiązane strony
Chcesz udostępnić dane firmy przez API?
Napisz, kto ma korzystać z danych i jakich informacji potrzebuje. Odpowiem z propozycją zakresu i wyceną.