I am the author of the RESTProvider. Still very early stage so I would not recommend to use it in production. I have been using it on several projects which are in production but I adapted most the code to specific needs. I will try to get a public stable API by the end of the year.
In regards to reworking the API, I would suggest the following:
- Use GZip compression
- Use ETags for caching
- Use standards with no modification (I saw cases where the naming changed from oauth_token to my_token which makes most library useless without modification) – OAuth/REST
- Use creation/modified timestamp and remote ids for all objects in order to enable caching client side (SQLite conflict clauses):
{“myobject”: {“createdAt”: xxxx, “rid”: “hashvalue”}}
4a. Use a good way to identify the object returned for user/activity/application: opensocial uses “application id” + “user id” + “activity id” - Prefer JSON over XML
- Prefer simplicity (lowest depth possible)
- Return the full object with the one to many relationship within that object:
{“parent”:….
“has”: {“full object not just the ID”}
} - Don’t return IDs only ( “category”: [ 2,3,4] should be “category”: [{“name”: “testing”, “id”: 2},{“name”: “production”, “id”: 3 }} )
- Consider each call to be independent of each other (i.e. I should have enough information for call http://test.com/object.json to populate my views)
For documentation:
1. provide test servers
2. provide cUrl for testing
3. provide sample scripts in java/php/ruby etc…
That s all I can think for now. I might add ontop of this as I come with more suggestion.