Creating public API definition for existing application

Question

Let's say there's a successful open source application (written in PHP if it matters), which provides its users with multiple ways to extend it (think about something like Drupal or Wordpress, lots of custom plugins, etc.). Now let's say unfortunately there's no formal definition what constitutes the public API for this application, and we want to define such a public API, so that we could a) control application development and refactoring and know we don't screw up the extensions with the next version and b) give extenders some idea what they can safely use and what they better not use. So the question is - how is it best to approach this and what should be there? For example, some specific questions:

1. Should all classes be part of public API or should we mark those are public or mark those that aren't?
2. Should protected methods be part of the API (if somebody creates derived custom class, they will be relying on it) and if so - should we be explicitly marking those that we don't want others to use, or those we're allowing to use?
3. Should public properties be part of the API too? How about protected ones?
4. If we want to make change/refactoring which can't be backwards-compatible (e.g. old API was too buggy or doesn't really fit in the app anymore), how we best approach it?
5. If we want to remove some class/method completely, what should be the process? I imagine we want to make it deprecated first, and then remove in later versions, but for example should we give some warnings when deprecated, but still existing functionality is called? The problem here is we can't warn to aggressively as it may break the application, but if we're not agressive people would ignore the deprecated mark until we remove the old API piece and then they'd get major breakage.

Any other advice is welcome too, and references for good papers/examples/etc. on the topic.

Answer 1

1. Q: Should all classes be part of public API or should we mark those are public or mark those that aren't?
    
   A: Do the clear distinction for users of your classes - mark those that are intended for use by "outside" developers AND mark those that aren't (the latter won't guarantee you from weird backward-compatibility issues in future but hopefully will make these less frequent and less painful)
    
2. Q: Should protected methods be part of the API (if somebody creates derived custom class, they will be relying on it) and if so - should we be explicitly marking those that we don't want others to use, or those we're allowing to use?
    
   A: Protected methods intended for "outside" use in derived custom class should be part of the API. The rest of protected methods should be stated as unsupported (this won't guarantee you from weird backward-compatibility issues in future but hopefully will make these less frequent and less painful)
    
3. Q: Should public properties be part of the API too? How about protected ones?
    
   A: All the properties intended for use by outside code should be part of the API. All others should be clearly declared as unsupported (again, this won't guarantee blah blah...)
    
4. Q: If we want to make change/refactoring which can't be backwards-compatible (e.g. old API was too buggy or doesn't really fit in the app anymore), how we best approach it?
    
   A: The best approach is to have a backup plan for the case if particular incompatible change turns out unacceptable for you (eg if it will lead to immediately breaking relations with developers at customer who brings you 90% income)
    
5. Q: If we want to remove some class/method completely, what should be the process? I imagine we want to make it deprecated first, and then remove in later versions, but for example should we give some warnings when deprecated, but still existing functionality is called? The problem here is we can't warn to aggressively as it may break the application, but if we're not aggressive people would ignore the deprecated mark until we remove the old API piece and then they'd get major breakage.
    
   A: Deprecate, then plan for removal - this is rather standard practice, why deviate? Be prepared for cases when removal takes longer than you anticipated or turns out plain unacceptable for you.

---

Any other advice is welcome too

Establish and maintain Developer Guide. Better get a good technical writer to maintain it.

Establish and foster community of "outsiders" using your API. Support them by providing public issue tracker, forum(s), mailing list(s), wiki, whatever.

Offer a certification for "outside" code that uses your API. "Application MegaVideoSharing is unsafe because it uses unsupported method temporaryHack in class Workaround. Suggested fix: use method permanentFacade from class AntiCorruptionLayer instead" - stuff like that.

• "Public APIs, like diamonds, are forever. You have one chance to get it right so give it your best..." (Joshua Bloch, How to Design a Good API and Why it Matters)

Answer 2

I maintain a list of API design resources, including recommended books, video tutorials and online articles here

http://theamiableapi.com/api-design-resources/

Ferenc

Answer 3

I'd suggest you buy this book:

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

I was told by a senior level Googler that many technical interview questions at Google (by the API teams) are directly taken out of this book. Thought, I haven't read it yet, I work mostly on the client-side these days. I'll probably end up reading that book only out of personal curiosity.