Api principles (preliminary, very rough draft)

%s/metadata/headers. Sorry had a brain fart. Editing message above.