API Requests

In Intro to REST APIs, we learned what APIs are and how they work, and explored some scenarios in which you’re likely to find them useful. In this post, we’ll learn about the structure and content of an API request.

Request structure

When your app calls an API, it must indicate the type of action it’s requesting, specify the operation it’s calling, and provide the data that the API requires to process the request. An API request consists of the following parts:

• Verb is the word that indicates the type of action that’s being requested.

• Endpoint is the HTTP(S) URL that identifies the object or resource that’s being acted upon by the API request.

• HTTP headers provide additional information that the server needs to process the request.

• Body specifies the data to be added or updated.

The following image shows an API request that uses the Smartsheet API to add a column to an existing sheet.

Verb

In an API request, the verb is a word that indicates the type of action that’s being requested. An API request must specify a verb. The verbs you’re most likely to use are:

• POST – add data or initiate the specified action
• GET – get data
• PUT or PATCH – update data
• DELETE – delete data

Note: You may sometimes hear the verb referred to as the method.

PUT vs PATCH

The verbs PUT and PATCH can both be used to update data — but what’s the difference between the two? Technically speaking:

• PUT is to be used for operations that update (replace) an entire resource.
• PATCH is to be used for operations that update only some attributes of a resource.

For example, an API request that updates a User object by supplying values for every attribute of the object would typically be issued with the verb PUT. In contrast, an API request that updates only the lastname attribute of a User object would typically be issued with the verb PATCH.

That all being said though, not all APIs adhere to this strict definition of PUT versus PATCH. Personally speaking, I’ve encountered lots of APIs that don’t use the verb PATCH at all — rather, the verb PUT is used for all update operations. The API Reference docs for the API you’re using will specify the verb to use with each operation.

Endpoint

In an API request, the endpoint is the HTTP(S) URL that identifies the object or resource that’s being acted upon by the API request. An API request must specify an endpoint and the endpoint may optionally include one or more query string parameters.

The combination of verb and endpoint identify the API operation being called. For example, consider the following column-related operations in the Smartsheet API, where the same endpoint is used for three different operations (Get Column, Update Column, Delete Column). The verb that’s specified in combination with the endpoint in an API request will determine which operation is called.

Operation	Verb	Endpoint
Add Column	POST	https://api.smartsheet.com/2.0/sheets/{sheetId}/columns
Get Column	GET	https://api.smartsheet.com/2.0/sheets/{sheetId}/columns/{columnId}
Update Column	PUT	https://api.smartsheet.com/2.0/sheets/{sheetId}/columns/{columnId}
Delete Column	DELETE	https://api.smartsheet.com/2.0/sheets/{sheetId}/columns/{columnId}

Note: You may sometimes hear the endpoint referred to as the URL, the URI, or the resource.

Body

In an API request, the body specifies the data to be added or updated, or provides data that the API requires to initiate the requested action. For example, a POST request that aims to create a new user will specify a body that contains name/value pairs for each user attribute to be populated. Only POST requests (that seek to add data or initiate an action) and PUT | PATCH requests (that seek to update data) will include a body.

The body of an API request is typically specified in a format called JSON. At this point, don’t worry about trying to understand the JSON that’s shown in the examples below — we’ll cover that topic soon in another post.

HTTP headers

In an API request, HTTP headers provide additional information that the server requires to process the request. Each HTTP header is composed of a property name and a value (i.e., a name/value pair). An API request must include HTTP headers and they may be used to specify things like:

• Authentication credentials that identify the user account that’s issuing the request (Authorization header).
• The type of content specified in the request body (Content-Type header).
• Other data about request and/or the expected response.

Note: The documentation for the API you’re using should specify which headers are required. In the interest of brevity, examples in this post show only the Authorization header and the Content-Type header. At this point, don’t worry about trying to understand the contents of these headers in examples below — we’ll cover the topics of Authentication and Content-Type in future posts.

Example requests

Now that we’re familiar with the parts of an API request, let’s look at some examples. The following example requests use the Smartsheet API to add, get, update, and delete sheet rows in the work management platform Smartsheet.

Example: Add data (POST)

The following request adds a new row to a sheet.

POST https://api.smartsheet.com/2.0/sheets/3932034054809476/rows

Authorization: Bearer 394j32xgs7g1t0dnd3e680
Content-Type: application/json

[
    {
        "siblingId": 5225480965908356,
        "cells": [
            {
                "columnId": 6101753539127172,
                "value": "pears"
            },
            {
                "columnId": 4055216160040836,
                "value": 10
            }
        ]
    }
]

In this request:

• The POST verb indicates that the request aims to add data.
• The endpoint corresponds to the rows collection within the specified sheet (https://api.smartsheet.com/2.0/sheets/3932034054809476/rows).
• This combination of verb and endpoint indicates that the request aims to add row(s) to the specified sheet (i.e., Add Rows operation).
• The Authorization header identifies the user account that’s issuing the request.
• The Content-Type header specifies that the body is formatted as JSON.
• The body specifies data for the new row.

Example: Read data (GET)

The following request gets data for an existing row in a sheet.

GET https://api.smartsheet.com/2.0/sheets/5831916227192708/rows/5942480978372484?include=format

Authorization: Bearer 394j32xgs7g1t0dnd3e680

In this request:

• The GET verb indicates that the request aims to get (read) data.
• The endpoint corresponds to the specified row in the specified sheet and includes a single query string parameter at the end of the URL (https://api.smartsheet.com/2.0/sheets/5831916227192708/rows/5942480978372484?include=format).
• This combination of verb and endpoint indicates that the request aims to get data for the specified row (i.e., Get Row operation).
• The Authorization header identifies the user account that’s issuing the request.

Note: Request body and the Content-Type HTTP header aren’t needed because GET requests don’t add or update data. 

Example: Update data (PUT)

The following request updates an existing row in a sheet.

PUT https://api.smartsheet.com/2.0/sheets/8838011585619844/rows

Authorization: Bearer 394j32xgs7g1t0dnd3e680
Content-Type: application/json

[
    {
        "id": "2381012218734468", 
        "cells": [
            {
	        "columnId": "47318480250756", 
	        "value": "XYZ", 
	        "overrideValidation": true, 
	        "strict": false
	    }
        ]
    }
]

In this request:

• The PUT verb indicates that the request aims to update data.
• The endpoint corresponds to the rows collection within the specified sheet (https://api.smartsheet.com/2.0/sheets/8838011585619844/rows).
• This combination of verb and endpoint indicates that the request aims to update the specified row(s) (i.e., Update Rows operation).
• The Authorization header identifies the user account that’s issuing the request.
• The Content-Type header specifies that the body is formatted as JSON.
• The body specifies data to be updated in the specified row.

Example: Delete data (DELETE)

The following request deletes a row from a sheet.

DELETE https://api.smartsheet.com/2.0/sheets/5831916227192708/rows?ids=5942480978372484

Authorization: Bearer 394j32xgs7g1t0dnd3e680

In this request:

• The DELETE verb indicates that the request aims to delete data.
• The endpoint corresponds to the rows collection within the specified sheet and uses a query string parameter (ids) to identify a specific row (https://api.smartsheet.com/2.0/sheets/5831916227192708/rows?ids=5942480978372484).
• This combination of verb and endpoint indicates that the request aims to delete the specified row (i.e., Delete Rows operation).
• The Authorization header identifies the user account that’s issuing the request.

Note: Request body and the Content-Type HTTP header aren’t needed because DELETE requests don’t add or update data. 

So there you have it…

…everything you need to know about the fundamentals of API Requests! Next, we’ll take a look at API Responses. But first — a quick knowledge check: