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….
I don’t intend this to be a comprehensive guide to building URLs for a true REST API, just some things to consider for the newbie API product manager who may not have a hardcore REST developer on their team. Considerations When Planning Endpoints for your RESTful API @ API Evangelist