diff --git a/content/v3.md b/content/v3.md index 8aa79cd363..1091a8b8c8 100644 --- a/content/v3.md +++ b/content/v3.md @@ -14,6 +14,7 @@ you have any problems or requests please contact * Authentication * Pagination * Rate Limiting +* Conditional Requests * Cross Origin Resource Sharing * JSON-P Callbacks @@ -223,6 +224,46 @@ You can also check your rate limit status without incurring an API hit. Please [contact us](https://github.com/contact) to request white listed access for your application. We prefer sites that setup OAuth applications for their users. +## Conditional Requests + +Most responses return `Last-Modified` and `Etag` headers. You can use the values +of these headers to make subsequent requests to those resources using the +`If-Modified-Since` and `If-None-Match` headers, respectively. If the resource +has not changed, the server will return a `304 Not Modified`. Also note: making +a conditional request and receiving a 304 response does not count against your +[Rate Limit](#rate-limiting), so we encourage you to use it whenever possible. + +
+$ curl -i https://api.github.com/user
+HTTP/1.1 200 OK
+Cache-Control: private, max-age=60
+ETag: "644b5b0155e6404a9cc4bd9d8b1ae730"
+Last-Modified: Thu, 05 Jul 2012 15:31:30 GMT
+Status: 200 OK
+Vary: Accept, Authorization, Cookie
+X-RateLimit-Limit: 5000
+X-RateLimit-Remaining: 4996
+
+$ curl -i https://api.github.com/user -H "If-Modified-Since: Thu, 05 Jul 2012 15:31:30 GMT"
+HTTP/1.1 304 Not Modified
+Cache-Control: private, max-age=60
+Last-Modified: Thu, 05 Jul 2012 15:31:30 GMT
+Status: 304 Not Modified
+Vary: Accept, Authorization, Cookie
+X-RateLimit-Limit: 5000
+X-RateLimit-Remaining: 4996
+
+$ curl -i https://api.github.com/user -H 'If-None-Match: "644b5b0155e6404a9cc4bd9d8b1ae730"'
+HTTP/1.1 304 Not Modified
+Cache-Control: private, max-age=60
+ETag: "644b5b0155e6404a9cc4bd9d8b1ae730"
+Last-Modified: Thu, 05 Jul 2012 15:31:30 GMT
+Status: 304 Not Modified
+Vary: Accept, Authorization, Cookie
+X-RateLimit-Limit: 5000
+X-RateLimit-Remaining: 4996
+
+ ## Cross Origin Resource Sharing The API supports Cross Origin Resource Sharing (CORS) for AJAX requests.