API: document the interfaces better and convert to ABC from interface