improved api specification