|
1 | 1 | --- |
2 | 2 | kind:change |
3 | | -title:"Gist APInow truncates large files" |
| 3 | +title:"Changes toGist APIresponse for large files" |
4 | 4 | created_at:2014-04-22 |
5 | 5 | author_name:leongersing |
6 | 6 | --- |
7 | 7 |
|
8 | | -In order to provide the most robust, fast and accurate API for Gist werecently decided to make a few small changes to the*files* attribute. |
| 8 | +In order to provide the most robust, fast and accurate API for Gist, weare making two changes to better handle large files in[Gist API responses][gist-json-representation]. |
9 | 9 |
|
10 | | -###Truncating file contents larger than 1MB |
11 | | -This change imposes a sensible (according to our data) limit on the amount of raw file data that is returned in gist fetches via the API. This means faster response times while eliminating browser timeouts when fetching gists that contains large files. When you need the full contents of your gist's file, simply make a request to the url specified in the raw_url attribute. |
| 10 | +###Truncating file contents larger than one megabyte |
12 | 11 |
|
13 | | -###"truncated" attribute |
| 12 | +The[Gist API response][gist-json-representation] includes data for every file in the Gist. That works well for Gists with reasonably-sized files. When a Gist contains large files, however, it can lead to timeouts when preparing or sending the API response. |
| 13 | + |
| 14 | +To eliminate those timeouts, the API now limits the amount of content returned for each file. If a file is larger than one megabyte in size, the API response will include the first megabyte of content for that file. (Few Gists have files this large. As a result, most API clients won't notice any impact from this change.) |
| 15 | + |
| 16 | +###New "truncated" attribute |
| 17 | + |
| 18 | +The JSON snippet below illustrates the attributes provided for each file in the Gist API response. In it, you'll notice a new**truncated** attribute included as part of the file metadata. This Boolean attribute indicates whether the`content` value is truncated for this request. |
14 | 19 |
|
15 | 20 | { |
16 | 21 | files: { |
17 | 22 | "my_large_file.md": { |
18 | 23 | "size": 2097152, |
| 24 | + "content": "Large content. Truncated at end of first megabyte. [...]", |
| 25 | + "truncated": true, |
19 | 26 | "raw_url": "https://raw.githubusercontent.com/[...]/my_large_file.md", |
20 | 27 | "type": "text/plain", |
21 | | - "language": "Markdown", |
22 | | - "content": "", |
23 | | - "truncated": true |
| 28 | + "language": "Markdown" |
24 | 29 | } |
25 | 30 | } |
26 | 31 | } |
27 | 32 |
|
28 | | -In this small example payload, you'll notice the new**truncated** attribute has been added to each file's payload. It is a boolean attribute indicating if the content attribute's value has been truncated for this request. |
| 33 | +###Getting the full content for truncated files |
| 34 | + |
| 35 | +We recognize that sometimes you'll still want the full content for a file, even if it's too large to get returned in the standard Gist API response. In those cases, simply make a request to the URL specified in the`raw_url` attribute, and you'll receive the complete content for that file. |
29 | 36 |
|
30 | | -If you have any questions,please[get in touch][contact]. |
| 37 | +If you have any questions,don’t hesitate to[get in touch][contact]. |
31 | 38 |
|
32 | 39 | [contact]:https://github.com/contact?form[subject]=Gist+API+now+tuncates+large+files |
| 40 | +[gist-json-representation]:/v3/gists/#detailed-gist-representation |
