I've spent some time working with the GitHub Gist API for the development of Gisted and have some thoughts on its usability. My workflow may be unique, but I suspect my needs are representative of more general purpose use-cases as well.
The gist.updated_at field is not updated when its child file objects are updated. This makes it very difficult to perform last-modified queries since all API calls are invoked at the gist level. Clients are required to fetch all gists to determine if there have been any updates since the last call, forcing a very inefficient workflow and burning through users' hourly request limits.
It would be very helpful to have a set of adjectives to perform filtering against the Gist list call. Specifically an updated_since param would be helpful to only fetch Gists updated since the given timestamp.
https://api.github.com/users/rwdaigle/gists?updated_since=20121031
Note that this is different from the API's general support for the 'If-Modified-Since' conditional request which will return all gists if any of them have changed since the last request. What is needed more often is to fetch only the gists changed since the last request.
The list gists API call does not return file contents. While this is understandable for most cases, it does result in an N+1 situation for clients that always need the file contents. A reasonable middle ground is to allow clients to request different object representations for the call.
For instance, the default call would remain as it is today - return gist and file meta-data but no file contents. However, by supporting an optional include_files parameter the API would return the file contents as well.
https://api.github.com/users/rwdaigle/gists?updated_since=20121031&include_files=true
This keeps the default response format lightweight while allowing clients that need the full gist contents an efficient way to fetch the data.