API, die Sie zum Weinen bringt

Was erwartet Sie?

Ziel ist es, Entwicklern zu zeigen, mit welchen Problemen ihre API-Benutzer am Beispiel der Arbeit mit verschiedenen CRM-Systemen konfrontiert sind.

Um mein Gesicht zu schützen, werde ich die Namen der Teilnehmer in diesem Artikel nicht bewerben.
Außerdem bin ich - ich bin kein Programmierer der Freundin meiner Mutter, also nehme ich nicht meine Schlussfolgerungen für die einzig wahre Option.

Eyeliner

Es war einmal ein hoffnungsvoller Junge. Dieser Junge hatte nichts in seinem Leben als die Arbeit in der technischen Unterstützung von Buchhaltungsprogrammen. Er kochte lange in diesem Kessel, bis er an einem Tag sein Dach abriss, die Hauptmerkmale des Wirts sendete und auf der Suche nach Perspektiven ging.

Der Junge träumte immer davon, ein cooler Entwickler zu werden, er würde außergewöhnliches Geld verdienen, am liebsten in der Basurm-Währung. Und deshalb war er parallel zur Arbeit an der Erstellung seiner Website beteiligt, wobei er Technologien einsetzte, die es in jenen Jahren noch nicht gegeben hatte. Dank dessen fand er einen neuen Besitzer, der ihm einen Job in seinem geliebten Geschäft gab, mit einem guten Gehalt und mit unerhörten Aussichten.

Seitdem lebte der Junge, lebte und machte es gut. Und er kannte die Sorgen und Nöte nicht ... oder wusste er es? Lass es uns herausfinden!

Ich habe einen Job in einem Business Intelligence-Unternehmen bekommen. Und welche Art von Analyse kann ohne Daten sein? Aus diesem Grund hatte das Unternehmen ein separates Team und eine Abteilung, die Daten von Kundenstandorten sammelte, um Umsatzpläne aus Werbekanälen und anderen Quellen zu erstellen. Was die Besonderheiten betrifft, bestand meine Aufgabe darin, unseren Zähler auf den Websites zu installieren, Daten über den Besucher zu sammeln und Anwendungen aus Formularen, Online-Chats, Rückrufen usw. zu erstellen. in ihren CRM-Systemen. Davon haben unsere Analysen in Zukunft Informationen über den Status und die Höhe des Verkaufs abgerufen.

Und da die Erstellung von Anwendungen in CRM durch das Umschließen unseres Systems vereinfacht wurde, das die Anwendung und den Client mithilfe von 1 Anforderung erstellt hat, einschließlich der Übernahme von Diensten von Drittanbietern, scheint dies nicht kompliziert zu sein. Aber wie Sie verstehen sollten, unterscheidet sich eine solche Logik nicht in der Flexibilität. Und wenn der Kunde etwas anderes benötigte, musste er bereits den Komfortmodus ausschalten und die Ärmel hochkrempeln, um direkt mit der API des gewünschten Systems zu arbeiten. Und manchmal, wenn ich mit der nächsten problematischen API arbeite, denke ich, wäre es besser, in diesen zu bleiben. unterstützen ...

Problem Nr. 1: Mangel an Methoden / Daten

Vielleicht ist das häufigste Problem, auf das ich in meinem Leben gestoßen bin, das Fehlen der Fähigkeit, die Daten abzurufen, die ich in der Schnittstelle benötige. Konflikte mit Kunden traten immer wieder auf, weil wir nicht jeden Tag etwas auf den Bildschirmen ihrer Monitore sehen können.

Zum Beispiel kam vor ein paar Jahren ein ziemlich großer Kunde zu uns, der in CRM-Dateien speichern musste, die ihm Kunden von den Formularen auf der Site senden. Eine gewöhnliche Aufgabe, aber es gab keine Möglichkeit der Umsetzung, und bis heute nicht!

Der Fehler für den Client war inakzeptabel, und am Ende mussten wir Dateien hochladen, um JS-Anforderungen von der Schnittstelle zu emulieren.

Ich muss sagen, dass dieses CRM, die Autorisierung in der API, auch in der Schnittstelle autorisiert, was für mich eine ziemlich seltsame Lösung ist. Dank dessen mussten wir jedoch nicht die übliche Autorisierung emulieren. Oder war es gedacht ...?

Ein weiterer Fall mit dem gleichen CRM ist nicht allzu lange her. Es war notwendig, den aktuell aktiven Application Manager zur Verantwortung zu ziehen. Und wie Sie bereits verstanden haben, gibt die API keine Informationen über die Manageraktivität an uns zurück. Das Paradoxe ist jedoch, dass ihre JS-API zurückkehrt. Infolgedessen musste ich eine JS-Anwendung schreiben, eine Art Vermittler, mit der ich den Server über aktive Manager im Moment informierte.

Lösung:
In unserem Team ist es üblich, eine öffentliche API-Methode für die Schnittstelle zu erstellen und über diese bereits mit dem Server zu interagieren. Dadurch wird das Problem der Nichtübereinstimmung zwischen den technischen Funktionen der Schnittstelle und der öffentlichen API beseitigt.

Problem Nummer 2: das Fehlen eines einheitlichen Stils von Anfragen / Antworten

Ein sehr häufiges Problem, auch in großen westlichen CRMs. Angenommen, wir müssen eine Liste der Bestellungen für einen Monat abrufen, dann stellen wir fest, dass das System die Anzahl der Elemente im Upload begrenzt. Um durch die Seiten zu navigieren, müssen Sie den Offset-Parameter verwenden. Okay, wir haben die Methode zum Laden von Aufträgen und separat die Hilfsmethode zum Paging implementiert.
Jetzt müssen wir die Liste der Clients entladen, eine neue Methode zusammen mit der zuvor geschriebenen Paginierungsmethode implementieren und ... Wir bekommen einen Fehler. Da PM und die Entwickler entschieden haben, dass Offset zu einfach klingt, lassen Sie es jetzt vid-offset sein.

Natürlich übertreibe ich, ich kann nicht wissen, was passiert ist, als sie diese API geschrieben haben. Dies ist aber immerhin ein PM-Fehler, da er nicht angegeben hat, wie er bereits in anderen Methoden implementiert wurde. Und auch ein Fehler der Entwickler, derer, die eine neue Methode geschrieben haben, und derer, die überprüft wurden. Derzeit ist jeder, der seine API verwendet, gezwungen, Krücken in seinen Anwendungen zu erstellen.

Lösung:
Jede neue API-Methode sollte, wenn möglich, der Struktur der bestehenden entsprechen. Der technische Leiter (oder mangels des ersten Teamleiters) kann eine Vorschrift erstellen, eine Art Codestil, nach der APIs entwickelt werden müssen, ohne dass alle Entwickler damit vertraut gemacht werden müssen. Wenn das Problem bereits besteht, ist es nach Möglichkeit besser, eine Krücke auf Ihre Seite zu legen, als Tausende Ihrer Kunden dazu zu zwingen, dies auf Ihre Seite zu tun.

Problem Nummer 3: Mangelhafte Dokumentation oder Mangel daran

Die Dokumentation ist eine Entwicklerreferenz. Wir stoßen oft auf Situationen, in denen wir gefragt werden, ob eine bestimmte Funktion implementiert werden kann. Und wenn wir uns nicht erinnern oder die Antwort nicht kennen, öffnen Sie sofort die Dokumentation. Informationen in einem guten Verzeichnis zu finden, dauert ein paar Minuten, während Sie in einem überlasteten Verzeichnis eine halbe Stunde lang graben können und dennoch keine eindeutige Antwort erhalten.

In einigen fortgeschrittenen Fällen ist es einfach unmöglich, im öffentlichen Bereich zu finden. Wenn Sie eine aktuelle Liste der Methoden benötigen, wenden Sie sich an den technischen Support. Und dann müssen Sie noch prüfen, ob dort etwas Neues aufgetaucht ist, das wir ein paar Kunden gefragt haben ...

Lösung:
Ich werde einige Punkte nennen, die für mich die Qualitätsdokumentation charakterisieren:

• Suche nach Namen, Beschreibung und Methodenparametern
• korrekte Beschreibung des Zwecks der Methode
• Liste der akzeptierten Parameter mit Typ und Beschreibung
• Liste der zurückgegebenen Parameter mit Typ und Beschreibung
• Beispiel anfordern
• Antwortbeispiel
• mögliche Fehlercodes mit einer Beschreibung
• eine Sandbox, in der Sie im Entwurfsmodus mit Anforderungen "herumspielen" können
• Änderungsverlauf aller API-Methoden als Kurzreferenz

Problem Nummer 4: Autorisierungsfahrräder

Sie kennen dieses wunderbare Gefühl, wenn Sie die Dokumentation eines neuen Systems öffnen, und dort wird im Abschnitt zur Autorisierung eine Reihenfolge von drei Methoden beschrieben, um einen Schlüssel zu erhalten, der nur für eine Anfrage gültig ist ...? Also habe ich es nicht.

Es bleibt mir ein Rätsel, warum Entwickler Oauth 2.0 zugunsten ihrer Motorräder aufgeben? Und okay, wenn die Autorisierung auf einen konstanten Token beschränkt ist, ist hier die gesamte Autorisierungskette ...

Lösung:
Sie sollten Ihr Fahrrad nicht neu erfinden, wenn es bereits fertige Standards gibt. Für diese Standards verfügen Entwickler bereits über eigene Komponenten für die einfache Autorisierung.

Nachwort

Ich habe über 4 Probleme gesprochen, auf die ich zu Beginn meiner Reise bis heute gestoßen bin. Ich habe versucht, ihre Lösungen bereitzustellen, aber es liegt an Ihnen, zu entscheiden, ob sie gut sind oder nicht. Am Ende hat jeder von uns seine eigene Denkarchitektur.

Also, ich danke allen, die bisher gelesen haben! Dies ist mein erster Artikel, und wenn er informativen Wert für Sie hatte, werde ich gerne die Artikelserie über mein Leiden mit der API fortsetzen.

Und natürlich freue ich mich über die Meinung von Experten in den Kommentaren.

Alles für das kommende Jahr 2020!