Googled some useful links of web API design.
Web API Patterns: http://ajaxpatterns.org/Web_API_Patterns
RESTful Service: http://ajaxpatterns.org/RESTful_Service
* URLs reflect resources
* HTTP Methods reflect actions
* GET used for queries, and only for queries
* Services should be stateless
* Services should be idempotent
* Embrace hyperlinks
* Service documents itself
-- Error responses should also be in human-friendly language and with examples and hyperlinks.
* Service constrains data formats
* Handling arbitrary actions
Semantic Responses: http://ajaxpatterns.org/Semantic_Response
Semantic Responses can be represented in several different forms. Each of the following is captured as a separate pattern.
* XML Message
* JSON Message
* Plain-Text Message
Each of the above patterns discusses its own strengths and weaknesses. There are several factors involved:
* Browser-Side Environment: Which browser versions are being targeted will affect feasibility of message formats. In particular, XML support is limited in older browsers.
* Server-Side Environment: What sort of support is there for the message formats in the server-side coding environment. If using JSON, for example, is there a suitable binding for the server-side language?
* Developer Skills: What sort of skill base is available to deal with the message format? You might be tempted to use XML because you feel browser-based XSLT is the most elegant solution, but that requires XSLT talent.
* External Agents: The browser and the server may not be the only things that access the message. If the server is offering a generic REST service, the message format will need to be suitable for external applications too.
Some blogs:
http://www.sourcelabs.com/blogs/ajb/2006/08/how_to_provide_a_web_api.html
1. Keep it clean and simple
2. Stick to standards
3. Make it about data
4. Keep it working
5. Design for updates
http://particletree.com/features/how-to-add-an-api-to-your-web-service/
