more doc/ideas on api design, inspired by net/http