
Getting Started – Lesson 2
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 actionGET
– get dataPUT
orPATCH
– update dataDELETE
– 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 specifiedsheet
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: