Hogyan tervezzünk API-t? - Magyarországi Web Konferencia 2013

@janoszen www.janoszen.com @neticle_hu www.neticle.hu

Hogyan tervezzünk API-t?


Mindenki API tervező

● API gondolkodásmód jobbá teszi a kódodat.

● Az API elősegíti a kódújrahasznosítást.


Üzleti előnyök

● A másik oldal hozza az ügyfeleket.

● A másik oldal pénzt, időt és energiát fordít a technológiád, terméked megtanulására.


Üzleti veszélyek

● Support requestek

● Rossz API => rossz PR

● EGY esélyed van jól megcsinálni.


De miért fontos NEKED?

● Jobb kódot írsz

● Moduláris, újrafelhasználható

● Öndokumentáló funkcionalitás


Ilyen a jó API

● Egyszerű megtanulni/használni...● ...akár dokumentáció nélkül is.

● Nem szivárogtat implementációs részleteket.

● Egyszerű bővíteni.


Hogyan fogjunk neki?

● Minimális funkciókészlet

● Valós igényeket mérjünk fel!

● Egy oldalas absztrakt

● Mutassuk meg sok embernek!


Írjunk klienst!

● Akár még az implementáció előtt is.

● Implementáció közbeni problémák.

● Teszteli az API-t.

● Írjunk több implementációt!


Dokumentáció

● Dokumentáljunk MINDENT!

● A dokumentáció nem helyettesíti az egyszerűséget.

● Tegyük elérhetővé nyilvánosan!


Bonyolultság

Ha bonyolult elmagyarázni, nem jó ötlet.


Nevezéktan

● Célközönség-specifikus!

● Dokumentáció nélküli használat.

● Túl hosszú függvénynevek


Nevezéktan

● Magánhangzók kihagyása

● Hibás angol

● Legyen konzisztens!


A legkisebb funkcionalitás

● Hozzáadni mindig lehet

● Elvenni nem


Szivárgás

● Szivárgás: amikor a háttérrendszer működése befolyásolja az API működését.

● Defacto szabvány lesz


Kedvességek

● Numerikus hibaüzenetek

● Struktúrált paraméterek

● Legkisebb meglepetés elve

● Legyen egyszerű használni, tesztelni


Adatformátum

● Időpontoknál figyeljünk az időzónára.

● A float nem alkalmas pénzösszegek leképezésére.

● Ha lehet, ne használjunk stringet.


REST API

● HTTP protokollon alapul

● Szemantikus

● Tetszőleges adatformátumot szállíthat.


REST API

GET /0.1/client/ HTTP/1.1Host: api.neticle.huAuthorization: api kulcs (RFC2617)Accept: application/json

HTTP/1.1 200 OKContent-Type: application/json

[{"id":1,"name":"Teszt Ugyfel 1"},{"id":2,"name":"Teszt Ugyfel 2"}]

Forrás: http://wiki.neticle.hu/


REST API

GET /0.1/client/1/ HTTP/1.1Host: api.neticle.huAuthorization: api kulcs (RFC2617)Accept: application/json

HTTP/1.1 200 OKContent-Type: application/json

[{"id":1,"name":"Teszt Profil 1"},{"id":2,"name":"Teszt Profil 2"}]

Forrás: http://wiki.neticle.hu/


SOAP

● Objektumokat visz át.

● Kötött adatformátum.

● Legtöbbször automatikusan generált sémaleírás.


SOAPPOST /InStock HTTP/1.1

Host: www.example.org

Content-Type: application/soap+xml; charset=utf-8

Content-Length: 299

SOAPAction: "http://www.w3.org/2003/05/soap-envelope"

<?xml version="1.0"?>

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">

<soap:Header>

</soap:Header>

<soap:Body>

<m:GetStockPrice xmlns:m="http://www.example.org/stock">

<m:StockName>IBM</m:StockName>

</m:GetStockPrice>

</soap:Body>

</soap:Envelope> Forrás: http://en.wikipedia.org/wiki/SOAP


Jó példa


Takeaway

● Tiszta nevezéktan

● Legkisebb meglepetés elve

● Minimális funkciókészlet

● Dokumentáció!


További tanulandó


Stalking lehetőségek

Pásztor János Neticle Technologies

Ikonok: http://www.iconarchive.com/show/social-networks-pro-icons-by-artbees.html

www.janoszen.com

@janoszen

fb.com/janoszen

youtube.com /user/janoszen

blog.neticle.hu

@neticle_hu

fb.com/neticle

Documents

Hogyan tervezzünk API-t? - Magyarországi Web Konferencia 2013