proposed spec for v1 api

Change-Id: I99cc5a8017789fe817029922272e82a402645e9a

finalized api spec

Change-Id: Ibb015c4dab9e4f36290dec02fb6b9097dc070f11