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

...
Ü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é...
Üzleti veszélyek
●

Support requestek

●

Rossz API => rossz PR

●

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

@janoszen

www.janos...
De miért fontos NEKED?
●

Jobb kódot írsz

●

Moduláris, újrafelhasználható

●

Öndokumentáló funkcionalitás

@janoszen

w...
Ilyen a jó API
●

Egyszerű megtanulni/használni...

●

...akár dokumentáció nélkül is.

●

●

Nem szivárogtat implementáci...
Hogyan fogjunk neki?
●

Minimális funkciókészlet

●

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

●

Egy oldalas absztrakt

●

Mutassuk m...
Írjunk klienst!
●

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

●

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

●

Teszteli az API-t.

●

Írj...
Dokumentáció
●

●

●

Dokumentáljunk MINDENT!
A dokumentáció nem helyettesíti az
egyszerűséget.
Tegyük elérhetővé nyilváno...
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.jan...
Nevezéktan
●

Magánhangzók kihagyása

●

Hibás angol

●

Legyen konzisztens!

@janoszen

www.janoszen.com @neticle_hu

www...
A legkisebb funkcionalitás

●

Hozzáadni mindig lehet

●

Elvenni nem

@janoszen

www.janoszen.com @neticle_hu

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

@janosze...
Kedvességek
●

Numerikus hibaüzenetek

●

Struktúrált paraméterek

●

Legkisebb meglepetés elve

●

Legyen egyszerű haszná...
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 h...
REST API
●

HTTP protokollon alapul

●

Szemantikus

●

Tetszőleges adatformátumot
szállíthat.
@janoszen

www.janoszen.com...
REST API
GET /0.1/client/ HTTP/1.1
Host: api.neticle.hu
Authorization: api kulcs (RFC2617)
Accept: application/json
HTTP/1...
REST API
GET /0.1/client/1/ HTTP/1.1
Host: api.neticle.hu
Authorization: api kulcs (RFC2617)
Accept: application/json
HTTP...
SOAP
●

Objektumokat visz át.

●

Kötött adatformátum.

●

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

@janoszen

www....
SOAP
POST /InStock HTTP/1.1
Host: www.example.org
Content-Type: application/soap+xml; charset=utf-8
Content-Length: 299
SO...
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....
További tanulandó

@janoszen

www.janoszen.com @neticle_hu

www.neticle.hu
Stalking lehetőségek
Pásztor János

Neticle Technologies

www.janoszen.com

blog.neticle.hu

@janoszen

@neticle_hu

fb.co...
Upcoming SlideShare
Loading in …5
×

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

1,236 views

Published on

0 Comments
4 Likes
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total views
1,236
On SlideShare
0
From Embeds
0
Number of Embeds
96
Actions
Shares
0
Downloads
11
Comments
0
Likes
4
Embeds 0
No embeds

No notes for slide

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

  1. 1. Hogyan tervezzünk API-t? @janoszen www.janoszen.com @neticle_hu www.neticle.hu
  2. 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. 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. 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. 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. 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. 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. 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. 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. 10. Bonyolultság Ha bonyolult elmagyarázni, nem jó ötlet. @janoszen www.janoszen.com @neticle_hu www.neticle.hu
  11. 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. 12. Nevezéktan ● Magánhangzók kihagyása ● Hibás angol ● Legyen konzisztens! @janoszen www.janoszen.com @neticle_hu www.neticle.hu
  13. 13. A legkisebb funkcionalitás ● Hozzáadni mindig lehet ● Elvenni nem @janoszen www.janoszen.com @neticle_hu www.neticle.hu
  14. 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. 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. 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. 17. REST API ● HTTP protokollon alapul ● Szemantikus ● Tetszőleges adatformátumot szállíthat. @janoszen www.janoszen.com @neticle_hu www.neticle.hu
  18. 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. 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. 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. 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. 22. Jó példa @janoszen www.janoszen.com @neticle_hu www.neticle.hu
  23. 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. 24. További tanulandó @janoszen www.janoszen.com @neticle_hu www.neticle.hu
  25. 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

×