1. Hogyan tervezzünk API-t?
@janoszen
www.janoszen.com @neticle_hu
www.neticle.hu

2. 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

3. Ü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

4. Ü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

5. 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

6. 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

7. 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

8. Í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

9. 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

10. Bonyolultság
Ha bonyolult elmagyarázni, nem jó ötlet.
@janoszen
www.janoszen.com @neticle_hu
www.neticle.hu

11. 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

12. Nevezéktan
●
Magánhangzók kihagyása
●
Hibás angol
●
Legyen konzisztens!
@janoszen
www.janoszen.com @neticle_hu
www.neticle.hu

13. A legkisebb funkcionalitás
●
Hozzáadni mindig lehet
●
Elvenni nem
@janoszen
www.janoszen.com @neticle_hu
www.neticle.hu

14. 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

15. 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

16. 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

17. REST API
●
HTTP protokollon alapul
●
Szemantikus
●
Tetszőleges adatformátumot
szállíthat.
@janoszen
www.janoszen.com @neticle_hu
www.neticle.hu

18. REST API
GET /0.1/client/ HTTP/1.1
Host: api.neticle.hu
Authorization: api kulcs (RFC2617)
Accept: application/json
HTTP/1.1 200 OK
Content-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

19. REST API
GET /0.1/client/1/ HTTP/1.1
Host: api.neticle.hu
Authorization: api kulcs (RFC2617)
Accept: application/json
HTTP/1.1 200 OK
Content-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

20. 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

21. SOAP
POST /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>
@janoszen
Forrás: http://en.wikipedia.org/wiki/SOAP
www.janoszen.com @neticle_hu
www.neticle.hu

22. Jó példa
@janoszen
www.janoszen.com @neticle_hu
www.neticle.hu

23. Takeaway
●
Tiszta nevezéktan
●
Legkisebb meglepetés elve
●
Minimális funkciókészlet
●
Dokumentáció!
@janoszen
www.janoszen.com @neticle_hu
www.neticle.hu

24. További tanulandó
@janoszen
www.janoszen.com @neticle_hu
www.neticle.hu

25. Stalking lehetőségek
Pásztor János
Neticle Technologies
www.janoszen.com
blog.neticle.hu
@janoszen
@neticle_hu
fb.com/janoszen
fb.com/neticle
youtube.com
/user/janoszen
Ikonok: http://www.iconarchive.com/show/social-networks-pro-icons-by-artbees.html
@janoszen
www.janoszen.com @neticle_hu
www.neticle.hu