API

API Aura: programistyczny dostęp do danych i działań systemu, z uprawnieniami i dokumentacją — do użycia we własnych narzędziach, nie tylko na ekranie.

• OperacjeRodzina
• w abonamencie AURARozliczenie

Problem

Dane są w systemie, ale potrzebne bywają gdzie indziej: w arkuszu zarządu, w narzędziu, które ktoś u Was napisał, w zestawieniu obejmującym kilka lokali naraz. Bez dostępu programistycznego jedyną drogą zostaje eksport do pliku i ręczne przepisanie — czyli dokładnie ta praca, której cały system miał uniknąć.

Co robimy

Udostępniamy dane i działania systemu na zewnątrz w sposób, którym może posłużyć się Wasz programista albo Wasze narzędzie.

• Dostęp nadaje się i odbiera po stronie uprawnień, a nie przez wysłanie komuś hasła
• Zakres ustalamy wprost: co wychodzi na zewnątrz, a co zostaje w środku
• Do dostępu dołączamy dokumentację, bo interfejs bez opisu jest dostępem wyłącznie na papierze

Co wchodzi w zakres

Trzy elementy; o drugim decydujecie Wy, a nie my:

• Dostęp do danych systemu i do jego działań
• Uprawnienia: kto, do czego i na jak długo
• Dokumentacja opisująca, jak z tego korzystać

Ile to trwa

Moduł nie uruchamia się osobno — włącza się razem z poziomem AURA. Ile zajmie praca po Waszej stronie, zależy od tego, do czego dostęp ma prowadzić: podłączenie gotowego narzędzia to co innego niż napisanie własnego. Zakres i termin takiej pracy ustalamy przed startem, a nie w trakcie.

Ile to kosztuje

Dostęp programistyczny nie stoi obok systemu jako oddzielna umowa — jest jego częścią i wygasa razem z nim. Nie ma więc własnego cennika ani własnego terminu wypowiedzenia. To, czy go w ogóle włączać i jak szeroko, ustala się przy konfiguracji, razem z resztą uprawnień.

Jeśli po Waszej stronie potrzebna jest osobna praca integracyjna — połączenie z systemem, którego jeszcze nie obsługujemy — to odrębna usługa z własną wyceną i własnym artykułem: Integracje API.

Co z tego macie

Dane, które nie kończą się na naszym ekranie. Zarząd może wciągnąć je do własnego zestawienia, sieć zsumować kilka lokali, a Wasz programista dopisać narzędzie, którego u nas nie ma. Przy okazji jedno zabezpieczenie: skoro dostęp nadaje się osobno, da się go odebrać bez zmiany czegokolwiek w samym systemie.

Jak policzyć realne obciążenie, zanim ustalicie limity dostępu

Zanim ktoś zapyta o limit zapytań, warto policzyć, ile ich realnie będzie. Wzór: zapytania_na_minutę = liczba_aktywnych_użytkowników_narzędzia × liczba_odświeżeń_na_minutę_na_użytkownika.

• liczba_aktywnych_użytkowników_narzędzia — ile osób albo procesów faktycznie korzysta z dostępu w danym momencie, nie ile ma do niego dostęp w ogóle
• liczba_odświeżeń_na_minutę_na_użytkownika — jak często Wasze narzędzie odpytuje dane; pulpit odświeżany co minutę to co innego niż odpytanie raz dziennie

Przy pięciu użytkownikach odpytujących dane raz na minutę to pięć zapytań na minutę — mało. Ten sam pulpit odpytujący co sekundę to już trzysta zapytań na minutę, i to jest pytanie, które trzeba zadać przed startem, nie po nim.

Trzy drogi wyjścia danych na zewnątrz: eksport ręczny, gotowy pulpit, dostęp programistyczny

Wybór zależy od tego, jak często potrzebujecie danych i kto po drugiej stronie je odbiera.

• Eksport ręczny do pliku: nie wymaga programisty, ale ktoś musi go za każdym razem pobrać i przesłać dalej
• Gotowy pulpit albo raport w systemie: dane widać od razu, ale tylko w takim układzie, jaki przewidział pulpit
• Dostęp programistyczny (ta usługa): dane trafiają wprost do Waszego narzędzia albo arkusza zarządu, w układzie, jaki sami wybierzecie

Dostęp programistyczny ma sens tam, gdzie dane mają płynąć regularnie i automatycznie do czegoś, co już macie albo dopiero budujecie. Tam, gdzie wystarczy spojrzeć raz w tygodniu, gotowy pulpit jest prostszy i tańszy.

Kiedy dostęp programistyczny się nie opłaca

Cztery sytuacje, w których warto wybrać coś innego:

• Nikt po Waszej stronie nie programuje ani nie zleca tego na stałe — dostęp bez odbiorcy zostaje kluczem, którego nikt nie używa
• Potrzeba jest jednorazowa, na przykład jednorazowe zestawienie na potrzeby audytu — prostszy i tańszy będzie ręczny eksport
• Wystarczy spojrzeć na dane raz na jakiś czas, bez potrzeby łączenia ich z innym narzędziem — gotowy pulpit w systemie robi to samo za mniej
• Chodzi w istocie o połączenie z konkretnym, innym systemem, a nie o surowy dostęp do danych — to jest usługa Integracje, nie ta

W tym ostatnim przypadku różnica nie jest kosmetyczna: dostęp daje surowe dane i dokumentację, integracja buduje gotowe połączenie między dwoma konkretnymi systemami.

Co potrzebujemy z Waszej strony, żeby dostęp miał sens

Dostęp bez planu, do czego ma służyć, jest tylko kluczem leżącym w szufladzie.

• Osoba techniczna — programista, integrator albo Wasze narzędzie — która będzie faktycznie korzystać z dostępu
• Jasny zakres: które dane i które działania mają wychodzić na zewnątrz, a które mają zostać w środku
• Decyzja, kto po Waszej stronie nadaje i odbiera uprawnienia, kiedy zmienia się skład zespołu

Bez tej ostatniej decyzji dostęp zostaje przypisany do jednej osoby na stałe — a to problem, kiedy ta osoba odchodzi z firmy.

Jak sprawdzić efekt po miesiącu, bez naszego raportu

Trzy rzeczy widać po stronie Waszego narzędzia, bez logowania się do niczego naszego.

• Czy zapytania w ogóle przychodzą — widać to w logach Waszego narzędzia albo integratora
• Czy dokumentacja wystarcza, żeby ktoś nowy, kto nigdy z nią nie pracował, uruchomił połączenie samodzielnie
• Czy odebranie dostępu jednej osobie faktycznie przerywa połączenie natychmiast, a nie po kilku dniach

Ten ostatni test warto zrobić raz, świadomie — to prostszy sposób sprawdzenia bezpieczeństwa niż czytanie umowy.

Czego dostęp do API nie robi

Dostęp daje dane i uprawnienia, ale nie pisze za Was narzędzia, które z nich korzysta — samo narzędzie ktoś musi zbudować: Wasz programista albo my, i wtedy jest to już praca do zaplanowania, a nie przełącznik do włączenia.

Nie obiecujemy też konkretnego czasu odpowiedzi ani nieprzerwanej dostępności — to nie jest umowa serwisowa z gwarantowanym SLA, tylko dostęp w ramach systemu, z którego korzystacie na co dzień. I nie zastępuje spinania systemów: jeśli potrzebujecie gotowego, stałego połączenia z konkretnym cudzym systemem, tym zajmuje się warstwa integracji — obok, w tej samej AURZE.

Najczęstszy błąd przy korzystaniu z dostępu API

Wspólne hasło zamiast osobnych uprawnień. Ktoś udostępnia jeden klucz dostępu całemu zespołowi, bo tak jest szybciej — a potem nikt nie wie, które narzędzie akurat go używa, i odebranie go jednej osobie oznacza wyłączenie wszystkich naraz.

Koszt tego błędu wychodzi na jaw dopiero przy rozstaniu z pracownikiem albo przy awarii: trzeba wyłączyć wszystko i uruchamiać na nowo, zamiast po prostu odebrać dostęp jednej osobie. Dlatego uprawnienia nadajemy pojedynczo, a nie jednym wspólnym kluczem dla wszystkich.

Czyje są dane i co się dzieje, gdy zmienia się samo API

Dane, do których dajemy dostęp, są Wasze — powstały z Waszej działalności i zostają Wasze niezależnie od tego, czy dostęp programistyczny jest w ogóle włączony.

• Dostęp nadaje się i odbiera po stronie uprawnień, bez zmiany czegokolwiek w samym systemie — odebranie go jednej osobie albo całemu narzędziu nie kasuje danych
• Przy rozstaniu z Aurą dostęp programistyczny wygasa razem z resztą systemu, na tych samych zasadach co wszystko inne — nie jest to osobna umowa, którą trzeba wypowiadać oddzielnie
• Jeśli sami zmieniamy kształt danych albo sposób ich pobierania, robimy to jako zmianę wersji, a nie ciche nadpisanie tego, co już działa — stare narzędzia nie mają się wyłączać z dnia na dzień bez wiedzy o tym

Odwrotna sytuacja — kiedy to Wasze narzędzie zależy od cudzego API, nie naszego — niesie to samo ryzyko: druga strona może zmienić swój interfejs bez pytania nikogo. Dlatego dokumentacja i logi są częścią dostępu, nie dodatkiem: żeby taką zmianę było widać od razu, a nie po tygodniu ciszy.