Eineinhalb Jahre lang haben wir API mit zwanzig externen Diensten integriert. Die ersten fünf Integrationen gingen durch Schmerz und Tränen - wir haben alle möglichen Fehler gemacht. Sie haben den Code mehrmals umgeschrieben und sich kurz vor der Veröffentlichung von den Partnern getrennt, da sie sich nicht auf Verbesserungen einigen konnten. Zeit und Geld verloren.
Aber mit jeder neuen Integration haben wir Lösungen für wiederkehrende Probleme gefunden. Infolgedessen haben wir die letzte Integration viermal schneller als die erste durchgeführt. Was wir jetzt anders machen - lesen Sie den Artikel.
Damit Sie die Besonderheiten unserer Integrationen besser verstehen, werden wir kurz beschreiben, was wir tun. Wir entwickeln einen Online-Broker. Arbeitsprinzip: Der Benutzer kommt auf die Website, füllt den Fragebogen aus, wir übertragen ihn an Mikrofinanzorganisationen (MFIs) und erhalten von ihnen die Genehmigung oder Ablehnung eines Darlehens. Der Benutzer wählt ein geeignetes Angebot aus und erhält Geld. Damit dies online funktioniert, integrieren wir MFIs über die API.
Bewerten Sie die Integrationsbereitschaft des Partners anhand einer Checkliste und einer Spezifikation
Wir werden zwei Szenarien analysieren: Wenn ein potenzieller Partner bereits über eine API zum Akzeptieren von Anwendungen verfügt und wenn nicht. Beide Szenarien deuten darauf hin, dass der Partner sich in uns integrieren möchte und bereit ist, Zeit damit zu verbringen.
Der Partner hat keine API - wir senden die Spezifikation
Zuvor haben wir dem Partner mündlich oder in Korrespondenz erklärt, was wir für die Integration benötigen, und der Partner hat auf der Grundlage dieser Erklärungen eine API zum Akzeptieren von Bewerbungen mit Finspin erstellt. Wir waren uns nicht einig über die Anforderungen an Modelle, Objekte, Felder des Fragebogens und die Regeln für deren Validierung. Beschrieb schnell den Zweck der Methoden und mögliche Antworten. Das Ergebnis erwies sich als unendlich weit von den Erwartungen entfernt, da sich unser Verständnis der API stark von dem der Partnerschaft unterschied. Ich musste alles wiederholen.
Jetzt . Wir haben unsere Spezifikation geschrieben - eine YAML-Datei, die in Swagger geöffnet werden kann. In der Spezifikation haben wir die am besten geeignete API für die Integration von Finspin in MFIs beschrieben: die Felder des Fragebogens und die Regeln für deren Validierung, Formate und Arten von Anfragen mit Antworten, Methodennamen, möglichen Fehlern und Status. Wir haben den Status des Status des Antrags aufgezeichnet, den wir erhalten möchten, z. B. "Zur Bearbeitung angenommen", "Bewertung in Bearbeitung", "Verweigertes Darlehen", "Genehmigung" usw.
Wir senden die Spezifikation an den Partner und er entscheidet, ob er eine solche API bereitstellen kann. Wenn dies nicht möglich ist, werden problematische Punkte in der Spezifikation festgestellt. Beispielsweise sind nicht alle Anwendungsstatus bereit, an die API übertragen zu werden, oder der Fragebogen enthält nicht genügend Felder. Und wir diskutieren bereits bestimmte Punkte, keine abstrakten Entitäten. Der Partner verschwendet keine Zeit damit, seine Unterlagen zu schreiben, sondern passt unsere an.
Wir haben zwei Tage damit verbracht, die Spezifikation zu erstellen, aber jetzt sparen wir zehn Stunden bei Genehmigungen und Verbesserungen der API. Mithilfe von Spezifikationen filtern wir außerdem schnell Partner heraus, die nicht für die Integration bereit sind. In der Anfangsphase wird deutlich, dass unsere Online-Bewerbungsverarbeitungsprozesse sehr unterschiedlich sind: Die Integration ist unrentabel.
Der Partner hat eine API - führen Sie die Checkliste durch
Früher haben wir die Spezifikation eines Partners erhalten und unterwegs Fragen gestellt. Oft vergaßen sie, etwas Wichtiges zu klären, und dann tauchte dieses Wichtige in den letzten Phasen der Entwicklung und des Testens auf, als es besonders teuer wurde, es zu reparieren und neu zu schreiben. Irgendwie stellte sich am Ende der Integration mit einem Partner heraus, dass er den Status von Krediten mit einer Verzögerung von mehreren Tagen über API übertragen würde. Für uns ist das inakzeptabel. Die Partnerschaft musste aufgegeben werden.
Jetzt . Wir haben eine Checkliste geschrieben, um die API und die Prozesse, denen sie dient, zu bewerten. Die Checkliste sammelte Fragen, die beantwortet werden müssen. Zunächst sucht unser Manager nach Antworten in der Spezifikation. Wenn nicht gefunden, werden Fragen an den Partner gerichtet.
Die Checkliste hilft Ihnen dabei, Engpässe zu finden, bevor Sie mit der Entwicklung beginnen, und nicht danach - wenn Sie den Code bearbeiten müssen und Kunden unter einem schlechten Service leiden.
Wir füllen die Checkliste ständig auf, wenn wir mit neuen Situationen konfrontiert sind. Je detaillierter die Checkliste ist, desto geringer ist das Risiko, Fehler in der Entwicklung zu überspringen.
API-ChecklistenfragmentGlossar der Begriffe
Bisher schien es uns, dass im Bereich der Online-Kreditvergabe jeder Fachbegriffe auf die gleiche Weise versteht, dass es keine Unstimmigkeiten geben kann. Die Praxis hat gezeigt, dass wir falsch lagen.
Bei einem MFI haben wir beispielsweise primäre und wiederkehrende Clients unterschiedlich interpretiert. Für uns ist der Hauptkunde der Kunde, dessen Profil zuerst über Finspin in die MFI-Datenbank eingegeben wurde, und der Stammkunde war bereits in der Datenbank. Der Partner betrachtete Stammkunden anhand der Anzahl der ausgegebenen Kredite: Wiederholung erhielt zwei Kredite und kam für einen dritten. Eine solche terminologische Verwirrung könnte zu Inkonsistenzen bei der finanziellen Abstimmung führen.
Jetzt verwenden wir ein kleines Glossar mit Begriffen, anhand dessen wir uns bei Partnern erkundigen. In der Regel reicht es aus, fünf oder sechs Grundbegriffe zu klären, um Integrationsideen zu synchronisieren und die Aussichten für eine Zusammenarbeit zu bewerten.
Sobald ein Glossar mit Begriffen uns geholfen hat, eine nachteilige Integration zu vermeiden. Unsere Interpretation von "Genehmigung" war sehr unterschiedlich zu der des verbundenen Unternehmens. Die „Genehmigung“ des Partners umfasste viele verschiedene Aspekte, die eine manuelle Verarbeitung erforderten. Wir streben nach maximaler Automatisierung und haben uns sofort geweigert, zusammenzuarbeiten.
Klären Sie den Begriff "Genehmigung"Erst Geschäft, dann Entwicklung
Früher gab es Fälle, in denen wir mit einem potenziellen Partner mit einer Spezifikation zusammengearbeitet haben. Unser Manager erhielt die Spezifikation, studierte sie sorgfältig, spezifizierte Details für die Integration mit dem Partner und diskutierte umstrittene Probleme mit den Entwicklern. Und dann kam eine Nachricht von der Führung: "Ende, Integration wird abgebrochen, wir haben uns nicht auf die Bedingungen geeinigt." Mitarbeiter verschwendeten Zeit.
Wenn Sie Ihre Meinung ändern und die Arbeit erledigt istJetzt gilt die Eisenregel: Der Manager beginnt erst mit dem Studium der Spezifikation, wenn er vom Management eine klare Entscheidung über die Integration erhält.
Integrationsbereitschaft: URLs, Details, Umgebung
Zuvor erfolgte der erste Aufruf der Partner-API während des Testens unserer Anwendung von Entwicklungsservern. Häufig erhielten die ersten Anforderungen beim Verbindungsaufbau Fehler: Es kann keine Verbindung zum Server hergestellt werden oder es tritt nur eine Zeitüberschreitung auf. Beliebteste Gründe:
- Falsche Methodennamen (versiegelt oder verwirrt)
- Ungültige Domain
- fehlerhafte Verbindungsdetails,
- Wir haben die IP unserer Server nicht zur Whitelist hinzugefügt.
Es hat Stunden gedauert, um solche kleinen Fehler zu beheben, da sie nacheinander aufgetreten sind: Bis Sie einen behoben haben, werden Sie den nächsten nicht sehen.
Bevor wir die Aufgabe in den Entwicklungsplan aufnehmen, klären wir alle Funktionen des Zugriffs auf die API mit einer kleinen Checkliste. In der Checkliste sind die Punkte aufgeführt, die geklärt werden müssen, zum Beispiel:
- Einschränkungen bei der Auslastung des Dienstes,
- die Anzahl der Anfragen pro Zeiteinheit
- Verbindungsdetails
- Whitelist nach IP-Adressen,
- Validierung des SSL-Zertifikats
- Anforderungen an die Verkehrsverschlüsselung,
- spezielle Header in Anfragen
- das Vorhandensein eines Testservers mit API oder die Fähigkeit, Testanforderungen an den Kampfserver zu senden
Wenn es eine Test-API gibt, werden wir auf jeden Fall herausfinden, was der Unterschied beim Zugriff auf den Battle Server und den Test-Server ist. Wir berücksichtigen Unterschiede beim Erstellen von Anforderungen aus unserer Anwendung an Partner in Entwicklungs- und Produktumgebungen. Solche Maßnahmen helfen uns zu verstehen, ob die Systeme für unsere Anforderungen bereit sind oder ob zusätzliche Anpassungen erforderlich sind.
Manuelles Senden von Anforderungen an die API
Vorher haben wir den Code sofort nach den Vorgaben des Partners geschrieben, die Spezifikationen erstellt, überarbeitet, getestet. In der Phase der Integrationstests stellte sich heraus, dass nicht alles, was in der Spezifikation geschrieben ist, der Realität entspricht - angefangen beim Format der Anforderungen bis hin zum Bestehen des Antrags.
Zum Beispiel erwarten wir laut Spezifikation beim Zugriff auf eine bestimmte Methode eine Antwort in einem bestimmten Format in der Antwort, legen die Verarbeitung für die Gültigkeit der empfangenen Antwort auf, gehen zu den Tests und erhalten plötzlich ein Array in der Antwort. Die Gründe erfahren wir von den Entwicklern des Partners. Sie beziehen sich auf veraltete Dokumentation. Wieder ein Kreis von Verbesserungen, Überprüfungen und Tests.
Sobald wir die Dokumentation und die Verbindungsdetails erhalten haben, führen wir den Prozess über den API-Client aus. In der Regel lädt der Tester die Spezifikation auf Postman hoch und simuliert den gesamten Geschäftsprozess des Sendens eines Kreditantrags. Er überprüft die beliebtesten Fälle mit unterschiedlichen Datensätzen für die Anforderung. Das heißt, es wird manuell ausgeführt, was die Anwendung dann tut.
In der Phase eines manuellen Laufs werden 80% der Ungenauigkeiten in der Dokumentation aufgedeckt. Wir beschreiben die Fehler und geben sie an den Partner weiter. Der Partner beseitigt entweder Ungenauigkeiten zu Hause oder stellt die Spezifikation fertig. Infolgedessen erhalten die Entwickler zu Beginn der Arbeit am Code eine Arbeitsdokumentation.
Beliebteste Diskrepanzen:
- falsches Anforderungsformat, Versprechen, json zu akzeptieren, es stellte sich heraus, dass Formulardaten benötigt wurden;
- Fehler in den Namen der Felder, die in der Anfrage übertragen werden sollen;
- Fehler in Feldformaten;
- Feldvalidierungsregeln sind nicht angegeben oder werden falsch angegeben.
- Einige Felder können ganz vergessen werden.
- fehlt oder unterscheidet sich von der tatsächlichen Beschreibung des Antwortformats der Methode;
- fehlerhafte Markierungen über die Pflichtfelder - „Sternchen“ können erscheinen, wenn das Feld tatsächlich nicht obligatorisch ist, und umgekehrt;
- oft nicht alle Zustände und Zustände dokumentiert, in denen sich das Objekt befinden kann;
- Diskrepanzen zwischen dem erwarteten und dem empfangenen Zustand der Objekte. Zum Beispiel erwarten wir irgendwann, dass sich die Anwendung im Status X befindet - und von der API erhalten wir tatsächlich Y.
Rezept für Glück: Vermeidung von API-Integrationsfehlern
Schreiben Sie eine Spezifikation für die Integration in Ihren Service. Wir haben zwei Tage damit verbracht, die Spezifikation in YAML zu entwickeln, aber jetzt sparen wir zehn Stunden bei Verbesserungen und Genehmigungen.
Wenn der Partner seine Spezifikation sendet, überprüfen Sie diese in der Checkliste. Sammeln Sie in der Checkliste Fragen, auf die Sie Antworten erhalten müssen. Verlassen Sie sich nicht auf Erfahrung und Erinnerung, verpassen Sie trotzdem etwas.
Halten Sie ein Glossar mit Begriffen bereit, um Verwechslungen mit Ihrem Partner zu vermeiden. Unsere Erfahrung hat gezeigt, dass Unterschiede sogar offensichtlich sein können.
Nehmen Sie die Aufgabe erst in die Entwicklung auf, wenn Sie vom Management der Integration mit einem Partner eine grundsätzliche Genehmigung erhalten haben. Die Idee ist offensichtlich, aber sie hilft uns, unnötige Arbeit zu vermeiden.
Öffnen Sie eine Checkliste, um die Einzelheiten des Zugriffs auf die API des Partners zu klären: Verbindungsdetails, Whitelist, Überprüfung des SSL-Zertifikats, Anforderungen an die Verkehrsverschlüsselung usw. Überprüfen Sie die Checkliste so bald wie möglich, um ein Verrutschen in der Endphase zu vermeiden.
Haben Sie eine Spezifikation - beeilen Sie sich nicht, sofort Code zu schreiben. Führen Sie den Prozess zunächst manuell über einen API-Client aus, z. B. über Postman. So werden Sie frühzeitig und mit geringen Ressourcen Fehler in der Spezifikation finden. Und sie werden es sein.