Die Spezifikationen, die uns prägen

Als Entwickler bin ich faul. Wenn jemand eine Software entwickelt hat, die ein Problem löst, das ich habe, möchte ich sie benutzen. Ich sollte in der Lage sein, sofort loszulegen und mich ohne große Einmischung schnell in eine neue Bibliothek einzuarbeiten.

Als Initiative Lead für Nexmo's Server SDK Team war es eines meiner Ziele, sicherzustellen, dass wir den Entwicklern, die unsere SDKs verwenden, die bestmögliche Erfahrung bieten. Was nützt ein SDK, wenn die Nutzung so mühsam ist wie das Durchforsten der Dokumentation und das Ausführen von HTTP-Anfragen? Unser Team möchte dafür sorgen, dass Sie Ihre Arbeit - die Erstellung von Software - schneller erledigen können.

Vor kurzem hat sich das Team zusammengesetzt und beschlossen, die bestehenden Server SDK Specs (früher Client SDK Specs genannt) zu überprüfen, um zu sehen, wie sie sich halten. Die Spezifikationen wurden im Jahr 2016 geschrieben, als Nexmo begann, kritischer darüber nachzudenken, wie wir unsere Software schreiben. Im Jahr 2020 unterhalten wir nun sechs verschiedene Sprach-SDKs, wobei jede Sprache ihre eigenen Macken hat. Was müssen wir heute anders machen als vor Jahren?

Weniger RFC, mehr Flexibilität

Der erste Schritt war die Abschaffung eines Großteils der RFC-inspirierten Sprache. Die Begründung dafür war recht einfach: RFCs bieten eine bekannte Struktur und eine vereinbarte Formulierung. Dank der RFC 2119wurden Wörter wie MUST, MUST NOT, SHOULD, SHOULD NOTund andere haben alle ihre eigenen Definitionen und setzen Erwartungen an die Art und Weise, wie RFCs geschrieben werden. Wenn jemand ein neues Spezifikationsdokument erstellen würde, wären diese Wörter absolut sinnvoll.

Vier Jahre und fünf weitere SDKs später war das Dokument nicht nur in Bezug auf die Funktionalität, sondern auch auf die direkte Implementierung ziemlich streng geworden. Es beschrieb nicht nur das Verhalten, sondern auch, wie die API-Clients strukturiert sein sollten. Dies führte zu einer natürlichen Spaltung in der Art und Weise, wie einige SDKs entwickelt wurden, und zwang andere SDKs, Dinge auf eine nicht sehr sprachliche Art und Weise zu tun. Sollte ein Ruby-SDK wie eine NodeJS-Bibliothek aussehen und funktionieren?

Wahrscheinlich nicht.

Wir haben also einen Großteil der Sprache um spezifische Sprachkonstrukte herum entfernt, aber die übergreifenden Ziele und Zwecke verschiedener Ideen die unserer Meinung nach ein SDK einfach zu benutzen machen. Errors und Exceptions folgen immer noch der Idee, dass eine Bibliothek explizite Server- oder Response-Exceptions auslösen sollte, während die Anweisungen zur Benennung von Dingen auf "hier ist eine Liste von Verben, die Sie verwenden sollten" reduziert wurden. Die Spezifikation schreibt keine direkten Aufrufe von Methoden mehr vor, sondern empfiehlt eine konsistente Benennung.

Die Spezifikation ist viel weniger daran interessiert, die SDKs zu einer homogenen Erfahrung zu machen, und drängt nun darauf, den Erwartungen der Sprache und den besten Praktiken zu entsprechen. Im Laufe der Zeit bedeutet dies, dass sich unsere öffentlichen SDK-APIs ändern werden, aber so, wie Sie als Entwickler der Sprache X es erwarten. Wir möchten, dass die SDKs eine Erfahrung bieten, die Sie mit jeder gut konstruierten Bibliothek Ihrer Sprache machen würden.

Abstrahieren Sie die HTTP-Eigenschaft weg

Das Tolle an Nexmo ist, dass jeder sofort mit der Nutzung unserer API beginnen kann, indem er einfach eine Webadresse anklickt. Das Internet hat dazu beigetragen, dass es möglich ist, schnell mit Maschinen auf der ganzen Welt zu interagieren, indem man ein Standardprotokoll, HTTP, und eine einfache Textschnittstelle über JSON und XML verwendet. Wir können verschiedene Dienste wie nie zuvor miteinander verbinden.

Aber warum müssen Sie, wenn Sie Text-to-Speech in einem Anruf abspielen müssen, eine $talk->put()? Semantisch gesehen macht das keinen Sinn.

Ja, Nexmo bietet eine großartige API, aber wenn Sie Ihre Software entwickeln, sollten Sie sich nicht wirklich darum kümmern, was wir sind. Wenn Sie Text-to-Speech in einen Anruf einspielen wollen, $call->playTextToSpeech("Hello World") ist so viel klarer über seine Absichten. Dies kann eine HTTP PUT Anfrage stellen, um die Arbeit zu erledigen, aber es gibt keinen Grund, warum wir unsere Methoden nach HTTP-Methoden benennen müssen.

Wir haben die Verben und Benennungskonventionen auf eine Liste von Aktionen reduziert, die Sie durchführen würden, um Ihre Arbeit zu erledigen, nicht um einen HTTP-Client zu schreiben. Entwickler verwenden SDKs, um die von ihnen verwendeten Dienste von Drittanbietern zu abstrahieren, also sollten wir diese Abstraktion mit unseren Namenskonventionen fortsetzen. Letzten Endes interessiert es niemanden, ob wir ein PUT oder ein POST verwenden, sie wollen nur eine Aktion finden und ausführen.

Bequemlichkeit vor allem anderen

Ich möchte sicherstellen, dass unsere SDKs nicht nur all die verschiedenen Möglichkeiten der Interaktion mit unserer Plattform bieten, sondern auch, dass die Schnittstelle leicht zu verstehen und einfach zu bedienen ist. Unsere SDKs sollen Ihnen helfen, Ihr Problem zu lösen, indem sie die zu erledigende Arbeit eindeutig beschreiben und gleichzeitig die Standardformulierungen, die mit der Arbeit einhergehen können, vermeiden helfen.

Wenn wir zu unserem Beispiel der Wiedergabe von Text-to-Speech in einen bestehenden Anruf zurückkehren, ist unser derzeitiger Weg aus Sicht der Klarheit und der Semantik ein wenig stumpf. Wenn man herausfinden will, wie man etwas in unserem SDK macht, sollte das eindeutig sein, aber auch schnell zu machen. Ich möchte nicht, dass ein Entwickler in sechs Monaten zu seinem Code zurückkehrt und versucht herauszufinden, warum talk() ein Objekt zurückgibt, anstatt eine Aktion auszuführen. Ich möchte, dass der Entwickler seinen eigenen Code leicht lesen kann und jederzeit genau weiß, was passiert.

// Current, pull a Talk object out of a specific call
$talk = $client->calls['abcd-123']->talk();
// Set the text
$talk->setText(TEXT);
// PUT the text back to the API
$talk->put();

// In the future, we will just find a specific call
$call = $client->calls()->find('abcd-123');
// And play Text to Speech into it
$call->playTextToSpeech("All your base are belong to us");

Die Zukunft

Das Server-SDK-Team geht derzeit alle unsere Mainline-SDKs durch (NodeJS, Java, Python, .NET, Rubyund PHP) und überprüfen sie anhand der neuen Spezifikation. Wir haben einige aufregende Änderungen vor uns, da wir uns auf die Erfahrung der Entwickler mit unseren SDKs konzentrieren. Wir möchten allen unseren Kunden die gleiche Benutzerfreundlichkeit bieten, die sie schon immer von unseren SDKs erwartet haben, und das auf eine modernere, saubere Art und Weise.

Wie immer freuen wir uns über das Feedback unserer Kunden. Wir entwickeln diese Software, um Ihr Leben einfacher zu machen. Wenn Sie uns auf einer Konferenz oder einem Treffen sehen, lassen Sie uns wissen, wie es uns geht! Gibt es etwas, das Sie gerne in unseren SDKs sehen würden? Sprechen Sie uns an auf Github und lassen Sie uns wissen, welche Funktionen Sie vermissen.