@@ -196,6 +196,31 @@ Requests that require authentication will return 404, instead of 403, in some pl
196196This is to prevent the accidental leakage of private repositories to unauthorized
197197users.
198198
199+ ##Hypermedia
200+
201+ All resources may have one or more` *_url ` properties linking to other
202+ resources. These are meant to provide explicit URLs so that proper API clients
203+ don't need to construct URLs on their own. It is highly recommended that API
204+ clients use these. Doing so will make future upgrades of the API easier for
205+ developers. All URLs are expected to be proper[ RFC 6570] [ rfc ] URI templates.
206+
207+ [ rfc ] :http://tools.ietf.org/html/rfc6570
208+ -
209+ You can then expand these templates using something like the[ ` uri_template ` ] [ uri ]
210+ gem:
211+
212+ >> tmpl = URITemplate.new('/notifications{?since,all,participating}')
213+ >> tmpl.expand
214+ => "/notifications"
215+
216+ >> tmpl.expand :all => 1
217+ => "/notifications?all=1"
218+
219+ >> tmpl.expand :all => 1, :participating => 1
220+ => "/notifications?all=1&participating=1"
221+
222+ [ uri ] :https://github.com/hannesg/uri_template
223+
199224##Pagination
200225
201226Requests that return multiple items will be paginated to 30 items by