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.
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, 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.
| Method | Common Use |
|---|---|
GET | Most 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. |
POST | Most 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. |
PUT | Often 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). |
DELETE | Used 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.
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.
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function createMessage() {11const message = await client.messages.create({12body: "This is the ship that made the Kessel Run in fourteen parsecs?",13from: "+15017122661",14to: "+15558675310",15});1617console.log(message.body);18}1920createMessage();
1{2"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",3"api_version": "2010-04-01",4"body": "This is the ship that made the Kessel Run in fourteen parsecs?",5"date_created": "Thu, 24 Aug 2023 05:01:45 +0000",6"date_sent": "Thu, 24 Aug 2023 05:01:45 +0000",7"date_updated": "Thu, 24 Aug 2023 05:01:45 +0000",8"direction": "outbound-api",9"error_code": null,10"error_message": null,11"from": "+15017122661",12"num_media": "0",13"num_segments": "1",14"price": null,15"price_unit": null,16"messaging_service_sid": "MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",17"sid": "SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",18"status": "queued",19"subresource_uris": {20"media": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Media.json"21},22"tags": {23"campaign_name": "Spring Sale 2022",24"message_type": "cart_abandoned"25},26"to": "+15558675310",27"uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json"28}
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function fetchMessage() {11const message = await client12.messages("MM800f449d0399ed014aae2bcc0cc2f2ec")13.fetch();1415console.log(message.body);16}1718fetchMessage();
1{2"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",3"api_version": "2010-04-01",4"body": "testing",5"date_created": "Fri, 24 May 2019 17:18:27 +0000",6"date_sent": "Fri, 24 May 2019 17:18:28 +0000",7"date_updated": "Fri, 24 May 2019 17:18:28 +0000",8"direction": "outbound-api",9"error_code": 30007,10"error_message": "Carrier violation",11"from": "+12019235161",12"messaging_service_sid": "MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",13"num_media": "0",14"num_segments": "1",15"price": "-0.00750",16"price_unit": "USD",17"sid": "MM800f449d0399ed014aae2bcc0cc2f2ec",18"status": "sent",19"subresource_uris": {20"media": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMb7c0a2ce80504485a6f653a7110836f5/Media.json",21"feedback": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMb7c0a2ce80504485a6f653a7110836f5/Feedback.json"22},23"tags": {24"campaign_name": "Spring Sale 2022",25"message_type": "cart_abandoned"26},27"to": "+18182008801",28"uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMb7c0a2ce80504485a6f653a7110836f5.json"29}
1// Download the Node helper library from twilio.com/docs/node/install2// These consts are your accountSid and authToken from https://www.twilio.com/console3// To set up environmental variables, see http://twil.io/secure4const accountSid = process.env.TWILIO_ACCOUNT_SID;5const authToken = process.env.TWILIO_AUTH_TOKEN;6const client = require('twilio')(accountSid, authToken);78client9.messages('MM800f449d0399ed014aae2bcc0cc2f2ec')10.update({ body: '' })11.then(message => process.stdout.write(message.body));
1{2"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",3"api_version": "2010-04-01",4"body": "",5"error_code": null,6"error_message": null,7"num_segments": "1",8"num_media": "0",9"date_created": "Mon, 16 Aug 2010 03:45:01 +0000",10"date_sent": "Mon, 16 Aug 2010 03:45:03 +0000",11"date_updated": "Mon, 16 Aug 2010 03:45:03 +0000",12"direction": "outbound-api",13"from": "+14158141829",14"price": "-0.02000",15"sid": "MM800f449d0399ed014aae2bcc0cc2f2ec",16"status": "sent",17"to": "+15558675310",18"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: