Kreatív lustaság engedélyezve: API tervezés egyszerűen, RAML-lel

Az API tervezés kezdetben a szoftverfejlesztő szakemberek feladata volt, de mára teret nyert a “szép” API-k mozgalma, vagyis az a cég tehet szert üzleti előnyre, amelyik szabályos, érthető, szépen dokumentált API-kat tesz publikussá.

A szoftvervilágban a skálázódási és integrációs lehetőségek egyik kulcsa a megfelelő illesztő felületek (interface-ek) megléte, azok definiálása, dokumentálása és nyilvánossá tétele. A “mobile first”, vagyis a “készítsünk először mobil app-ot (és csak azután webes felületet)” mozgalomhoz hasonlóan, azt erősen támogatva jött létre az “API first”, azaz “először az API-t készítsük el”- szemlélet, mellyel az API-k definiálása a szoftverfejlesztés folyamatában az első lépések egyikévé lépett elő.

Az API tervezés kezdetben a szoftverfejlesztő szakemberek feladata volt. Érthető, hiszen ők voltak a legközelebb az egyes komponensekhez, az integrációs feladatokat is ők maguk végezték.

Az üzleti oldal által diktált követelmények és elvárások azonban  megváltoztatták a status quo-t, az illesztő felületek nyilvánossá tételében már az üzleti oldal is erősen érdekeltté vált.

Olyannyira, hogy elindult a “szép” API-k mozgalma, vagyis az a cég tehet szert üzleti előnyre, amelyik szabályos, érthető, szépen dokumentált API-kat tesz publikussá.

Az API egyfajta “szerződés”, amely biztosítja, hogy bár a háttérrendszerek kódja változhat (az összekapcsolódó rendszerek bármelyikében), a közös kommunikációs felület, az interfész a dokumentáció alapján kötött.

A RAML (RESTful API Modeling Language) egy REST API-k tervezésére szolgáló leíró nyelv.

Egyszerű nyelvtana lehetővé teszi, hogy akár üzleti elemzők is létrehozhassanak API definíciókat, melyet megoszthatnak a fejlesztő csapatokkal, egyéb üzleti területekkel.

A RAML ezen a területen különösen hasznos, hiszen rövid idő alatt, minimális ráfordítással hozható létre egy szépen dokumentált, bemutatható API.

A RAML előnyei

A RAML felhasználóbarát: egyszerű szöveges file-ban írható le az API felépítése. Ahogy gépeled, a szemed előtt alakul és formálódik az API.

A RAML támogatja a prototípus építést: azt hinni, hogy az API, amit tervezel megfelel a felhasználói igényeknek sajnos már nem elég. Meg kell győződnöd róla – miközben építed. A RAML file-okat egyszerűen megoszthatod, átküldheted a potenciális felhasználóknak, így idejekorán kiderülnek a módosítási kérelmek és újabb igények.

A RAML-lel tökéletesítheted az API-t még az élesítés előtt: a teljes fejlesztési életciklust lejátszhatod egyszerű szöveges állományokkal, mielőtt élesítenél. Tervezés, prototípus készítés, tesztelés, visszajelzések begyűjtése, finomhangolás. Így, még élesítés előtt kiderülnek a hibák.

RAML és YAML

RAML file-ok készítéséhez a YAML szintakszist kell betartani. A YAML (YAML Ain’t Markup Language) specifikációja az alábbi linken érhető el: http://yaml.org/spec/1.2/spec.html

A YAML emberek és gépek számára is egyaránt könnyen olvasható és értelmezhető formátum. Egyszerű szöveges file, amelyben az adatok megfelelő szintakszis alapján sorokban szerepelnek.

Vegyünk egy egyszerű példát:

A RAML file a YAML 1.2 specifikációnak megfelelően egy kötelező deklarációs sorral kezdődik, ez a “#%RAML”.

A fenti két sort mentsük el myAPI.raml néven. A .raml filekiterjesztés biztosítja, hogy a megfelelő feldolgozó programok RAML szintakszist várnak el a file-on belül és a megfelelő értelmezővel dolgozzák fel.

Előző cikkünkben a Site Reliability Engeneer pozíció eredetét és feladatait vettük sorra, következő cikkünkben pedig a https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md/ alapján elkezdünk egy saját API-t építeni a RAML 1.0 specifikációját követve.