abstract out api specific behavior
fix docblock for jetbrains intellisense