Criteria for putting functionality in an API or letting developers make it themselves

Question

I'm defining an abstract base class as a part of an API that will be used by other developers, kind of like defining the Android API and letting developers use it to make phone apps. When should the creator of the API (that's me) provide certain functionality, and when should the creator leave it up to the developers (ie. users of the API) to define that functionality?

Here's a relevant example: let's say I'm defining a general tree of MyObjs (where users can make classes that derive from MyObj and have children, a parent, and can be filtered via types and values.

class MyObj
{
 public:
  // These must be provided
  MyObj const * parent();
  bool setParent(MyObj const * i_obj);

  std::vector<MyObj const * > children() const;
  bool addChild(MyObj const * i_obj);
  bool removeChild(MyObj const * i_obj);


  // The following functions can be implemented
  // by using the functions listed above.
  // Should I provide them (by leaving them in the class or
  // defining them as utility functions, etc), or should I let 
  // the developers define them?
  MyObj const * root() const;
  bool hasChild(MyObj const * i_obj) const;
  std::vector<MyObj const * > descendants() const;
  std::vector<MyObj const * > childrenFiltered(FilterType i_type, FilterValue i_val) const;
  std::vector<MyObj const * > descendantsFiltered(FilterType i_type, FilterValue i_val) const;

 private:
  std::vector<MyObj * > m_children;
  MyObj * m_parent;
};

Things to consider:

• If it involves the use of private variables such that the developers (users of the API) can't provide that functionality, themselves, then I must provide it.
• If some functionality will be used by many of the developers (users of the API), define it myself. That way, developer A won't need to make the same set of extremely useful utility functions that developer B makes; they'll both use the ones I provide.
  • On the other hand, maybe it is best to not try to predict how the base class will be used, and instead, provide the minimum functionality needed to allow developers to do whatever they want.
• If the functionality is core functionality, provide it (even it can be implemented using only other public functions)
  • Determining if something is core functionality seems to be a rather vague business

related posts:

• https://stackoverflow.com/a/1055889/635125
• http://www.gotw.ca/gotw/084.htm
• Class design vs. IDE: Are nonmember nonfriend functions really worth it?

Answer 1

Library design is a fairly complex endavour and there are many different things to consider. Based on the notes I have on this topic I could probably fill a book this. The question above seems to concentrate on individual classes and this is what this answer is about. If things become more complex, e.g. if you have have systems for class or algorithms, more layers of complexity in deciding what goes where show up.

For a class the basic rule is actually relatively simple:

1. The class shall be sufficient. That is, you need everything which a fundamental part of the abstraction and which is necessary to maintain the classes internal integrety: once constructed the object stays in a valid state until destruction (with the possible exception that a member function only supporting the basic exception guarantee may turn the object into the destructible-only state; you should strive not to have any of these).
2. The class shall be efficient. That is, if the exposed interface doesn't allow efficient implementation of typical use cases but using the internal structure of the class would support this, it is probably a good idea to provide the corresponding functionality. For example std::list<T>::sort() can be more efficient than using e.g. std::merge_sort() on iterators exposed.
3. The class shall be minimal. Don't include anything which makes objects bigger because it would be "nice".
4. Optionally, you might want to provide essentially forwarding functions which make the interface a bit nice. For example, on a sequence you might want to have a push_back() function instead of requiring users to use something like cont.insert(value, cont.end()). Anything which is non-trivial to write but can be done with interface shall not be part of the interface.

To some extend this lands you with a pretty bare-bone class. Users can write their own algorithms using it. To avoid lots of duplication you might want to also provide algorithms which are probably implemented in terms of an abstraction of your class. For example, if your class represents a tree algorithms operating on all childrens of a node should work with all kind of trees. For example, std::find() works on all sequences. Adding it to a container only makes sense if the container can do substantially better as is e.g. the case for the associative containers when you go searching for the container's key type. If you need to find something else std::find() is what you want even for these. However, creating appropriate algorithm libraries and coming up with suitable abstraction is a much bigger fish to fry than creating decent classes.

BTW, the "interface" you hae above would send me searching for an alternative library. If there is none I would seriously consider if creatig my own is an alternative. A C++ library with an interface exposing specific containers or pointers would need to add quite a bit of value before I would consider using it.