Come realizzare una buona API

categorie

API Design
Johanne Andersen ci racconta nel suo articolo Practical Advice to Good API Design come realizzare una buona Application Programming Interface. Per farlo ha preso spunto da un famoso googletalk video di Joshua Bloch: How to build good APIs and why it matters by .

Quali sono le caratteristiche di una buona API ?
- Facile da imparare
- Facile da usare, anche senza documentazione
- Difficile da usare in modo improprio
- Il codice che la utilizza deve essere di facile lettura e manutenzione
- Abbastanza potente da soddisfare i requisiti
- Facile da evolvere
- Adeguata al pubblico

Nella pratica:
- Una API dovrebbe fare una cosa e farla bene
- Una API dovrebbe essere più piccola possibile, ma non esagerare
- Non inserire i dettagli di implementazione nella API
- Ridurre al minimo l'accessibilità di tutto
- I nomi contano !
- La documentazione è importante
- Mai deformare una API per le prestazioni
- Ridurre al minimo i cambiamenti
- Creare sottoclassi solo dove ha senso
- Progettare e documentare per l'ereditarietà o vietarla
- Non far fare al client tutto ciò che il modulo potrebbe fare
- Applicare il principio della minima sorpresa
- Fail fast - Gli errori devono essere segnalati il più presto possibile dopo che si sono verificati.
- Fornire un accesso programmatico a tutti i dati disponibili sotto forma di stringa
- Sovraccaricare con cura
- Utilizzare i tipi di parametri e di ritorno appropriati
- Utilizzare un ordine di parametri coerente tra i vari metodi
- Evitare lunghe liste di parametri
- Evitare i tipi di restituzione che richiedono un'elaborazione ulteriore

API Cheat Sheet – What is an API, How it Works, and How to Choose the Right API Testing Tools

[via]

How To Design A Good API and Why it Matters

Add new comment

The content of this field is kept private and will not be shown publicly.

Full HTML

  • Web page addresses and email addresses turn into links automatically.
  • Lines and paragraphs break automatically.

Filtered HTML

  • Web page addresses and email addresses turn into links automatically.
  • Allowed HTML tags: <a href hreflang> <em> <strong> <cite> <blockquote cite> <code> <ul type> <ol start type='1 A I'> <li> <dl> <dt> <dd> <h2 id='jump-*'> <h3 id> <h4 id> <h5 id> <h6 id>
  • Lines and paragraphs break automatically.
CAPTCHA
This question is for testing whether or not you are a human visitor and to prevent automated spam submissions.