The first experience with the Google API (on the example of ContactsAPI) and OAuth2.0 on pure HTTP
- Tutorial
When writing a project, I needed to add entries to the Google Contacts Book. Everything seems to be simple, there is an API, take it and use it, but you couldn’t get and use it right away. A lot of documentation, cross-references (of course not in Russian). It took me a long time to figure it all out. In addition, I needed an example of using a pure HTTP protocol without code in any other language. After everything worked out, I decided to write here to save someone a lot of time, putting all the steps on the shelves. For many, there will be nothing new here, especially since this article is mostly a translation and simplification of Google documentation.
So, specifically for my purposes, it was necessary to use the Contacts API. We go into our google account in which we want to enable the API. We follow the link
console.developers.google.com/iam-admin/projects and click "Create Project":
Next, we do everything that Google offers, without folding anywhere. Set the name of the project, etc.
After the creation of the project is completed, you can download the file with all the project data (ID, secret, etc.).
You must also enable the API. To do this, go to console.developers.google.com/apis/ , select the required API from the list and click "Enable API" in the tab that opens. That's it, the first step is over.
To access the API, you need to get access tokens according to the OAuth 2.0 standard. This, perhaps, was the most difficult for me. It’s not so easy to figure out how, where and what requests to send, in what order.
To get tokens that I could later use in my program, I used the extension for Firefox called HTTPRequester.
1. Get code
At this step, a request is made to the user for access. An example request (the symbol * just replaced some data of my application):
More details about some parameters:
scope - the service we are accessing. For contact, this is www.google.com/m8/feeds . The list of addresses of different services can be found at developers.google.com/identity/protocols/googlescopes ;
access_type - type of access. If you need to update tokens without user intervention, be sure to use the offline value. It is also possible that the value is online, but when you select it, you will need to each time ask for permission from the user in the browser;
redirect_uri and client_id - data that is specified in the project file that was downloaded in the first stage;
When executing this GET request, the permissions page appears:
If you click “Allow”, you will get a code that looks something like this (* - replacing my data):
4 / iLcXnhpU8NvMHT5aTy8JjXhcROERzkvKq ********
2. Receive tokens
To receive authorized access tokens, you must send a POST request to the address
www.googleapis .com / oauth2 / v4 / token ( Required , the request content-type must be application / x-www-form-urlencoded).
The request body must contain the following parameters:
Where
code is the data obtained in the previous step;
grant_type is a required parameter, which must be equal to “authorization_code” (not some kind of authorization code, namely, the letters authorization_code).
You will receive a response in JSON format, which will indicate the access token and the access token update token.
Response example:
3. Update the access token The access
token (access_token) has a limited time specified in the expires_in parameter. After expiration, the access token can be updated by the refresh token (refresh_token).
To do this, you need to make a POST request at www.googleapis.com/oauth2/v4/token ( Required, the request content-type must be application / x-www-form-urlencoded).
Request body:
In the answer, again in JSON format, you will receive a new access token.
All received data can be used to perform your tasks. All that was written above is application authorization using the OAuth 2.0 protocol. Further, in order to execute authorized requests, it is necessary to transfer the access token in the parameters (http: //google..................com/? Access_token = ya.23 ****** ***********).
For my task, I needed only three actions: Add a contact, get a list of contacts and delete a contact.
1. Getting a contact list
To get a contact list, just send a GET request with parameters. Example request:
www.google.com/m8/feeds/contacts/gmm ********@gmail.com/full?access_token=ya29.GlwbBFzl0uXJG6yt_Wdgr6vI4KJ88Djw85H*************** ******************************************
In the answer, you can parse the data and get the number of contacts, their description and their ID.
gmm**********@gmail.com is the address of my account.
2. Adding contacts
To add contacts to the address book, you need to send a POST request with an access token in the parameters. ( Required, the request content-type must be application / atom + xml). Example request:
www.google.com/m8/feeds/contacts/gmm *********@gmail.com/full?access_token=ya29.GlwYBLz6AgOE9Xs************* ***************************************************** *************.
Request body (taken from google documentation):
We leave the whole structure the same, we change only personal data (name, number, etc.).
3. Deleting a contact
To delete a contact, you need to find out its ID (you can get it either in the response when adding a contact or when receiving the entire list of contacts) and send a DELETE request.
IMPORTANT! You must add the If-Match parameter to the request header and set its value as *. Without this, deleting a contact will not work.
Example request:
www.google.com/m8/feeds/contacts/gmm ***@gmail.com/base/5a5415d78e677387?access_token=ya29.GlwYBLz6AgOE9Xsnt8Z1raYaa3fB****************** ****
5a5415d78e677387 - Contact ID.
Original google docs:
→ Using OAuth 2.0 for Web Server Applications.
→ Google Contacts API.
That's all, I will be very glad if someone comes in handy article. Personally, to me, the person who first encountered the google API, it was quite difficult to deal with all this.
First part. Application creation and configuration
So, specifically for my purposes, it was necessary to use the Contacts API. We go into our google account in which we want to enable the API. We follow the link
console.developers.google.com/iam-admin/projects and click "Create Project":
Next, we do everything that Google offers, without folding anywhere. Set the name of the project, etc.
After the creation of the project is completed, you can download the file with all the project data (ID, secret, etc.).
You must also enable the API. To do this, go to console.developers.google.com/apis/ , select the required API from the list and click "Enable API" in the tab that opens. That's it, the first step is over.
Second part. Receive Tokens
To access the API, you need to get access tokens according to the OAuth 2.0 standard. This, perhaps, was the most difficult for me. It’s not so easy to figure out how, where and what requests to send, in what order.
To get tokens that I could later use in my program, I used the extension for Firefox called HTTPRequester.
1. Get code
At this step, a request is made to the user for access. An example request (the symbol * just replaced some data of my application):
https://accounts.google.com/o/oauth2/v2/auth?scope=https://www.google.com/m8/feeds&access_type=offline&include_granted_scopes=true&redirect_uri=urn:ietf:wg:oauth:2.0:oob&response_type=code&client_id=921647******-l5jcha3bt7r6q******bhtsgk*****um6.apps.googleusercontent.com
More details about some parameters:
scope - the service we are accessing. For contact, this is www.google.com/m8/feeds . The list of addresses of different services can be found at developers.google.com/identity/protocols/googlescopes ;
access_type - type of access. If you need to update tokens without user intervention, be sure to use the offline value. It is also possible that the value is online, but when you select it, you will need to each time ask for permission from the user in the browser;
redirect_uri and client_id - data that is specified in the project file that was downloaded in the first stage;
When executing this GET request, the permissions page appears:
If you click “Allow”, you will get a code that looks something like this (* - replacing my data):
4 / iLcXnhpU8NvMHT5aTy8JjXhcROERzkvKq ********
2. Receive tokens
To receive authorized access tokens, you must send a POST request to the address
www.googleapis .com / oauth2 / v4 / token ( Required , the request content-type must be application / x-www-form-urlencoded).
The request body must contain the following parameters:
code=4/iLcXnhpU8NvMHT5aTy8JjXhcROERzkvKq********&client_id=921647******-l5jcha3bt7r6q******bhtsgk*****um6.apps.googleusercontent.com&client_secret=hi1W9GAKGer************&redirect_uri=urn:ietf:wg:oauth:2.0:oob&grant_type=authorization_codeWhere
code is the data obtained in the previous step;
grant_type is a required parameter, which must be equal to “authorization_code” (not some kind of authorization code, namely, the letters authorization_code).
You will receive a response in JSON format, which will indicate the access token and the access token update token.
Response example:
3. Update the access token The access
token (access_token) has a limited time specified in the expires_in parameter. After expiration, the access token can be updated by the refresh token (refresh_token).
To do this, you need to make a POST request at www.googleapis.com/oauth2/v4/token ( Required, the request content-type must be application / x-www-form-urlencoded).
Request body:
client_id=921647******-l5jcha3bt7r6q******bhtsgk*****um6.apps.googleusercontent.com&client_secret=hi1W9GAKGer************&refresh_token=1/rCIfgox0M7ul5uKHasqk****************&grant_type=refresh_tokenIn the answer, again in JSON format, you will receive a new access token.
All received data can be used to perform your tasks. All that was written above is application authorization using the OAuth 2.0 protocol. Further, in order to execute authorized requests, it is necessary to transfer the access token in the parameters (http: //google..................com/? Access_token = ya.23 ****** ***********).
Working with Contacts API
For my task, I needed only three actions: Add a contact, get a list of contacts and delete a contact.
1. Getting a contact list
To get a contact list, just send a GET request with parameters. Example request:
www.google.com/m8/feeds/contacts/gmm ********@gmail.com/full?access_token=ya29.GlwbBFzl0uXJG6yt_Wdgr6vI4KJ88Djw85H*************** ******************************************
In the answer, you can parse the data and get the number of contacts, their description and their ID.
gmm**********@gmail.com is the address of my account.
2. Adding contacts
To add contacts to the address book, you need to send a POST request with an access token in the parameters. ( Required, the request content-type must be application / atom + xml). Example request:
www.google.com/m8/feeds/contacts/gmm *********@gmail.com/full?access_token=ya29.GlwYBLz6AgOE9Xs************* ***************************************************** *************.
Request body (taken from google documentation):
Elizabeth Bennet Elizabeth Bennet Notes
(206)555-1212
(206)555-1213
Mountain View 1600 Amphitheatre Pkwy CA 94043 United States
1600 Amphitheatre Pkwy Mountain View
We leave the whole structure the same, we change only personal data (name, number, etc.).
3. Deleting a contact
To delete a contact, you need to find out its ID (you can get it either in the response when adding a contact or when receiving the entire list of contacts) and send a DELETE request.
IMPORTANT! You must add the If-Match parameter to the request header and set its value as *. Without this, deleting a contact will not work.
Example request:
www.google.com/m8/feeds/contacts/gmm ***@gmail.com/base/5a5415d78e677387?access_token=ya29.GlwYBLz6AgOE9Xsnt8Z1raYaa3fB****************** ****
5a5415d78e677387 - Contact ID.
Original google docs:
→ Using OAuth 2.0 for Web Server Applications.
→ Google Contacts API.
That's all, I will be very glad if someone comes in handy article. Personally, to me, the person who first encountered the google API, it was quite difficult to deal with all this.