Upload
janos-pasztor
View
930
Download
0
Embed Size (px)
Citation preview
@janoszen www.janoszen.com @neticle_hu www.neticle.hu
Hogyan tervezzünk API-t?
@janoszen www.janoszen.com @neticle_hu www.neticle.hu
Mindenki API tervező
● API gondolkodásmód jobbá teszi a kódodat.
● Az API elősegíti a kódújrahasznosítást.
@janoszen www.janoszen.com @neticle_hu www.neticle.hu
Ü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.
@janoszen www.janoszen.com @neticle_hu www.neticle.hu
Üzleti veszélyek
● Support requestek
● Rossz API => rossz PR
● EGY esélyed van jól megcsinálni.
@janoszen www.janoszen.com @neticle_hu www.neticle.hu
De miért fontos NEKED?
● Jobb kódot írsz
● Moduláris, újrafelhasználható
● Öndokumentáló funkcionalitás
@janoszen www.janoszen.com @neticle_hu www.neticle.hu
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.
@janoszen www.janoszen.com @neticle_hu www.neticle.hu
Hogyan fogjunk neki?
● Minimális funkciókészlet
● Valós igényeket mérjünk fel!
● Egy oldalas absztrakt
● Mutassuk meg sok embernek!
@janoszen www.janoszen.com @neticle_hu www.neticle.hu
Í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!
@janoszen www.janoszen.com @neticle_hu www.neticle.hu
Dokumentáció
● Dokumentáljunk MINDENT!
● A dokumentáció nem helyettesíti az egyszerűséget.
● Tegyük elérhetővé nyilvánosan!
@janoszen www.janoszen.com @neticle_hu www.neticle.hu
Bonyolultság
Ha bonyolult elmagyarázni, nem jó ötlet.
@janoszen www.janoszen.com @neticle_hu www.neticle.hu
Nevezéktan
● Célközönség-specifikus!
● Dokumentáció nélküli használat.
● Túl hosszú függvénynevek
@janoszen www.janoszen.com @neticle_hu www.neticle.hu
Nevezéktan
● Magánhangzók kihagyása
● Hibás angol
● Legyen konzisztens!
@janoszen www.janoszen.com @neticle_hu www.neticle.hu
A legkisebb funkcionalitás
● Hozzáadni mindig lehet
● Elvenni nem
@janoszen www.janoszen.com @neticle_hu www.neticle.hu
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
@janoszen www.janoszen.com @neticle_hu www.neticle.hu
Kedvességek
● Numerikus hibaüzenetek
● Struktúrált paraméterek
● Legkisebb meglepetés elve
● Legyen egyszerű használni, tesztelni
@janoszen www.janoszen.com @neticle_hu www.neticle.hu
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.
@janoszen www.janoszen.com @neticle_hu www.neticle.hu
REST API
● HTTP protokollon alapul
● Szemantikus
● Tetszőleges adatformátumot szállíthat.
@janoszen www.janoszen.com @neticle_hu www.neticle.hu
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/
@janoszen www.janoszen.com @neticle_hu www.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/
@janoszen www.janoszen.com @neticle_hu www.neticle.hu
SOAP
● Objektumokat visz át.
● Kötött adatformátum.
● Legtöbbször automatikusan generált sémaleírás.
@janoszen www.janoszen.com @neticle_hu www.neticle.hu
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
@janoszen www.janoszen.com @neticle_hu www.neticle.hu
Jó példa
@janoszen www.janoszen.com @neticle_hu www.neticle.hu
Takeaway
● Tiszta nevezéktan
● Legkisebb meglepetés elve
● Minimális funkciókészlet
● Dokumentáció!
@janoszen www.janoszen.com @neticle_hu www.neticle.hu
További tanulandó
@janoszen www.janoszen.com @neticle_hu www.neticle.hu
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