How to Build Your API on ConnexCS
Build Your Own API
API: Introduction
The acronym "API" is frequently used in tech talks in today's digital world, but what precisely is an API and why is it so important? We'll begin on a trip to explain APIs in this technical blog, examine their relevance, and comprehend how they enable smooth interaction between applications and services.
What's an API?
Imagine you have two different programs or apps on your computer, like a music player and a chat application. These programs are like separate worlds, each with its own language and way of doing things.
Now, you want to do something cool: you want to share what song you're currently listening to in the music player as your status in the chat app. But there's a problem–these programs don't naturally understand each other. They speak different languages, and they don't know how to exchange information.
This is where the API comes in.
An API is like a bridge between these two programs. You may consider an API that provides a common platform for the applications. It's a set of rules and instructions that tell the music player and the chat app how to talk to each other.
It defines:-
- What You Can Ask For: The API says, "You can ask me for information about the current song playing in the music player."
- How to Ask: It explains the specific words or phrases you should use to ask for this information.
- What You'll Get Back: It also tells you what kind of answer to expect, like the name of the song, the artist, etc.
Thus, when you want to update your chat app with your current song, you send a message to the API, following its rules. The API then goes to the music player, figures out what song is playing, and brings that information back to your chat app. Your chat app can now show your friends what song you're enjoying.

In a nutshell, APIs help different software programs talk using an agreed language and work with each other by providing a common set of rules and tools for communication.
They're like the translators that enable the digital world to collaborate and share information effectively.
Types of APIs for Web Services
GraphQL and RESTful API are two different approaches to building and consuming APIs for web services.
Each has its own characteristics, advantages, and use cases.
Let's compare GraphQL and the RESTful API:
Parameter | GraphQL | RESTful API |
---|---|---|
Definition | GraphQL is a query language for your API and a server-side runtime for executing those queries by specifying the shape and structure of the response data. | RESTful API is an architectural style that uses a set of constraints and principles for designing networked applications, often using HTTP as the communication protocol. |
Data Retrieval | Clients request specific data fields, reducing over-fetching or under-fetching. | Clients receive a fixed set of data, potentially causing over-fetching or under-fetching. |
Multiple Requests | Often retrieve all needed data with a single request, reducing round trips. | May require multiple requests to gather related data, increasing round trips. |
Query Flexibility | Clients define their data requirements through queries, allowing for dynamic requests. | Clients rely on predefined endpoints and fixed data structures. |
Versioning | Typically does not require versioning, as clients can request new fields as needed. | Often requires versioning to maintain backward compatibility when endpoints change. |
Schema | Uses a strongly-typed schema to define available data types and operations. | Less rigid in terms of data structure; relies on documentation for data shape. |
Caching | More challenging to implement caching due to dynamic queries and field-level control. | Easier to implement caching with predictable endpoints and consistent response formats. |
Overhead | Potential for larger payloads due to flexible queries; may result in over-fetching. | Typically has smaller payloads as clients only receive data defined by the endpoint. |
Discoverability | Relies on introspection queries and well-documented schema for discoverability. | Uses well-documented endpoints and HTTP methods for discoverability. |
Ecosystem | Growing ecosystem of tools, libraries, and services, but not as mature as REST. | Mature ecosystem with well-established tools, libraries, and best practices. |
Real-time Support | Supports real-time data through subscriptions, allowing for live updates. | Real-time updates may require additional protocols or technologies. |
Adoption | Gaining popularity, especially for complex, data-intensive applications. | Widely adopted across various domains and industries. |
Learning Curve | May have a steeper learning curve due to the GraphQL schema and query language. | Typically has a shallower learning curve, especially for developers familiar with HTTP. |
Thus, the choice between GraphQL and the RESTful API depends on factors like the specific use case, the need for flexibility, and the client's requirements.
GraphQL is a good choice when clients require flexibility in data retrieval, while RESTful APIs are well-suited for more straightforward scenarios or when backward compatibility is crucial.
Many organizations are now using a combination of both, leveraging each approach where it makes the most sense in their architecture.
📝 Note: "For this blog, we would primarily be referring to RESTful API"
Importance of APIs
- Interoperability: APIs are the foundation of interoperability. They enable different software systems, regardless of their architecture or programming language, to communicate seamlessly.
- Efficiency: By using APIs, developers can leverage existing functionality, saving time and effort in building everything from scratch.
- Scalability: APIs allow services to scale independently. For instance, a cloud storage service can provide APIs for developers to access storage resources, enabling applications to scale storage needs easily.
- Innovation: APIs foster innovation by opening up platforms to third-party developers. This has led to the creation of extensive ecosystems around services like Facebook, Salesforce, and Amazon.
- Integration: APIs are the glue that holds modern software ecosystems together. They enable diverse applications to work harmoniously, ensuring data flows seamlessly between them.
ScriptForge acts as a powerful automation and integration tool that complements APIs by simplifying their usage, enhancing their functionality, and enabling developers to create customized solutions.
It streamlines the process of working with APIs, making it easier to harness their capabilities and integrate them into your applications.
We discuss ScriptForge in the next section.
ConnexCS API Access
ConnexCS API Access to all of the functions that you can use with the Control Panel.
We have all of this documented here under the Control Panel API. If you want to manipulate a connexcs account (as an administrator or any person representing your company) from an external system, this is the way to start.
Alternatively, if you want to give your customers API access so they may integrate the services you provide (from ConnexCS as a default), then you can point your customers to the Customer Portal API.
There is another way that an API may be used when ConnexCS connects outbound to use an external 3rd party application or platform.
Our platform can also integrate any external API, but we are not going to talk about that here. If you are interested in this, please contact us.
However, what we are going to continue to talk about in this documentation is how to extend the functionality provided by ConnexCS and provide an API to your customer that can access and perform operations entirely of your choosing.
If you are looking to create a full UI as well, this can be done with our ConnexCS Application Platform, which we will talk about later.
ScriptForge: Introduction
What's ScriptForge?
ScriptForge is a scripting framework or library that provides developers with a set of tools and functions to automate tasks within various applications.
It simplifies complex operations, extends functionality, and enhances productivity.
ScriptForge allows you to create custom scripts or code snippets to perform specific actions.
For more information on ScriptForge. Please visit our documentation website and you may read our blog post ScriptForge-Javascript Routing.
The Relationship: How APIs and ScriptForge Work Together
APIs and ScriptForge can be thought of as collaborators in the automation process:
The API is a window into ScriptForge
ScriptForge serves as the executor. Developers can use ScriptForge to write scripts that make API calls. These scripts can trigger actions within applications or services that the API controls. For example, a ScriptForge script can automatically upload files to a cloud storage service using the API.
When your customer wants to interact with your systems to do something that is specific to you, they can call an endpoint that will pass the request to ScriptForge.
ScriptForge is a full Javascript engine that can perform any sort of function you would like. It can prepare the reply and send it back to the customer. Thus, it can provide your own API to your customers.

Use Cases:
- Raise a ticket in your support system
- Order a DID
- Place a phone call
- Completing 3rd-party KYC requirements
- SMS Gateway Functionality
We will now discuss an example of using ScriptForge and APIs together in the next section.
How to build an origination API?
The API Dialing feature sends an API request to the ConnexCS Platform for their customers to place a call via the API.
For this feature, write an API in ScriptForge for connecting the company to their customer via the ConnexCS Platform using this API (in ScriptForge).
ScriptForge uses the originate
feature for originating the call.
You need to include the Company ID,the Server where the call will be sent, Destination, CLI, and Extension in the script.
Building the API Code
- Login to your account.
- Go to Developer ➡️ ScriptForge IDE ➡️ ScriptForge.
- Click on the blue
+
button. - Enter the Name for the script in the Basic Tab.
- You can use the Schedule tab to run your script.
- Click on
Save
. - Click on the created script
Calling API
. <img src= /img/blog/baniing/callingapi.png> - Enter the below code:
/* This ConnexCS Library makes it easy to place a call */
const originate = require('cxOriginate');
/*
Simple Key/Value pairs, where the Key is a private secret,
and the value is the Customer ID.
*/
const apiKeys = {
'secret-key': 1234
};
//async function main (data) {
/* Authorizing the key */
const companyId = apiKeys[data.apiKey];
/* If the company does not exist, throw an Error*/
if (!companyId) throw new Error('401 Unauthorized');
/*
If the destination does not exist, throw an Error
The destination is the telephone number to be dialled
*/
if (!data.destination) throw new Error('Missing Destination');
/*
If the CLI does not exist, throw an Error
The CLI is the form number of the phone call.
*/
if (!data.cli) throw new Error('Missing CLI');
/*
If the extension does not exist, throw an Error
The external is the second leg destination where the
connected call will then be delivered to.
For example, a queue.
*/
if (!data.extension) throw new Error('Missing Extension');
/*
Use the ConnexCS library to place the call.
*/
var result = await originate.originate(companyID, 'enter server details the calls will be sent to', data.destination, data.cli, data.extension);
/*
Confirm that everything worked okay.
*/
return {status: 'OK'};
}
9.Click on Save and Run
. <img src= /img/blog/baniing/callingapi1234.jpg>
10.You can access this feature on your Customer Portal using the UUID. We use the UUID to access ScriptForge from the customer portal URL as an API unauthenticated. For example, your Customer Portal URL is https://api.xx.yy/api/script/**uuid** and the code will be published here.
Conclusion
In a world where digital transformation is reshaping industries, APIs are the building blocks of connectivity. They empower developers to create integrated, efficient, and innovative software solutions.
Understanding how to harness the power of APIs isn't just an asset; it's a necessity in today's tech landscape.
The next time you hear the term "API," remember that it's not just an acronym; it's the key to unlocking the potential of interconnected software.