Rest API Calls Made Easy

What are APIs?

API is a set of protocol(rules). It is a method to get response from the server.

How APIs work

The method consists of 6 parameters which are used when you send a request to the server. Depending on the API call the required, these parameters can vary.

The six parameters are:

1. API end point*
2. Method*
3. Rest Endpoint*
4. Headers*
5. Params
6. Data(Payload)

*required

Let’s examine these in detail:

Rest Endpoint

Rest Endpoint is a common endpoint for all the API calls. It is a part of the API url-Rest Endpoint and API endpoint together make up the API url.

Microsoft has several Rest Endpoints:

• Outlook rest endpoint: https://outlook.office.com/api/{version}
• Graph rest endpoint: https://graph.microsoft.com/{version}

In this article, we will be implementing two functions- list messages and send email.

We will be using graph rest endpoint for all the API calls we make in this article. Rest endpoint is generally common for all the functions -list messages, send email, list messages by folder.

Example:

Rest Endpoint as defined in microsoft developers documentation: 
https://graph.microsoft.com/{version}

Find the definition in Microsoft docs here and here.

Modules required:

• uuid( Universal Unique Identifier): It creates a randomly generated unique ID
• requests: It helps decode content from the server.
• json: This is a library that parses JSON data from files or strings to a Python dictionary or list, which is originally in human-readable form.

Case I: List Messages

Gets all the messages in the signed-in user’s mailbox (including the Deleted Items and Clutter folders)

The API components are:

1. API endpoint

It is a unique URL that contains the objects or collection of objects:

/me/messages

Now since we have the Rest Endpoint and the API endpoint therefore the request url will be:

url = "https://graph.microsoft.com/v1.0/me/messages"

2. Headers

Headers are used to give server instructions about the variables in the request. It is used for web communication. These are those fields of the packet that describe to the server the kinds of web pages that are being requested by the client, and consequently enable the client to access these pages.

Headers we will use are to be sent in the json format. The request_id is therefore a long generated string. Our Headers:

• Authorization
• Accept
• client-request id
• return-client-request-id

Representation of Headers:

request_id = str(uuid.uuid4())
headers = {
    'Authorization': 'Bearer {0}'.format(access_token),
    'Accept': 'application/json',
    'client-request-id': request_id,
    'return-client-request-id': 'true'
}

3. Method

HTTP methods (or verbs) are a list of functions that perform corresponding operations that usually involve creation/reading/updating/deleting (CRUD) a resource.
Since we want to GET all the list of messages in the users account therefore the method used will be “get”.

4. Data

Data is generally given when we are creating, updating, or deleting something. In general, data is required when method is POST, PUT or DELETE. Here we are using a GET request therefore data is not required.

5. Params

These are user specifications passed to the endpoint that affects the type of response generated. The different types include header parameters, path parameters, query string parameters and request body parameters. If we only want the top 10 messages as response and not the whole list of 100–1000 messages then we will set the params as:

query_parameters = {
    '$top': '1'
}

Now it’s time to group together and send a request. The request format is:

request. < method > (url, headers, data, params)

Therefore the request will be:

url = "https://graph.microsoft.com/v1.0/me/messages"
request_id = str(uuid.uuid4())
headers = {
    'Authorization': 'Bearer {0}'.format(access_token),
    'Accept': 'application/json',
    'client-request-id': request_id,
    'return-client-request-id': 'true'
}
query_parameters = {
    '$top': '1'
}
response = requests.get(url, headers=headers, params=query_parameters)
print(response_json())

Since we are not passing any data, therefore we will not send anything.

access_token is a unique token generated after OAuth with Microsoft.

uuid module is used in creating the request_id and requests module is always required to send the request.

GET request example

Case II: Create Message

Now, we will create a “Create Message” request i.e we want to send a mail to some other id, we will be sending the recipients info, message details to Microsoft as data. We will be making a POST request.

Again we will break down the components:

1. API endpoint

/me/message and /me/messeages/"messageID"/send
POST request to “/me/message” will save the message to DRAFTS folder and “/me/messeages/"messageID"/send” will take the message from DRAFT folder to SENT folder.

url = "https://graph.microsoft.com/v1.0/me/messages"

2. Headers

Headers representation:

request_id = str(uuid.uuid4())
headers = {
    'Authorization': 'Bearer {0}'.format(access_token)
    'Accept': 'application/json',
    'client-request-id': request_id,
    'return-client-request-id': 'true',
    'Content-Type': 'application/json'
}

3. Method

Since we want to send a message to Microsoft server to be eventually sent to the recipient, therefore the method used will be “post”.

4. Data

Data is generally given when we are creating, updating, or deleting something. In this request we are composing a new mail. The required data format is defined on Microsoft developers account, here:

data = {
    "subject": "Testing Email",
    "importance": "Low",
    "body": {
        "contentType": "HTML",
        "content": "Hey, this is the first testing email"
    },
    "toRecipients": [
        {
            "emailAddress": {
                "address": "apurvakhatri2011@gmail.com"
            }
        }
    ]
}

6. Params

We do not require query parameter because we do not want to limit out response. We just want to see the response status( response code).

Therefore the request will be:

get_compose_url = "https://graph.microsoft.com/v1.0/me/messages"
request_id = str(uuid.uuid4())
headers = {
    'Authorization': 'Bearer {0}'.format(access_token),
    'Accept': 'application/json',
    'client-request-id': request_id,
    'return-client-request-id': 'true',
    'Content-Type': 'application/json'
}
data = {
    "subject": "Testing Email",
    "importance": "Low",
    "body": {
        "contentType": "HTML",
        "content": "Hey, this is the first testing email"
    },
    "toRecipients": [
        {
            "emailAddress": {
                "address": "apurvakhatri2011@gmail.com"
            }}]
}
r = requests.post(get_compose_url, headers=headers, data=json.dumps(data))
r_json = r.json()
message_id = r_json["id"]
get_send_url = "https://graph.microsoft.com/v1.0/me/messages/{}/send".format(message_id)
r = requests.post(get_send_url, headers=headers, data=json.dumps(data))
print(r.status_code)
print(r.text)

POST request example

Start learning how to implement REST APIs along with creating a YellowAnt application here. Tell us about your experiences with APIs in comments below or join the YellowAnt community. Sign up for YellowAnt here.