Make a request to an external API

In order to run any of the following examples, you will first need to create a Function into which you can paste the example code. You can create a Function using the Twilio Console or the Serverless Toolkit as explained below:

Your Function is now ready to be invoked by HTTP requests, set as the webhook of a Twilio phone number, invoked by a Twilio Studio Run Function Widget, and more!

In order for your Function to react to incoming SMS and/or voice calls, it must be set as a webhook for your Twilio number. There are a variety of methods to set a Function as a webhook, as detailed below:

Before you can make an API request, you'll need to install axios as a Dependency for your Function. Once axios is installed, copy the following code snippet and paste it as the body of a new, public Function, such as /astro-info. Be sure to use the instructions above to connect this Function as the webhook for incoming calls to your Twilio phone number.

This code is:

• Initializing a TwiML Voice Response, for speaking back to the incoming caller
• Using axios to perform an API request to the astros endpoint, which will return the number of people currently in space, and a list of their names
• Performing some operations on the data returned by the API, such as isolating the names into a sorted list, and preparing an Intl.ListFormat object for formatting the names
• Generating the message to be returned to the caller, and returning it
• All of this is wrapped in a try/catch block to handle any exceptions, such as a connection error that could be thrown by the API

There are some key points to keep in mind.

Making an HTTP request to an API is what we call an asynchronous operation, meaning the response from the API will come back to us at a later point in time, and we're free to use computing resources on other tasks in the meantime. Calling axios in this code sample creates a Promise, which will ultimately resolve as the data we want, or reject and throw an exception.

The MDN has an excellent series that introduces asynchronous JavaScript and related concepts.

Note that we've declared this Function as async. This means that we can leverage the await keyword and structure our code in a very readable, sequential manner. The request is still fundamentally a Promise, but we can treat it almost like synchronous code without the need for callback hell or lengthy then chains. You can learn more about this async/await syntax at the MDN.

The other key point is that our code only ever calls callback once our code has successfully completed or if an error has occurred. If the await keyword was removed, or we otherwise didn't wait for the API call to complete before invoking the callback method, this would result in incorrect behavior. If we never invoke callback, the Function will run until the 10-second execution limit is reached, resulting in an error and the customer never receiving a response.

Another common situation you may encounter is the need to make one API request, and then a subsequent request which is dependent on having data from the first request. By properly handling Promises in order, and ensuring that callback is not invoked before our requests have finished, you can make any number of sequential requests in your Function as necessary for your use case (while also keeping in mind that the Function has 10 seconds to complete all requests).

Similar to the previous example, copy the following code snippet and paste it as the body of a new, public Function, such as /detailed-astro-info. In addition, you will need to install the qs module as a Dependency so that we can make an API request that includes search parameters. Also, for the text messaging to work, you'll need to set your Twilio phone number as an environment variable titled TWILIO_PHONE_NUMBER.

This code is:

• Initializing a TwiML Voice Response, for speaking back to the incoming caller
• Using axios to perform an API request to the astros endpoint, which will return the number of people currently in space and a list of their names
• Performing some operations on the data, and randomly selecting one of the astronaut names
• Performing a second API request. This time, querying Wikipedia for any articles about the astronaut, with their name as the search term.
• Generating the message to be returned to the caller, sending the caller a text message containing a Wikipedia article (if one is found), and returning the voice message to the caller
• All of this is wrapped in a try/catch block to handle any exceptions, such as a connection error that could be thrown by either API

Frequently in applications, we also run into situations where we could make a series of requests one after another, but we can deliver a better and faster experience to users if we perform some requests at the same time.

We can accomplish this in JavaScript by initiating multiple requests, and awaiting their results in parallel using a built-in method, such as Promise.all.

To get started, copy the following code snippet and paste it as the body of a new, public Function, such as /space-info.

In addition to the axios and qs dependencies installed for previous examples, you will want to get a free API key from positionstack. This will enable you to perform reverse geolocation on the International Space Station or ISS. Set the value of the API key to an environment variable named POSITIONSTACK_API_KEY.

This code is:

• Initializing a TwiML Voice Response, for speaking back to the incoming caller
• Using axios to create two requests to the Open Notify API, one for astronaut information and the other for information about the ISS's location, and storing references to the resulting Promises.
• await ing the result of both requests simultaneously using Promise.all
• Performing a second API request, this time to convert the latitude and longitude of the ISS into a human-readable location on Earth, such as "North Pacific Ocean"
• Generating the message to be returned to the caller based on all of the data gathered so far, and returning the voice message to the caller
• All of this is wrapped in a try/catch block to handle any exceptions, such as a connection error that could be thrown by any of the APIs

Just as you may need to request data in your Serverless applications, there are numerous reasons why you may want to send data to external APIs. Perhaps your Function responds to incoming text messages from customers and attempts to update an internal record about that customer by sending data to an API that manages customer records. Maybe your Function serves as a means to push messages onto a queue, like SQS so that some other microservice can handle clearing out that queue.

Regardless of the use case, you are free to make write requests to external APIs from your Functions (assuming you have permission to do so from the API). There are no restrictions imposed on this by Runtime itself.

Depending on the scenario, making a write request will mostly consist of using the same principles from the above examples, but using HTTP verbs such as POST and PUT instead of GET.

The below example demonstrates a simple use case where a Function:

• Receives an incoming text message
• Derives an identifier from the incoming phone number
• Retrieves a record from an API, based on the derived ID
• Writes an update to that API, and responds to the sender once all operations are complete

Some APIs may not accept write requests that are formatted using JSON (Content-Type: application/json). The approach to handling this situation varies depending on the expected Content-Type and which HTTP library you are using.

One example of a common alternative, which you'll encounter when using some of Twilio's APIs without the aid of a helper library, is Content-Type: application/x-www-form-urlencoded. As detailed in the axios documentation and shown in the example below, this requires some slight modifications to the data that you send, the Headers attached to the request, or a combination of both.

API requests aren't always successful. Sometimes the API's server may be under too much load and unable to handle your request, or something simply happened to go wrong with the connection between your server and the API.

A standard approach to this situation is to retry the same request but after a delay. If that fails, subsequent retries are performed but with increasing amounts of delay (also known as exponential backoff). You could implement this yourself, or use a module such as p-retry to handle this logic for you. This behavior is also built into got by default.

To see this more explicitly configured, the following code examples implement some previous examples, but while utilizing an unstable API that only sometimes successfully returns the desired data.