add some remarks for the next API implementer