Understanding APIs and SDKs: A Guide for Everyone

Fear not! In this guide, I'll break down APIs in straightforward terms to help you understand what they are, what they're used for, and how they benefit our everyday digital experiences. I’ll also discuss how APIs differ from SDKs, and – of course – explain the curl thing. Let’s dive in.

What is an API?

An API, or “Application Programming Interface” , essentially works like a messenger, carrying your request to its destination and resulting in some output. Many apps will use APIs to fetch data from a server, such as getting weather updates, retrieving news articles, or listing social media posts. Instead of each app creating its own weather forecasting system, they can use a weather service API to get reliable data.

A great analogy for an API is to think of a waiter in a restaurant and how food is served to the customers.

In a restaurant, you will have your menu which describes the food on offer, and a chef who cooks your food. However, you can’t just walk into the kitchen and ask for a plate of pasta! There must be a process in place that everyone must follow – in order to receive your food, you must communicate with your waiter using the menu to inform them what you are looking for. The waiter then passes on that information to the kitchen, which then prepares your food. Once complete, the waiter will bring your food to your table for you to enjoy. That concept of a waiter, works the very same as an “API”.

An API (the waiter) works between you and the service you wish to communicate with (the kitchen), and delivers the data (food) to you. This way there is no need to expose sensitive data or create your own service. If a weather service has an API available, for example, you can interact directly with that service and receive real-time weather updates without developing your own weather tracking service. Just use what is already available. How great is that?

How do you use an API?

At a restaurant, a menu will display what food is on offer from the kitchen and what you can or cannot have. This works the very same for APIs – the menu for an API is what we call “documentation”.

API documentation is a detailed guide or manual that explains how to use a given API. It's a collection of instructions, just like a “menu,” that tells you what ingredients (parameters) are used in your dishes to get the outcome (results) you want. The documentation will show you what type of requests (orders) are accepted and how to issue them to get specific information.

Depending on the size and history of the service, and how well it has been developed, the level or quality of documentation can vary. Some organizations may lack adequate documentation, causing challenges for developers, while others prioritize excellent documentation, valuing their developers' experiences more. At Twilio, we try to always deliver great customer experiences and make consistent conscious efforts to improve our documentation. We hope you find our own API documentation resourceful and helpful – check out the Twilio Docs, and let us know what you think.

HTTP request methods

When it comes to making an API request, there are some methods which you should be familiar with. These methods have an accepted usage across APIs – but I’ll warn you, always check the API documentation to verify they’ll work the way you expect.

HTTP (Hypertext Transfer Protocol) methods are essential components of the HTTP protocol, defining the actions that can be performed on a given resource (e.g., a web page, a document, or data) located on a web server. These methods determine the type of interaction between a client (e.g., a web browser, customer) and a server (a computer which hosts the website), allowing for various operations to be carried out.

Even when you access a website from your browser, behind the scenes HTTP methods are being used. When making an API request, you will need to select a method that best suits what you are trying to do. Each HTTP method serves a distinct purpose and has specific characteristics.

Below I will touch on four commonly used HTTP methods:

GET

The GET method requests a representation of the specified resource. Requests using GET should only retrieve data. If you wish to get some data from an API, GET is the method you must include in your request.

POST

The POST method submits an entity to the specified resource, often causing a change in state or side effects on the server. If you wish to POST or send some data, this is the method you must include in your request.

PUT

The PUT method replaces all current representations of the target resource with the request payload. If you want to replace some data with data in your request, this is the method you would use.  

DELETE

The DELETE method deletes the specified resource. If you wish to delete some data through an API, the DELETE method should be used in your request.

Making your first request

Now that you have a good understanding of APIs, let's talk about making your first API request. There are many excellent ways to do this and it all boils down to personal preference so what you use is entirely up to you. I’m going to give you a brief tutorial on how to use curl, a command line client which can make API requests.

What is curl ?

curl, which stands for "Client for URLs," is a widely used open-source command-line tool and library for making API HTTP requests and interacting with various protocols. It’s been around since 1998, and you can find its homepage here.

curl is designed to facilitate data transfer between servers and clients, making it a powerful tool for developers, system administrators, and individuals working with web services. You can install it via your own command line in a few steps, as seen below.

Installation 

Installing curl will vary a bit, depending on your computer platform. I’ll give you an overview of installation steps for Windows and Macintosh users.

Windows

Using curl for Windows:

• Download the curl executable for Windows from the official curl website: curl for Windows.
• Choose the appropriate version (either 32-bit or 64-bit) based on your system architecture.
• Extract the downloaded ZIP file to a location of your choice (e.g., C:\curl).
• Add the curl executable path to your system's PATH environment variable:
• Right-click on This PC or My Computer and select Properties.
• Click on Advanced system settings on the left sidebar.
• Click on the Environment Variables button.
• Under System variables, scroll down and find the Path variable, then click Edit.
• Click New and add the path to the curl executable (e.g., C:\curl\bin).
• Open a new command prompt (cmd) and type curl to verify the installation.

macOS:

Using Homebrew (preferred method for macOS):

• Open Terminal, which you can find in the Utilities folder within the Applications folder, or use Spotlight search (Command + Space, then type "Terminal").
• Install Homebrew (if not already installed) by running the following command in Terminal:

After Homebrew is installed, you can install curl using the following command:

brew install curl

To verify the installation, type curl --version in Terminal. If successful, you should see your curl version number displayed. For example, when I tested for this article I saw  curl 8.4.0 (x86_64-apple-darwin21.0).

Send your first SMS message

Now you should have curl successfully installed on your Windows or macOS system. You can choose quite a few things to do for your introduction to APIs – but I’m going to show you how to use Twilio’s Programmable Messaging API to send an SMS.

We’ll start using it from the command line to hit the Twilio API and send our first SMS message. If you haven't done so already, you will need to purchase a Twilio phone number to send SMS from inside the Twilio console. You’ll then need to follow any additional registration steps for the number, depending on where the number originates and where you live.

Log in to the Twilio Console, select Phone Numbers, and then click on the red plus sign to buy a Twilio number. Note that if you are using a free account you will be using your trial credit for this purchase.

In the “Buy a Number” page, select your country and check SMS in the capabilities field. If you’d like to request a number from your region, you can enter your area code in the “Number” field.

Click the Search button to see what numbers are available, and then click Buy for the number that you like from the results. After you confirm your purchase, click the Close button.

To be able to send an SMS via Twilio, you will need to wait for any necessary registration steps to be complete. Once that is done, you need to  have access to your Twilio account credentials to authenticate the API request. Likewise, to send an SMS you need to have two phone numbers: the number of the sender, which is the number you bought in the previous section, and the number of the recipient, which can be your personal number.

The Twilio credentials that you need are your “Account SID” and your “Auth Token”. You can find both on the dashboard of the Twilio Console:

Once you have this information, you are ready to go with your first API request.

Send an SMS with curl

Remember our analogy of our restaurant ? Well let's now take a look at the equivalent of our restaurant’s menu which we can find here: Messaging Resource Documentation 

When you open the link above, you will be presented with quite a lot of information surrounding our Messaging Resource. One the right of the page you will see some code snippets and may notice various programming languages listed: Node.JS, Python, C#, etc. These may be a little daunting at first, but you can ignore these for now as we are only focusing on curl for the purpose of this blog post.

Make sure curl is selected here, and you will be presented with the appropriate template syntax for a request to send a message.

Click the copy icon shown in the image above (in the code box in the upper right hand corner) to copy the entire code snippet and paste it into a text editor of your choice. You can also copy and paste the code snippet seen below the language tabs.

Here’s the example curl script:

This example sends an outbound message from the sender (212) 555-1114 (+12125551114) to the recipient at (310) 556-7965 (+13105567965), and includes the following message: Hello from Twilio!

To make this script work for you, make the following updates, and then paste it into a terminal window:

• Line 1 update with your Account SID
• Line 2 update with a valid destination
• Line 3 update with the desired message text
• Line 4 update with a valid sender number
• Line 5 update with your Account SID and Auth Token

Once you have hit enter in your terminal, a text message will be sent to your destination phone number you supplied in your request above.

Additional optional parameters can be added in your request for requesting status change updates, adding a price limit, and more. For full details on each of the available options, and code samples from our Helper Libraries, please see Message Parameters (Twilio Docs).

API vs SDK

Now that you have a basic understanding of an API, you may ask yourself: what is the difference between APIs and SDKs? In software development, there is a lot of discussion around SDKs, or Software Development Kits, so it’s important you are able to differentiate between the two.

When you want to start developing an application, there are many packages you may need to install to perform specific tasks within your application. One of these, for example, could be connecting to Twilio to send a message.

If you built an application to interact with Twilio, the last thing you want is to manually write API requests for each action you wish to carry out (like we did above!). Manual API requests are fine to get data quickly or test an API, but rarely the optimal approach when it comes to a fully built, production application. Therefore, a more automated API approach which abstracts away the details of the API and makes it easier to program in your choice of language would be best. And you guessed it – this is where an SDK comes in.

An SDK is essentially a collection of packages of pre-written code resources that you can install within your application. Rather than re-writing code to carry out various aspects of your application, you can install the SDK in the language you need, then use the methods built into the SDK to carry out these tasks. Why reinvent the wheel, right?

As an example, imagine you want to build a treehouse. To do that, you need various tools such as a hammer, nails, a saw, and so on. An SDK is like a special kit of tools designed for a specific task, such as creating mobile apps, games, or other software.

This kit includes things like code libraries, pre-written pieces of code, and documentation that make it easier for developers to create software for a particular platform or device. Instead of starting from scratch, you can use the tools in the SDK to save time and effort.

So, an SDK is like a handy set of tools that simplifies the process of building software, just like a toolbox makes it easier to build a treehouse.

Twilio’s Software Development Kits

When it comes to Twilio, we have a vast range of SDK’s available. Whether you want to introduce Voice calling to your application, or you wish to have a 1:1 Video conversation with a doctor, Twilio has you covered with SDKs that help you develop those applications quicker than you can directly with our APIs.

You can check out all our SDKs available in our product documentation. I have also included a list of our Helper Libraries which we have for messaging, in case these also interest you.

Feel free to choose a language and dive right in:

• C# with .NET Framework
• C# with .NET Core
• Java
• Node.js
• PHP
• Python
• Ruby
• Go

We can’t wait to see what you build

David Dooley is a Team Lead for the EMEA Developer Support Team at Twilio based out of Dublin. He’s very passionate about helping our customers achieve success with Twilio and loves to work on complex problems. He also enjoys educating others, hence this blog post. In his spare time he likes to dabble in crypto and is a strong believer in blockchain technology. He can be reached at ddooley [at] twilio.com.