An Introduction to Using Rest APIs with Twitter

5 min readDec 20, 2018

If you’ve thought about getting data from another source on the internet, such as Twitter you need to use Rest API. But what is a REST API and how do you use it with Twitter?

What Is A REST API

Let’s say you’re trying to find articles on Javascript. You open up Google, type “Javascript” into a search field, hit enter, and you see a list of articles about Javascript. A REST API works in a similar way. You search for something, and you get a list of results back from the service you’re requesting from.

An API is an application programming interface. It is a set of rules that allow programs to talk to each other. The developer creates the API on the server and allows the client to talk to it.

REST determines how the API looks like. It stands for “Representational State Transfer”. It is a set of rules that developers follow when they create their API. One of these rules states that you should be able to get a piece of data (called a resource) when you link to a specific URL.

Each URL is called a request while the data sent back to you is called a response.

The Anatomy Of A Request

It’s important to know that a request is made up of four things:

The endpoint
The method
The headers
The data (or body)

The endpoint (or route) is the url you request for. It follows this structure:

root-endpoint/?

The root-endpoint is the starting point of the API you’re requesting from. The root-endpoint Twitter’s API is https://api.twitter.com.

The path determines the resource you’re requesting for. You can access paths just like you can link to parts of a website.

To understand what paths are available to you, you need to look through the API documentation. For example, let’s say you want to get a list of tweets, retweets or likes through Twitter’s API. The docs tell you to use the following path to do so:

Any colons (:) on a path denotes a variable. You should replace these values with actual values of when you send your request. In this case, you should replace :id with the actual id of the tweet/retweet/like you’re searching for.

All Twitter APIs that return Tweets provide that data encoded using JavaScript Object Notation (JSON). JSON is based on key-value pairs, with named attributes and associated values. These attributes, and their state are used to describe objects.

Twitter serves many objects as JSON, including Tweets and Users. These objects all encapsulate core attributes that describe the object. Each Tweet has an author, a message, a unique ID, a timestamp of when it was posted, and sometimes geo metadata shared by the user. Each User has a Twitter name, an ID, a number of followers, and most often an account bio.

JSON

JSON (JavaScript Object Notation) a common format for sending and requesting data through a REST API. The response that Twitter sends back to you is also formatted as JSON.

A JSON object looks like a JavaScript Object. In JSON, each property and value must be wrapped with double quotation marks, like this:

{
  "property1": "value1",
  "property2": "value2",
  "property3": "value3"
}

Here’s a sample tweet:

The following JSON illustrates the structure for these objects and some of their attributes:

{
  "created_at": "Thu Apr 06 15:24:15 +0000 2017",
  "id_str": "850006245121695744",
  "text": "1\/ Today we\u2019re sharing our vision for the future of the Twitter API platform!\nhttps:\/\/t.co\/XweGngmxlP",
  "user": {
    "id": 2244994945,
    "name": "Twitter Dev",
    "screen_name": "TwitterDev",
    "location": "Internet",
    "url": "https:\/\/dev.twitter.com\/",
    "description": "Your official source for Twitter Platform news, updates & events. Need technical help? Visit https:\/\/twittercommunity.com\/ \u2328\ufe0f #TapIntoTwitter"
  },
  "place": {   
  },
  "entities": {
    "hashtags": [      
    ],
    "urls": [
      {
        "url": "https:\/\/t.co\/XweGngmxlP",
        "unwound": {
          "url": "https:\/\/cards.twitter.com\/cards\/18ce53wgo4h\/3xo1c",
          "title": "Building the Future of the Twitter API Platform"
        }
      }
    ],
    "user_mentions": [     
    ]
  }
}

The Method

The method is the type of request you send to the server. You can choose from these five types below:

GET
POST
PUT
PATCH
DELETE

These methods provide meaning for the request you’re making. They are used to perform four possible actions: Create, Read, Updateand Delete (CRUD).

The API lets you know what request method to use each request. For example, to get a user’s tweets, you need a GET request:

GET statuses/user_timeline

A GET request is required to get a list of tweets from a user. It returns a collection of the most recent Tweets posted by the user indicated by the screen_name or user_id parameters.

Resource URL: https://api.twitter.com/1.1/statuses/user_timeline.json

Follow, search, and get users

GET users / show is used to retrieve a single user object.

There are a few things to note when using this method.

You must be following a protected user to be able to see their most recent status update. If you don’t follow a protected user their status will be removed.
The order of user IDs or screen names may not match the order of users in the returned array.
If a requested user is unknown, suspended, or deleted, then that user will not be returned in the results list.

Resource URL

https://api.twitter.com/1.1/users/lookup.json

Parameters

Example Requests

$ curl --request GET 
  --url 'https://api.twitter.com/1.1/users/lookup.json?user_id=783214,6253282' 
  --header 'authorization: OAuth oauth_consumer_key="consumer-key-for-app", 
  oauth_nonce="generated-nonce", oauth_signature="generated-signature", 
  oauth_signature_method="HMAC-SHA1", oauth_timestamp="generated-timestamp", 
  oauth_version="1.0"'$ twurl /1.1/users/lookup.json?user_id=783214,6253282

Example Response

[
  {
    {user-object},
    {user-object}
  }
]

HTTP Status Codes And Error Messages

HTTP status codes let you tell the status of the response quickly. The range from 100+ to 500+. In general, the numbers follow the following rules:

200+ means the request has succeeded.
300+ means the request is redirected to another URL
400+ means an error that originates from the client has occurred
500+ means an error that originates from the server has occurred

The standard Twitter API returns HTTP status codes in addition to JSON-based error codes and messages and it attempts to return appropriate HTTP status codes for every request.