Skip to contentSkip to navigationSkip to topbar
Rate this Page:

What is a REST API?


A REST API allows software programs to expose functionality and data to other programs over the Internet in a consistent format. APIs are considered RESTful if the means of accessing the API provider's functionality adhere to the architectural style of REST(link takes you to an external page).


More on REST APIs

more-on-rest-apis page anchor

A REST API is a popular way for systems to expose useful functions and data to consumers over the Internet. REST stands for Representational State Transfer(link takes you to an external page), which can be described as an architectural pattern describing how distributed systems can expose a consistent interface. API stands for application programming interface, which is essentially a set of software functionality that can be consumed by other software programs (see full definition). Twilio, for example, provides a REST APIs for sending messages, making phone calls, looking up phone numbers, and a lot more.

Generally speaking, when people use the term REST API, they are referring to an API that is accessed via the HTTP protocol at a predefined set of URLs (uniform resource locators) representing the various resources with which interactions can occur.


A REST API will be made up of one or more resources. A resource is any information or content accessed at a given URL - resources could be JSON, images, HTML, or audio files. Resources can usually have one or more methods that can be performed on them over HTTP. Some of the most common are in the table below.

MethodCommon Use
GETMost often used to retrieve a resource at a given URL. Can be requested over and over without side effects. When your browser retrieves a web page, it is performing an HTTP GET request to retrieve that page and the assets on it.
POSTMost often used to create new data on a server. POST requests usually have side effects, like creating new comments or bank charges every time they are submitted.
PUTOften used for updating data. You can submit a PUT request over and over and it should not have side effects (it should do the same thing every time).
DELETEUsed to delete resources from the server.

These HTTP verbs sometimes DO NOT map 1:1 to these tasks, but commonly REST APIs provide a "CRUD" interface to remote resources. "CRUD" stands for these four operations.

  • Create
  • Read (one or multiple)
  • Update
  • Delete

To send a text message with Twilio, for example, you Create a new Message resource. This creates an instance of the resource. You can then Read this instance later to review the message, Update the message body to redact the message, and even Delete the message.

Code Examples

code-examples page anchor

Create a new Message

create-a-new-message page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_14
// Download the helper library from https://www.twilio.com/docs/node/install
_14
// Find your Account SID and Auth Token at twilio.com/console
_14
// and set the environment variables. See http://twil.io/secure
_14
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_14
const authToken = process.env.TWILIO_AUTH_TOKEN;
_14
const client = require('twilio')(accountSid, authToken);
_14
_14
client.messages
_14
.create({
_14
body: 'This is the ship that made the Kessel Run in fourteen parsecs?',
_14
from: '+15017122661',
_14
to: '+15558675310'
_14
})
_14
.then(message => console.log(message.sid));

Output

_24
{
_24
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_24
"api_version": "2010-04-01",
_24
"body": "This is the ship that made the Kessel Run in fourteen parsecs?",
_24
"date_created": "Thu, 24 Aug 2023 05:01:45 +0000",
_24
"date_sent": "Thu, 24 Aug 2023 05:01:45 +0000",
_24
"date_updated": "Thu, 24 Aug 2023 05:01:45 +0000",
_24
"direction": "outbound-api",
_24
"error_code": null,
_24
"error_message": null,
_24
"from": "+15017122661",
_24
"num_media": "0",
_24
"num_segments": "1",
_24
"price": null,
_24
"price_unit": null,
_24
"messaging_service_sid": "MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_24
"sid": "SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_24
"status": "queued",
_24
"subresource_uris": {
_24
"media": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Media.json"
_24
},
_24
"to": "+15558675310",
_24
"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.json"
_24
}

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_10
// Download the helper library from https://www.twilio.com/docs/node/install
_10
// Find your Account SID and Auth Token at twilio.com/console
_10
// and set the environment variables. See http://twil.io/secure
_10
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10
const authToken = process.env.TWILIO_AUTH_TOKEN;
_10
const client = require('twilio')(accountSid, authToken);
_10
_10
client.messages('MM800f449d0399ed014aae2bcc0cc2f2ec')
_10
.fetch()
_10
.then(message => console.log(message.to));

Output

_25
{
_25
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_25
"api_version": "2010-04-01",
_25
"body": "testing",
_25
"date_created": "Fri, 24 May 2019 17:18:27 +0000",
_25
"date_sent": "Fri, 24 May 2019 17:18:28 +0000",
_25
"date_updated": "Fri, 24 May 2019 17:18:28 +0000",
_25
"direction": "outbound-api",
_25
"error_code": 30007,
_25
"error_message": "Carrier violation",
_25
"from": "+12019235161",
_25
"messaging_service_sid": "MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_25
"num_media": "0",
_25
"num_segments": "1",
_25
"price": "-0.00750",
_25
"price_unit": "USD",
_25
"sid": "MM800f449d0399ed014aae2bcc0cc2f2ec",
_25
"status": "sent",
_25
"subresource_uris": {
_25
"media": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SMb7c0a2ce80504485a6f653a7110836f5/Media.json",
_25
"feedback": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SMb7c0a2ce80504485a6f653a7110836f5/Feedback.json"
_25
},
_25
"to": "+18182008801",
_25
"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SMb7c0a2ce80504485a6f653a7110836f5.json"
_25
}

Node.js
Python
C#
Java
PHP
Ruby
curl

_11
// Download the Node helper library from twilio.com/docs/node/install
_11
// These consts are your accountSid and authToken from https://www.twilio.com/console
_11
// To set up environmental variables, see http://twil.io/secure
_11
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_11
const authToken = process.env.TWILIO_AUTH_TOKEN;
_11
const client = require('twilio')(accountSid, authToken);
_11
_11
client
_11
.messages('MM800f449d0399ed014aae2bcc0cc2f2ec')
_11
.update({ body: '' })
_11
.then(message => process.stdout.write(message.body));

Output

_19
{
_19
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_19
"api_version": "2010-04-01",
_19
"body": "",
_19
"error_code": null,
_19
"error_message": null,
_19
"num_segments": "1",
_19
"num_media": "0",
_19
"date_created": "Mon, 16 Aug 2010 03:45:01 +0000",
_19
"date_sent": "Mon, 16 Aug 2010 03:45:03 +0000",
_19
"date_updated": "Mon, 16 Aug 2010 03:45:03 +0000",
_19
"direction": "outbound-api",
_19
"from": "+14158141829",
_19
"price": "-0.02000",
_19
"sid": "MM800f449d0399ed014aae2bcc0cc2f2ec",
_19
"status": "sent",
_19
"to": "+15558675310",
_19
"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/MM800f449d0399ed014aae2bcc0cc2f2ec.json"
_19
}


The REST architectural style goes much deeper. If you'd like to learn more about the REST architectural pattern and REST API's, please check out these resources:


Rate this Page: