adding brief bit of documentation on maintenance of service apis/the shim