Getting started with CALLR API

APIs quickly took the developers’ world by storm. 11 years ago, the firsts APIs (Mashery, Google Maps, Facebook…) were made public, along with their documentation. APIs spread fast because they allow an unprecedented level of integration between different services and platforms. Since the inception of the first public APIs, a lot of progress has been made, especially regarding their documentation and accessibility. While interacting with the first APIs pretty much required you to be a developer, or at least be familiar with common data structures and information retrieval methods, APIs are now close to being usable by anyone willing to spend some time digging. In this article, we’ll explain how to interact with APIs and navigate their documentation, using our own CALLR API as an example. Although the article is focused on our API, we tried to make it as generic as possible to help you get your hands on any API, and start building! If you want to freshen up on APIs before we start, feel free to check out our previous article: What is an API?

Finally, one last heads-up before we dig in: we offer SDKs in nine different programming languages. To keep the article clear and as concise as possible, we’ll only present code snippets in Python. Don’t worry if you are using another programming language, you’ll just have to adapt the snippets a little. You'll need to have a CALLR account to get started:[cta href="https://www.callr.com/#signup" txt="The one-stop-shop for all your telco needs" btn="Try CALLR"]

Setting up the development environment

Before your start using an API, you need to cover the basics and set up your development environment: where to write your code, what you need to make it run and how to make it run. If your development environment is already set up, feel free to skip this step. Setting up the development environment includes having a text editor suited to write code, installing your desired programming language requirements and setting the terminal you will use to run your code. We’ll go through each step. If you are on Mac, the installation process is much simpler: indeed, most of the programming languages covered (PHP, Ruby and Python) in this article are already pre-installed on Macs.

Where do I write my code?

You can write code in any text editor you like; even the most basic would do. However, some editors are specifically designed to make it convenient and fast. Here, we use and recommend the feature-rich SublimeText. SublimeText offers a permanent free trial. Feel free to buy it if you find yourself using it often.

What do I need to run it?

PHP

On Windows, you can use WampServer, a web development environment. PHP and Apache come pre-packaged with Mac.

Python

The Python language documentation provides an exhaustive guide detailing the installation process for Windows. Python is pre-installed on Mac.

Ruby

An all-in-one Ruby installer is available for Windows. Ruby is pre-installed on Mac.

JavaScript/NodeJS

Tutorials are available to detail the installation process. Treehouse's tutorials are clear and straightforward, both for Mac and Windows.

How do I run it?

Be it on Mac or Windows, both have pre-installed terminals you can use to run your code: no additional setup is required. Numerous alternative terminals are available with their own set of features; considering what we will do today, the default is enough.

Your first steps with CALLR's API

Most APIs requires you to authenticate yourself. Authentication method varies, we’ll cover the process for CALLR’s API. In order to use our API, you will need to register an account on CALLR, follow this link to start the process if you don't already have one. Once registered, you will receive your credentials by email; they will be required for the authorization will initializing your code. We have produced (and keep producing) numerous contents to help you use CALLR to its full extent. Check out our other resources if you need more assistance.

How to initialize the API?

You need to create an instance of the API in your code and provide correct authentication parameters for it to function properly. You can copy paste the code below. Don't forget to replace the placeholders with your login credentials. The login and password required here were sent by email after your signup.

What are methods?

Methods are the main way to interact with APIs. Methods are functions: given arguments (entry parameters) a method will output an object variable and/or accomplish an action. For instance, one of the simplest methods of our API is the sms.send method (doc).Given four arguments listed below, it returns a hash (8 characters alphanumeric code) which is the unique identifier of the sent SMS (ex: "I8PSZ8O7") if the message was successfully sent. Arguments have a specified type such as string or integer. We will present them in the next section. Some arguments can be empty/None while some others are required.

1. from: SMS Sender Name, default is SMS
2. to: SMS destination number,
3. body: the message,
4. options: object to specify other options such as encoding or SMS nature, can be none.

Before using methods, you need to initialize the API.

How to call methods?

You won't be able to call methods until the API is properly initialized. It's a good practice to create a variable that will store the result returned by your API calls. All PHP, Python and Ruby codes displayed here and in the docs are structured this way. Methods are called using the api.call command. For this example, we will use the sms.send method (doc). It sends an SMS to the target number while returning a 8-digits hash ID of the sent SMS. The api.call command requires the name of the method you wish to use followed by its required parameters. We'll illustrate this with the sms.send method. It requires four parameters in the following order: the sender name (string), the destination number (string), the message content (string) and the options (object). In the following examples, no options are set; the parameter still needs to be imputed (Null/Nill/None object).

Calling our first method

Now that you’re familiar with the sms.send method, let’s send our first SMS using CALLR: Pretty straightforward right? Remembers that the sms.send method send an SMS but also returns the ID of it? You can print it: print(sms).Sms.send is a simple method, if you want to use more complex ones, you'll need to be aware of all the data types to be able to format your arguments properly. To be able to navigate the documentation of APIs and understand how to properly call their methods, you need to familiarize yourself with data types and objects. We’ll detail each one.

What are the different data types?

For each method, documentations generally list the expected parameters and their types (it’s systematic on CALLR’s doc). Names specified in parenthesis correspond to the way the data types are referred to in our doc. While we sent our first SMS, we already used to use two different data types: strings (from, to and body) and objects (options). It’s a good start but there is more to it:

Integer (Int)

Integers are whole numbers that can be positive, negative or zero. They cannot have decimal places. 2, 2675, and -74 are all integers. Integers are used whenever a numeric input is needed, to specify the area code and the desired number amount while using the did/store.reserve method for instance (doc).

String

A string is a chain of characters. There are no restrictions regarding its content which can be of any character types, numeric or text. Strings are used to carry content, such as the body of an SMS message in the sms.send method (doc).Strings must be delimited using inverted commas, for instance: 'string content' or "string content".

Array

Arrays a list of elements formatted using the same data structure. For instance, the did/areacode.countries method return an array of DID countries objects, that is the country with their label, code and boolean regarding DID availability (Classic and Gold).

Print of an array - the result of the did/areacode.countries method (using Python)[/caption]

Boolean (Bool)

A boolean is a data type with two possibles values: True or False. On the previous screenshot, the CLASSIC and GOLD availability are both booleans.

What are objects?

Objects are a format type. Methods return outputs objects such as the SMS hash identifier for the sms.send method (doc).Objects are also used to store information, such as the SMS.options object (doc) where you can specify the nature of the traffic or force a specific encoding. Note: data types are not exclusive and are often nested in one another. For instance, the SMS.options object is an object made of an array of strings and booleans.

Calling the sms.send method with options

Now that we are familiar with data types and objects, let’s go back to our first API call and make it a little bit more complex. For our first SMS, we used “None” as our SMS.options parameters: This time, we’ll refine the call by specifying options. The first step is to go to the docs and learn more about this SMS.options object. The docs tell us that the SMS.options accept five proprieties (we don’t have to specify all of them) all detailed in the docs:

• flash_message
• force_encoding
• nature
• user_data
• webhook

For the sake of the example, we’ll try sending a flash message. Flash messages are SMS sent for notifications purpose. They are not stored on the recipient’s phone. Considering the intrusive nature of flash SMS, please test them only with yourself. Here’s how it will look like on the recipient’s phone (iPhone):

Formats used, their limits, and regular expression

While using CALLR, you’ll have to exchange back and forth with our API values that need to be formatted a certain way so you both understand each other. Sadly, our API is not yet sentient, so you’ll have to adapt to the formats the API is used to. For instance, as we’ve seen before with the sms.send method, phone numbers need to be formatted in the international E.164 standard with a + prefix, for instance: +447890123456.All specific formats used for values are specified in the doc with a description and their regular expressions.

Going further: your next steps with CALLR API

The documentation is a good starting point. With the additional details about methods, objects and data types, you are now able to use it fully. Feel free to check the SDK of your preferred programming language as the code examples will help you grasp what the API can do. We also publish cookbooks detailing, step by step, the process required to build simple apps using CALLR. Check them out. Finally, if you are looking for a more advanced tutorial, feel free to check's Davy's House Hunter Bot to learn how to automate your appartement search.