Since after the June 2016 API restrictions by the instagram, I was facing difficulty in integrating with the instagram, since all the available materials on the web were outdated.
So, in this blog i will try to explain everything from the beginning, on how to get started with the Instagram Api, how much data you can access and what is restricted.
Registering an API Client as developer
Before you can do anything with the Instagram API, you need to register yourself as a developer . If you are already registered as a developer with the Instagram, then you have to register a new client for you new app.
Once you have registered your app as a client, you will get your client id and client secret. It looks something like this
Your client id and client secret is required when you make API call with Instagram endpoints.
You can see that client status is sandbox mode. so what really is sandbox mode. Lets understand it.
Understanding Sandbox mode
Every new app created on the Instagram Platform starts in Sandbox mode. It is an environment that allows the developers to test the API before going live.
In sandbox mode, you need to create sandbox users. Only sandbox users are allowed to use your app and authenticate with your app.
The data available in Sandbox mode are real Instagram data, with the following limitations:
- Apps in sandbox are restricted to 10 users,i.e you can invite up to 10 users and each user can be invited to 5 apps.
- Data is restricted to the 20 most recent media from each of the sandbox users.
- Reduced API rate limits, i.e. in 1-hour time, only 500 requests can be made to the API.
To get out of Sandbox mode, you need to submit your app for review. If your app falls into the below use cases and gets approved, it will automatically go live.
- “My app allows people to login with Instagram and share their own content”
- “My product helps brands and advertisers understand, manage their audience and media rights.”
- “My product helps broadcasters and publishers discover content, get digital rights to media, and share media with proper attribution.”
Authentication with Instagram
The Instagram API requires an authentication, before you can make any request to the API. Authenticated requests require an access_token. These tokens are unique to a user and should be stored securely. Access tokens may expire at any time in the future, so it must be handled for any future errors.
Access_token can be generated in two different ways depending on your flow, whether you want to generate it on client side or server side.
I will cover both of them, one by one.
1. Receiving an access_token on server side
For receiving an access token on the server side, it is three step process.
STEP ONE: Direct the user to the below Instagram authorisation URL
In the above URL, three query parameters are required, client_id, redirect_uri and response_type.
On redirecting to the above URL, the user will be asked if they would like to grant your application access to her Instagram data.
STEP TWO: Receiving the redirect from Instagram
Once a user authorizes your application, the instagram issue a redirect to your redirect_uri with a code parameter to use in step three.
It looks something like
If the user deny to grant access to your application, then instagram will redirect to the redirect_uri with the below URL
So this case must be handled in your application.
STEP THREE: Request the access_token
Once you get the code in step 2, then you can exchange this code for the access token. For this you have to make a POST request to the below URL.
https://api.instagram.com/oauth/access_token with the below required parameters.
- client_id: your client id
- client_secret: your client secret
- grant_type: authorization_code is currently the only supported value
- redirect_uri: your redirect_uri.
- code: the exact code you received during the step 2
In this case, the Disable Implicit OAuth checkbox must be checked as shown below, otherwise the step 3 will give the error.
Now I will show how to implement it in code with the angular 2 and rails application.
Client Side code in Angular2
Below is HTML code and typescript code, which will redirect your application to URL specified in step 1.
Now after the page is redirected to the Instagram authenticatin URL, the instagram will redirect to our redirect-uri where we get the code in the paramteres and we can store this code and send it to the server side for exchanging it with the access_token.
In the above we are sending our code which we fetched from the query parameters to the server side to exchange it with the access_token.
The above HTTP call must be implemented in services for best practices, but for now we will do it in component only.
Server side code in Ruby on rails
Below is our routes file
Below is our instagram controller
In the above code, the
exchange_code_with_token is the method which will make the POST request as specified in STEP 3.
If we successfully get the access_token, then we can store it in the database and use it for later stage.
Now this access_token can be used before making any request to the Instagram API endpoints.
2. Receiving an access_token on client side
If you are not using any server side language, and want to receive access_token completely on the client side, then it is a two step process.
STEP ONE: Direct the user to the below Instagram authorisation URL
This step is same as what we are doing while receiving the access_token on the server side, but this time we will be using response_type as token instead of code in query parameters.
STEP TWO: Receive the access_token via the URL fragment
In the above step, user will be provided with a login screen and then a confirmation screen where they grant your app’s access to their Instagram data.
Once the user has authenticated and then authorized your application, Instagram redirects them to your redirect_uri with the access_token in the url fragment. It will look like this:
If the user denies to grant permission to your application, then you will get the same error as in server side implementation.
As discussed in the server side implementation, Disable Implicit OAuth checkbox must be must be unchecked in this case.
Fetching data from the API endpoints
Once we have authenticated with the Instagram, now we can start requesting data from API endpoints.
Instagram provides following endpoints :
Now the basic request which we can send to the Users endpoint, is to know about the owner of the access_token.
Note that at the end of the URL, we are sending access_token as the parameter, which we have received during the authentication process.
So all the request to the API endpoints must have valid access_token as the parameter or the endpoint will give the error.
The above endpoint will give us response which will look something like this
In the similar manner we can get the recent media of the user (last 20 media in the sandbox mode)
The response for the above request will look something like this
Server Side Code for above API Endpoints requests
In similar manner you can get data from other endpoints.
Understanding Scopes for API endpoints
The above two endpoints which we are requesting for data is in basic scope. There are many scopes which currently Instagram API supports:
- basic — to read a user’s profile info and media
- public_content — to read any public profile info and media on a user’s behalf
- follower_list — to read the list of followers and followed-by users
- comments — to post and delete comments on a user’s behalf
- relationships — to follow and unfollow accounts on a user’s behalf
- likes — to like and unlike media on a user’s behalf
All apps in sandbox mode have basic access by default, but if want to access other scopes, you will need to specify these scopes in your authorization request like this:
https://api.instagram.com/oauth/authorize/?client_id = CLIENT-ID&redirect_uri=REDIRECT-URI&response_type=code&scope=public_content`
While in sandbox mode, your app has access to all permissions and you can generate access tokens with any scope for testing. To use these scopes in production though, your app needs to go through review and be approved for a given permission. The permissions your app can be approved for relate directly to the use case of your app.
For more information on scopes and use case, visit Instagram developer documentation
Instagram Developer Documentation
While in sandbox, your app has access to all permissions and you can generate access tokens with any scope for testing…
If you liked this article, click the 💚 below. I notice each one and I’m grateful for them.
For more musings about programming, follow me so you’ll get notified when I write new posts.