Creazione della definizione dell'API pubblica per l'applicazione esistente

1. D: tutte le classi dovrebbero far parte dell'API pubblica o dovremmo contrassegnarle come pubbliche o contrassegnare quelle che non lo sono?
   
   A: Fai una chiara distinzione per gli utenti delle tue classi - contrassegna quelli che sono destinati all'uso da parte di sviluppatori "esterni" E contrassegna quelli che non lo sono (quest'ultimo non ti garantirà da problemi di retrocompatibilità in futuro, ma si spera che diventino meno frequenti e meno dolorosi)
2. D: I metodi protetti devono far parte dell'API (se qualcuno crea una classe personalizzata derivata, si affideranno a esso) e in tal caso - dovremmo contrassegnare in modo esplicito quelli che non vogliamo che gli altri uso, o quelli che stiamo permettendo di usare?
   
   A: I metodi protetti destinati all'uso "esterno" nella classe personalizzata derivata devono far parte dell'API. Il resto dei metodi protetti dovrebbe essere dichiarato come non supportato (questo non vi garantirà da strani problemi di compatibilità con le versioni precedenti in futuro, ma si spera che li renderà meno frequenti e meno dolorosi)
   
3. D: Anche le proprietà pubbliche devono far parte dell'API? Che ne dici di quelli protetti?
   
   A: tutte le proprietà destinate all'uso da codice esterno devono far parte dell'API. Tutti gli altri dovrebbero essere chiaramente dichiarati come non supportati (anche in questo caso, questo non garantisce bla bla ...)
4. D: Se vogliamo apportare modifiche / refactoring che non possono essere retrocompatibili (ad esempio, la vecchia API era troppo buggata o non si adattava più all'app), come ci si avvicina di più?
   
   A: L'approccio migliore consiste nell'avere un piano di backup per il caso se risulta impossibile accettare particolari modifiche incompatibili per te (ad esempio, se ciò porterà a relazioni immediatamente violente con gli sviluppatori del cliente che ti porta 90% di reddito)
   
5. D: Se vogliamo rimuovere completamente qualche classe / metodo, quale dovrebbe essere il processo? Immagino che vogliamo prima renderlo deprecato e poi rimuoverlo nelle versioni successive, ma per esempio dovremmo dare qualche avvertimento quando deprecato, ma viene comunque chiamata la funzionalità esistente? Il problema qui è che non possiamo avvisare in modo aggressivo in quanto potrebbe interrompere l'applicazione, ma se non siamo aggressivi, le persone ignorerebbero il marchio deprecato fino a quando non rimuoveremo il vecchio pezzo API e quindi si verifichino gravi problemi.
   
   A: Deprecate, quindi pianifica la rimozione: questa è una pratica piuttosto standard, perché deviare? Sii preparato per i casi in cui la rimozione richiede più tempo del previsto o risulta inaccettabile per te.

Any other advice is welcome too

Stabilire e mantenere la Guida per gli sviluppatori. Meglio avere un buon scrittore tecnico per mantenerlo.

Stabilisci e incoraggia la comunità di "estranei" usando la tua API. Supportateli fornendo tracker, forum (s), mailing list (s), wiki, wiki, qualsiasi cosa.

Offri una certificazione per il codice "esterno" che utilizza la tua API. "L'applicazione MegaVideoSharing non è sicura perché usa il metodo non supportato temporaryHack nella classe Workaround . Soluzione consigliata: usa il metodo permanentFacade dalla classe AntiCorruptionLayer invece" - roba del genere.

• "Le API pubbliche, come i diamanti, sono per sempre. Hai una possibilità di farlo bene, quindi dai il massimo ..." (Joshua Bloch, Come progettare una buona API e perché è importante )

Gestisco un elenco di risorse di progettazione API, inclusi libri consigliati, tutorial video e articoli online qui

link

Ferenc

Suggerisco di acquistare questo libro:

RESTful Web Services Cookbook: Solutions for Improving Scalability and Simplicity by Subbu Allamaraju

Mi è stato detto da un livello senior di Google che molte domande di interviste tecniche su Google (da parte dei team API) sono state prese direttamente da questo libro. Pensiero, non l'ho ancora letto, lavoro principalmente sul lato client in questi giorni. Probabilmente finirò col leggere quel libro solo per curiosità personale.