1) Most Server site software development frameworks now use URL rewriting.URL rewrite can 'scrape' variable/value pairs out of apparent directories after a site address. For example:
http://www.site.tld/variable-A/value-A/animal-type/dog/
The delimiters can be fairly custom within the allowed URL character set. For example:
http://www.site.tld/variable-A#value-A/animal-type#dog/
http://www.site.tld/variable-A#value-A/animal-type#dog/breeds#poodle;afghan;border-collie/
2) When using a modern software development framwork like Symfony, Ruby on Rails, .Net MVC, and the Java MVC products, one of the VERY FIRST THINGS THAT YOU WANT TO DO between doing all the business modeling, use cases, and other top level software design tasks, and actually coding is to map the resources and modules to URLs. Part of that is deciding what formats to supply upon request and where to signify the format on the URL.
3) If a site is going to use multiple formats, the most common way for that to to the server what format is desired is to use a file extension, but use it ubiquitously.
That means, as normal, if a URL looks like:
http://subdomain.domain.tld/directory/filename.ext
Just change the extension to what is desired, and if the site supports it, grand. Usual suspects are .rss|.xml|.json|.html. The ubiquitous part means NO MATTER WHAT IS THE LAST MAJOR VALUE AT THE END OF THE URL (except for variable/value pairs and query strings), PUT THE '.format' AT THE END OF IT. Examples will show it clearly:
http://subdomain.domain.tld/module-or-resource/action.FORMAT
http://subdomain.domain.tld/fake_directory_name_for_user_readability/module-or-resource/action.FORMAT
http://subdomain.domain.tld/module-or-resource/action.FORMAT/var1#value1/var2#value2/
http://subdomain.domain.tld/fake_directory_name_for_user_readability/module-or-resource/action.FORMAT?not-user-friendly-query-string-value=something&also-serach-engines-dont-catalog-this-full-url=but-we-want-that
http://www.site.tld/resource/action/id.format
http://www.site.tld/products/ship/4d912f22c182293a70e2e7ac3671228dff397a52.FORMAT/carrier#ups/rate#blue/address#123-Mocking-Bird-Lane-Uphigh-CO-80230-USA/currency#usd
The '.format' is between the end of the part of the URL that selects the resource or code and the part of the URL that supplies variables to the code processing the request. (PHP/Symfony, PHP/Drupal, Ruby/Rails, et al. all use this)
This convention/practice was decided upon in my projects after going through the research below. I hope it is as useful to you as it was to me:
=========================================
=================
I looked at the following sites:
Twitter
yahoo
amazon S3
facebook
myspace
linkedin
google.
(EOL = End of the Last listed of Collection, Module, Action ,Or Id)
The methods of specifying the return type of the document were one of three different kinds:
1/ Implied, because only one was available (Amazon S3:json, Linkedin:xml)
2/ Implied but another could be specified BY ADDING ‘.format’ TO THE END OF THE EOL before any query string or friendly URL components at the end of the whole URL (MySpace-xml:add.json)
3/ Implied but another could be specified by a query string paramter (google-atom:‘alt=json’, yahoo-xml:‘output=json’)
4/ Format was required BY ADDING ‘.format’ TO THE END OF THE EOL ((Twitter:add .json|.xml|.rss)
=========================================
API Versions numbers used in URL of the the API for:
Yahoo
MySpace
EXAMMPLES of the way '.format' is added to API URLs:
-------------------------------------------------------
http://microformats.org/wiki/rest/urls
HTML
GET /people/1
return the first record in HTML format
GET /people/1.html
return the first record in HTML format
XML
GET /people/1.xml
return the first record in XML format
JSON
GET /people/1.json
return the first record in JSON format
http://confluence.sakaiproject.org/display/SAKDEV/EntityBroker+RESTful+URL+support
Access to an entity:(MEMBER)
* http://localhost:8080/direct/webapp-entity/id0
* http://localhost:8080/direct/webapp-entity/id0.xml
* http://localhost:8080/direct/webapp-entity/id0.json
Access to an entity space:(COLLECTION)
* http://localhost:8080/direct/webapp-entity
* http://localhost:8080/direct/webapp-entity.xml
* http://localhost:8080/direct/webapp-entity.json
Describing entities: (SELF-DISCOVERY/ERD)
o http://localhost:8080/direct/describe
o http://localhost:8080/direct/eval-evaluation/describe
o http://localhost:8080/direct/webapp-entity/describe
o http://localhost:8080/direct/webapp-entity/describe.xml
MySpace
EXAMPLE REQUEST:
* XML: http://api.myspace.com/v1/users/454304609/albums
* JSON: http://api.myspace.com/v1/users/454304609/albums.json
http://apiwiki.twitter.com/Twitter-Search-API-Method%3A-search
Search(GET)
o Example: http://search.twitter.com/search.json?callback=foo&q=twitter
http://search.twitter.com/search.atom?lang=en&q=devo
Statuses/User_timeline
http://twitter.com/statuses/user_timeline/12345.xml or http://twitter.com/statuses/user_timeline/bob.json.
http://twitter.com/statuses/user_timeline.xml?user_id=1401881
http://twitter.com/statuses/user_timeline.xml?screen_name=101010
http://twitter.com/statuses/user_timeline.rss?page=3
Status Updates (POST)
curl -u user:password -d "status=playing with cURL and the Twitter API" http://twitter.com/statuses/update.xml
Further References
http://www.xml.com/pub/a/2004/12/01/restful-web.html
http://ajaxpatterns.org/RESTful_Service (EXCELLENT)* Describing entities:
o http://localhost:8080/direct/describe
o http://localhost:8080/direct/eval-evaluation/describe
o http://localhost:8080/direct/webapp-entity/describe
o http://localhost:8080/direct/webapp-entity/describe.xml
