How to Write a Self-Documenting API
URLs and REST resources have to be intuitive.
The API should cross-link with URL between different resources. This is used very aggressively in the API.
I feel that JSON is better for self-documenting than XML and that the world is moving to JSON so the API is JSON only.
The objects returned have to be self-documenting in terms of how the keys are labeled.
One can’t hide too much functionally in the request or response Headers. This is at times a contentious issue in REST API designs and I explore it further below.
The different types of resources should use the same keys as much as possible. In our cases games and users had a reasonable amount of overlap.