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:
#%RAML 1.0 title: My API
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 http://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.