GitHub Gist API with cURL and Ajax

http://techslides.com/github-gist-api-with-curl-and-ajax

I had seen the GitHub API before but never considered that it extends out toGists, which I use for code samples on this site. In fact, I use a Gist on the bottom for the Ajax code samples that programmatically interact with GitHub using their API to create and modify Gists. First, I will just use command line cURL and then XHR, or more specifically, jQuery Ajax functions. Since Github supports both JSONP and CORS, you can use client side code to interact with the GitHub API.

There is a lot you can do with the GitHub API without authentication. For example, this url will show you latest public Gists in a JSON data structure. You could also create a Gist as Anonymous:

curl -H "Content-Type: application/json" -d '{"description": "the description for this gist","public": true,"files": {"file1.txt": {"content": "String file contents"}}}' https://api.github.com/gists

But, you probably want to manage your code blocks or files under a specific user and for that we need authentication. To create a new authorization, we pass our username and password in cURL and request the gist scope. The JSON body also requires a note or description of what you are trying to achieve. With this cURL command, you will generate a GitHub API token for your user that is needed to authenticate further API requests:

curl -v -H "Content-Type: application/json" -u myUsername:myPassword -d '{"scopes":["gist"],"note":"gist test for a user"}' https://api.github.com/authorizations

The response to this cURL request had a token parameter and value which we will grab and use in an Authorization header to create a new Gist:

curl -v -H "Authorization: token TOKEN-VALUE-FROM-PREVIOUS-CALL" -d '{"description": "a gist for a user with token api call","public": true,"files": {"file1.txt": {"content": "String file contents"}}}' https://api.github.com/gists

This POST request with proper authentication created the Gist file and returned information about it. The PATCH http method is used by GitHub to edit a Gist and here is how you can make a cURL request with the PATCH method to modify our file:

curl -v --request PATCH -H "Authorization: token TOKEN-VALUE-FROM-PREVIOUS-CALL" -d '{"description": "updated gist","public": true,"files": {"file1.txt": {"content": "String file contents are now updated"}}}' https://api.github.com/gists/GIST-ID-FORM-PREVIOUS-CALL

Remember to use the token you have generated in the authorization call and the Gist ID you have received from the previous POST call. Now, how do we make this work with Ajax so that you can create Gists programmatically from JavaScript? Since, we are talking about GitHub Gists, let’s use one of them to demonstrate the code:

	/*
	Assuming jQuery Ajax instead of vanilla XHR
	*/
	//Get Github Authorization Token with proper scope, print to console
	$.ajax({
	url: 'https://api.github.com/authorizations',
	type: 'POST',
	beforeSend: function(xhr) {
	xhr.setRequestHeader("Authorization", "Basic " + btoa("USERNAME:PASSWORD"));
	},
	data: '{"scopes":["gist"],"note":"ajax gist test for a user"}'
	}).done(function(response) {
	console.log(response);
	});
	//Create a Gist with token from above
	$.ajax({
	url: 'https://api.github.com/gists',
	type: 'POST',
	beforeSend: function(xhr) {
	xhr.setRequestHeader("Authorization", "token TOKEN-FROM-AUTHORIZATION-CALL");
	},
	data: '{"description": "a gist for a user with token api call via ajax","public": true,"files": {"file1.txt": {"content": "String file contents via ajax"}}}'
	}).done(function(response) {
	console.log(response);
	});
	//Using Gist ID from the response above, we edit the Gist with Ajax PATCH request
	$.ajax({
	url: 'https://api.github.com/gists/GIST-ID-FROM-PREVIOUS-CALL',
	type: 'PATCH',
	beforeSend: function(xhr) {
	xhr.setRequestHeader("Authorization", "token TOKEN-FROM-AUTHORIZATION-CALL");
	},
	data: '{"description": "updated gist via ajax","public": true,"files": {"file1.txt": {"content": "updated String file contents via ajax"}}}'
	}).done(function(response) {
	console.log(response);
	});

view raw github-gist-api.js hosted with ❤ by  GitHub

The Gist above shows how to execute the same 3 cURL functions with Ajax and jQuery allows you to use the type parameter to change the API call from a POST to a PATCH. The beforeSend parameter let’s me adjust the headers of the request so I can pass the authorization token. The data structured in JSON has a files object which can include multiple files. The XHR or XMLHttpRequest request works because the GitHub origin supports cross origin resource sharing.

So, how would you use this API to build and extend the GitHub Gists feature?

I had seen the GitHub API before but never considered that it extends out toGists, which I use for code samples on this site. In fact, I use a Gist on the bottom for the Ajax code samples that programmatically interact with GitHub using their API to create and modify Gists. First, I will just use command line cURL and then XHR, or more specifically, jQuery Ajax functions. Since Github supports both JSONP and CORS, you can use client side code to interact with the GitHub API.

There is a lot you can do with the GitHub API without authentication. For example, this url will show you latest public Gists in a JSON data structure. You could also create a Gist as Anonymous:

curl -H "Content-Type: application/json" -d '{"description": "the description for this gist","public": true,"files": {"file1.txt": {"content": "String file contents"}}}' https://api.github.com/gists

But, you probably want to manage your code blocks or files under a specific user and for that we need authentication. To create a new authorization, we pass our username and password in cURL and request the gist scope. The JSON body also requires a note or description of what you are trying to achieve. With this cURL command, you will generate a GitHub API token for your user that is needed to authenticate further API requests:

curl -v -H "Content-Type: application/json" -u myUsername:myPassword -d '{"scopes":["gist"],"note":"gist test for a user"}' https://api.github.com/authorizations

The response to this cURL request had a token parameter and value which we will grab and use in an Authorization header to create a new Gist:

curl -v -H "Authorization: token TOKEN-VALUE-FROM-PREVIOUS-CALL" -d '{"description": "a gist for a user with token api call","public": true,"files": {"file1.txt": {"content": "String file contents"}}}' https://api.github.com/gists

This POST request with proper authentication created the Gist file and returned information about it. The PATCH http method is used by GitHub to edit a Gist and here is how you can make a cURL request with the PATCH method to modify our file:

curl -v --request PATCH -H "Authorization: token TOKEN-VALUE-FROM-PREVIOUS-CALL" -d '{"description": "updated gist","public": true,"files": {"file1.txt": {"content": "String file contents are now updated"}}}' https://api.github.com/gists/GIST-ID-FORM-PREVIOUS-CALL

Remember to use the token you have generated in the authorization call and the Gist ID you have received from the previous POST call. Now, how do we make this work with Ajax so that you can create Gists programmatically from JavaScript? Since, we are talking about GitHub Gists, let’s use one of them to demonstrate the code:

	/*
	Assuming jQuery Ajax instead of vanilla XHR
	*/
	//Get Github Authorization Token with proper scope, print to console
	$.ajax({
	url: 'https://api.github.com/authorizations',
	type: 'POST',
	beforeSend: function(xhr) {
	xhr.setRequestHeader("Authorization", "Basic " + btoa("USERNAME:PASSWORD"));
	},
	data: '{"scopes":["gist"],"note":"ajax gist test for a user"}'
	}).done(function(response) {
	console.log(response);
	});
	//Create a Gist with token from above
	$.ajax({
	url: 'https://api.github.com/gists',
	type: 'POST',
	beforeSend: function(xhr) {
	xhr.setRequestHeader("Authorization", "token TOKEN-FROM-AUTHORIZATION-CALL");
	},
	data: '{"description": "a gist for a user with token api call via ajax","public": true,"files": {"file1.txt": {"content": "String file contents via ajax"}}}'
	}).done(function(response) {
	console.log(response);
	});
	//Using Gist ID from the response above, we edit the Gist with Ajax PATCH request
	$.ajax({
	url: 'https://api.github.com/gists/GIST-ID-FROM-PREVIOUS-CALL',
	type: 'PATCH',
	beforeSend: function(xhr) {
	xhr.setRequestHeader("Authorization", "token TOKEN-FROM-AUTHORIZATION-CALL");
	},
	data: '{"description": "updated gist via ajax","public": true,"files": {"file1.txt": {"content": "updated String file contents via ajax"}}}'
	}).done(function(response) {
	console.log(response);
	});

view raw github-gist-api.js hosted with ❤ by  GitHub

The Gist above shows how to execute the same 3 cURL functions with Ajax and jQuery allows you to use the type parameter to change the API call from a POST to a PATCH. The beforeSend parameter let’s me adjust the headers of the request so I can pass the authorization token. The data structured in JSON has a files object which can include multiple files. The XHR or XMLHttpRequest request works because the GitHub origin supports cross origin resource sharing.

So, how would you use this API to build and extend the GitHub Gists feature?