GraphQL support in FreePBX 15

As you’re probably already aware, we’re very close to the release of version 15 of FreePBX.  One of my favorite new features in FreePBX is the GraphQL support that was added earlier this year.  The support that was added for GraphQL makes it easier for external programs or systems to interact with a FreePBX system.  For those of you not familiar with GraphQL, I hope this blog post makes a good introduction, and helps you to catch my enthusiasm for supporting GraphQL in FreePBX.

What is GraphQL?

GraphQL is a more modern way of programmatically querying applications. GraphQL allows the API user to be more specific about the query they would like to issue to the API. This allows the interaction between the client and server to be more streamlined, make fewer API calls, and be more performant.

GraphQL is a “data query language”, that was developed by Facebook.  It is a specification for how to query an API over HTTP or HTTPS. You can think of it as being somewhat REST-like, but more declarative.  With typical REST APIs, you ask the server to send you a representation of some sort of object. For example, you might do an HTTP GET to http://my.example.com/rest/v1/book/42 and the server would return some sort of stateful representation of object “book” with an identifier of “42”.  If the “book” object has a large number of fields, the server is going to return every single one.

GraphQL is also used to query a server via HTTP or HTTPS and get a response — just like REST.  Unlike REST however, GraphQL lets you specify the exact fields that you want returned. How? A client tells the GraphQL server exactly what it wants the response to look like, by sending the server the layout it wants for the responses.  For example, let’s assume we have a GraphQL server that serves up information about books. The following GraphQL query shows how you would query the server to get the book with ID 42, with only its ID and title fields returned:

query {
  book(id: 42) {
    id
    title
  }
}

Why GraphQL instead of REST?

GraphQL is better at dealing with hierarchical data.  To extend our “books” example a bit more, let’s say that each book has a link to an “author” object as well.  Using REST, we’d have to GET a book object, parse the response to get the author ID, then GET the author object with that ID.  It makes for a lot of back-and-forth requests for linked data. GraphQL, on the other hand, follows relationships between objects.  For example, the following example query would automatically follow the link between the book and the author, and return the “firstName” and “lastName” of the author(s) associated with the books.

query {
  allBooks {
    book {
      id
      title
      author {
        firstName
        lastName
      }
    }
  }
}

GraphQL is also strongly typed.  This means each field is either a built-in type (such as a string or an integer), or a specified type (such as a book or an author).  With GraphQL, you never have to worry about what type of values you’re going to get back from the server.

GraphQL comes with a set of default scalar types out of the box:

  • Int: A signed 32‐bit integer.
  • Float: A signed double-precision floating-point value.
  • String: A UTF‐8 character sequence.
  • Boolean: true or false.
  • ID: Represents a unique identifier for an object

Of course, a GraphQL server can (and often does!) define its own custom types.

GraphQL is also introspective.  This means that there is built-in support for asking the server which methods are available, and which types of data can be returned.  This makes a server self-describing in a way that makes it much easier for developers to explore the API and understand the results. Some GraphQL clients use this introspection to make developing with GraphQL much easier, as will be explained below.

GraphQL basic concepts

GraphQL has three basic types of operations that you can perform: queries, mutations, and subscriptions.  A query is a request for information from the server. A query typically begins with the word “query”, and then the method you are querying, along with the details from that query that you want returned.  For simplicity’s sake, if you leave off the word “query”, GraphQL will assume you’re doing a query. This means that the following two queries are functionally identical:

query {
  book(id: 42) {
    id
    title
  }
}

{
  book(id: 42) {
    id
    title
  }
}

Mutations are used to either create a new object, or to change values on an existing object.  You can think of them as being roughly analogous to using POST, PUT, and PATCH on REST APIs. In the case of GraphQL, however, you’re always using an HTTP POST for your queries, mutations, and subscriptions. For example, the following mutation could be used to create a new book in our example API, and then return its ID:

mutation {
  createBook(input: {
    author: "John Q. Public",
    title: "Hoping for Better Weather",
  }) {
    id
  }
}

The last basic operation is a subscription.  You use subscriptions to be notified when a new object is created, or an existing object is modified.  Assuming the API has a subscription type of “newBook”, the following example would wait until a new book is created, then return it’s title and ID.

subscription {
  newBook {
    id
    title
  }
}

How do I get started with GraphQL in FreePBX 15?

Now that we have covered the basics of GraphQL, let’s dive into using the GraphQL support in FreePBX 15. To begin with, you’ll want to make sure that all of your FreePBX modules are up to date, and that you have the “API” module installed.

IMPORTANT NOTE: Please note that GraphQL support in FreePBX 15 is a technology preview, and that GraphQL support has not been added to every single FreePBX module. Over time, we hope to expand the GraphQL support in FreePBX to cover more modules and more functionality.

Once that is done, you’ll want to create a new API “Application” in FreePBX. Simply go to the FreePBX administrators panel, and choose “API” from the “Connectivity” menu. Then click on the “Add Application” button and choose “Machine-to-Machine app” as shown below:

Adding a Machine-to-Machine App

On the next page, give your application a name (such as “GraphQL demo”) and a description.  For now, leave the “Scopes” field empty. Scopes are a way of limiting the permissions of an application, but by leaving the field blank, we’re giving this application full permissions.  Click on the “Add Application” button.

On the next page, you’ll be presented with all the necessary information to connect to FreePBX via GraphQL.  Your information will obviously be slightly different than mine, but it should look something like the following:

It is vitally important that you copy the “Client Secret” because as soon as you hit the “Close” button you cannot retrieve that value.

Now that we’ve created application credentials, we can use them to play with GraphQL.  There are two methods for doing this. The first is the built-in GraphQL Explorer panel.  The second is using an external application. I’ll briefly explain how to use both.

Using the GraphQL explorer

Within the API module in FreePBX, simply click on the “GraphQL” explorer tab.  Then, simply type “gql” in the scopes text box, and click the “Reload Explorer” button.  This will load the GraphQL explorer with the “gql” scope, which means that you’ll be able to see everything with GraphQL.

GraphQL Explorer Scope

You’ll then see the GraphQL Explorer interface, which allows you to test GraphQL queries and mutations directly from your web browser.  For example, type the following query to get a list of all the FreePBX modules on your system and their current version:

{
  allModules {
    modules {
      name
      version
    }
  }
}

GraphiQL Explorer

Note how the “data” object returned matches the layout of our query? That’s one of the beauties of GraphQL — the results match the format and layout of the query.

Use an external program for testing

Another way to interact with GraphQL (without writing your own GraphQL client in the programming language of your choice) is to use an external program.  There are two popular REST development clients which have added GraphQL support, namely Postman and Insomnia. Since Insomnia was the first to support GraphQL and seems to have more robust GraphQL support, I’ll show you how to configure Insomnia to connect to the GraphQL endpoint in FreePBX.

First, download and install the Insomnia program from https://www.insomnia.rest.  Insomnia has clients for Linux and Mac and Windows.  Once the program has installed, run the Insomnia client.

Click on the “New Request” button, give the request a name, select “POST” as the request type, and “GraphQL Query” as the body type.  Then click the “Create” button.

Create Request

First, let’s tell Insomnia where to send GraphQL requests.  In the URL bar at the top (to the right of where it says “POST”, enter the GraphQL URL from the client credentials we created above.  From my example credentials, the URL would be http://192.168.55.153/admin/api/api/gql. Yours will obviously be slightly different.

GraphQL URL

Next, click on the “Auth” tab at the top of the middle pane.  Click the small arrow next to “Auth” to open the drop-down, and select “OAuth 2”.  Select “Client Credentials” as the “Grant Type”. Enter the Token URL from the client credentials, as well as the Client ID and Client Secret.  Make sure the “Enabled” box is checked. Now, click the “Refresh Token” button at the bottom of the screen. If the “Access Token” is filled in with a long list of letters and numbers, your authentication is working correctly.  If you get a 401 error instead, double-check your Client ID and Client Secret and try again.

GraphQL Authentication

Finally, we can write our query in the “Body” tab.  For our first query, let’s list the FreePBX modules and their versions.  Click the small arrow next to the “Body” tab, and select “GraphQL Query”.  Then type (or copy/paste) the following query in to the “GraphQL” tab:

query {
  allModules {
    modules {
      name
      version
    }
  }
}

Now we can press the “Send” button, and see our results:

GraphQL results

There you go!  You’re on your way to playing with GraphQL and FreePBX 15!  Feel free to look at the documentation, either in the GraphQL Documentation tab in the API module of the FreePBX GUI, or by clicking on the “schema” button in Insomnia.

Technology Preview

Just as a final reminder, please remember that GraphQL support in FreePBX 15 is a technology preview.  Not all of the desired functionality has been baked into the FreePBX 15 release. Future module updates will likely add additional functionality to the GraphQL API.  We hope that this blog post inspires you to start looking at the GraphQL API.  Please give us feedback on what features you would like to see added to FreePBX in the future!

FreePBX 15 – Backup and Restore Rewrite

First, some history: we started development of the new backup and restore system in mid 2017. Some of the goals of that effort were to redesign the feature to allow for more simplicity, flexibility, and maintainability.

Some of the major reasons it was decided to rewrite include:
– There was no choice for backup on a per module basis.
– There was no option to restore the backup from an older version to a newer version.
– No choice of restoring only a particular module.

The redesign ended up being a new concept/structure of taking backup from the way it used to be. Each module handles its own backup and restore. This makes the QA process more complicated due to having to test each and every module and many combinations of modules.

New Backup & Restore functionality:

The new backup and restore functionality in Freepbx 15 is very simple and easy. Each module handles its own backup and restore implementation. It allows you to do backups per module – and 15 backup does only the data backup so it is very lightweight. Prior to 15, backup could potentially include not just configuration files and database information, but also could include FreePBX PHP files and other similar unnecessary additional program related data (depending on how a user constructed their backup templates). In FreePBX 15, we have also removed the backup templates concept from backup and restore to make the backup data selection process more simple and clear for users. We decided that the previous template system was overly complicated for what it was intended to do. If someone is not familiar with the details of which underlying applications and modules needed to be backed up, it was challenging to figure out how to properly construct a template for some particular part of the system. The new system simplifies the module selection interface and it allows you to restore any particular module from a full backup. So if users would like to backup or restore only one particular module, the new interface allows users to easily do so.

FreePBX 15 backup also allows you to restore from legacy backups. This means that people can take a backup from an older version of FreePBX (specifically versions 13 and 14) and restore to a FreePBX 15 system. This makes it easy for the users of FreePBX to migrate from older versions to a new or more current major version of FreePBX.

Backup storage options are now handled in the Filestore module which offers more options on where to store your backups. These options include local storage, remote FTP, SSH/SCP, Amazon’s S3, Email, and Dropbox.

As previously mentioned, due to the scope and complexity of these efforts, it required a much longer QA cycle to make sure it was ready to go (or ready enough). That being said, we hope it to be a lot more “baked” at release time than it would have been otherwise.

We hope you all are able to enjoy and try this new functionality out. As always, for any issues that are found, feel free to open a bug at issues.freepbx.org.

Thanks,
Philip Joseph

FreePBX 15 Release Candidate Announcement

Hey All,

Before I get down to business, I’d like to introduce myself to you, as I don’t think I’ve had an opportunity to do so. My name is Matthew Fredrickson, and I’m the new FreePBX project lead at Sangoma. I began working at Sangoma as a part of the Digium acquisition and have had the role of Asterisk project lead for the last few years. After Andrew decided to leave Sangoma, the leadership at Sangoma asked me if I would be willing to step in and work with the many great developers and community members of FreePBX in addition to those of the Asterisk project. Taking on that mantle from Andrew has been no small undertaking, but has been an enjoyable opportunity for me to grow as well.

My background in telecommunications started in 2001 when Mark Spencer asked me to work for him doing open source software development with Asterisk. Over the years, I’ve had the opportunity to do extensive work on DAHDI, Asterisk, and many of Digium’s traditional telephony products. The acquisition by Sangoma allowed both Digium’s and Sangoma’s world class teams to come together and try to improve our part of the telecom industry in a more synergistic way.

All that being said, my goal today is not to go extensively into my own past, but to write about the present. Today, we’d like to announce that the FreePBX 15 branch is graduating from beta into a release candidate phase. This is the final step that will take place prior to an official FreePBX 15 release. The goal is to have an approximately 4 week period in the release candidate phase and have all major issues and regressions resolved by the end of the month, at around Astricon time (Oct 28-Oct 30 or so). So for those of you who like to test new releases, please do your best to test things in the FreePBX 15 branch so that we can get as many pesky bugs knocked out as possible prior to a final release.

In conclusion, I want to thank all of you that contribute regularly to the FreePBX project – whether it be in the forums answering questions, doing code level contributions, or all the many other ways there are to directly and indirectly contribute. I have learned in my work with the Asterisk project that it takes a lot of time and effort from not just one, but many individuals to help make all the parts of an open source project to run smoothly.

Also, be on the lookout over the next few weeks for a few blog posts editorializing some of the new features in FreePBX 15.

Happy testing to you all, and best wishes!

Matthew Fredrickson

Ch-ch-changes to AstriCon

A year ago, the words of rock legend David Bowie rang in my head as the acquisition of Digium by Sangoma was announced. “Ch-ch-ch-ch-changes, turn and face the strange ch-ch-ch-changes” indeed summed up how I was feeling in the moment.

When you initiate changes yourself, it’s pretty easy to adapt since it’s a wanted change. However, when it’s unexpected or unplanned, it can be difficult and sometimes annoying until you step back and begin understanding the reasoning behind it. I’ve had to adapt to many changes this past year including a new boss, new co-workers, and new processes/ procedures. After the dust settled, I began to understand better that for Digium to continue to grow and remain successful, a change was necessary… which brings me to AstriCon.


AstriCon is the event for open source users and the open source community. Open source software is flexible and agile, allowing developers to create unique solutions, which the community can then build upon. That’s what keeps Asterisk growing. As someone who has been part of AstriCon since 2006, I can say that AstriCon had started falling into a “rinse and repeat” mode. Becoming routine which ultimately leads to dull, predictable, and uninteresting. And, honestly, the attendance numbers were starting to indicate a change was necessary. Unlike Asterisk, we were far from agile. As a team (which included key software engineers, long-term Digiumites, and key execs), we determined a “re-boot” was necessary. Thus the changes to AstriCon 2019.

In order to improve, you have to do things differently. Sometimes those improvements are not readily seen at first. There have been several instances within the Asterisk community when changes were made that caused some heartburn but ultimately led to improvements in Asterisk. Two examples come to mind. Code reviews which were a very drastic process shift – people were initially against it, but through that, we gained better code quality and a more stable Asterisk. The second, chan_pjsip, which was a leap into a new SIP implementation but through it we’ve gained new features to make things easier for users such as outbound registration line support, and new functionality such as video conferencing. These things would not have been possible to reasonably do with chan_sip.

AstriCon 2019 is going to be different from what attendees have experienced in the past. While there won’t be as many open source tracks and there are business tracks, the key areas will remain the same: content, collaboration and networking opportunities with like-minded open source enthusiasts. Change is hard, but embracing it, like I have, will bring rewards.

If you are on the fence about attending AstriCon, I encourage you to take a leap of faith and join us. We need our community to attend and help us with feedback as we work to reinvent AstriCon with you in mind. We want to know what works, what doesn’t work, what you like, and what you’d like to see in the future. Don’t hesitate to let us know.

Register here!

Farewell Andrew

Great Job Andrew!

It’s been several years since I’ve blogged here and I’m honored to have the privilege of wishing Andrew the best on his future endeavors! For those that don’t know me, I used to run FreePBX prior to Andrew taking the helm so it only seemed appropriate that I have the opportunity to wish Andrew the best and further reflect on where FreePBX has been and is going!

Andrew has had a wonderful journey through his involvement and influence on FreePBX and the Asterisk world. The marks that he’s made on the project will continue for years to come. He has had his hands on so many different aspects of the project that I couldn’t even begin to enumerate everything he’s touched! Luckily we have ‘git blame’… Since I haven’t been involved in the day to day goings of FreePBX I thought I’d touch on my views and reflections of the attributes of a successful Open Source project like FreePBX.

I’ll start with some minor reminiscing of my own. My involvement started at the end of 2005, before there was even a FreePBX as it was still called AMP (Asterisk Management Portal) and just prior to Rob Thomas taking over the project. The database schema at the time comprised of 8 tables if I recall correctly, sip, iax, zap and extensions, and a few others. In my case I had just left the corporate world looking for something more fun to do and wanting to get back into telecom. I hooked up with a good friend who had been playing around in this space and immersed myself in this new world.

Rob Thomas had been running the project but other life priorities were competing for his time so I ended up taking it over. This was a time during the FreePBX life that I equated to the 60’s. It was a wild and free time where any and every contribution thrown at the project was getting absorbed without any real structure or planning or release management. It was a great period of growth and recognition but at the time, with the popularity of Asterisk@Home FreePBX was taking off and there was a huge boom in the commercialization of and adoption of FreePBX and Asterisk.

Upon taking over, it was my goal to provide stabilization for the project while continuing to keep it a vibrant and creative environment. These are somewhat opposing forces but necessary to make sure it would come out as an innovative project that thousands of resellers could build dependable businesses and millions of installations could result. During my tenure I accepted the help of energetic and significant forces in the community, whether individuals who came and left or significant players such as Schmooze, with whom I eventually joined forces. The goal was a continued and vibrant creative base to make sure that FreePBX excelled and at the same time, a strong supporter who eventually became Sangoma after FreePBX’s path through Bandwidth.com and then Schmooze who merged with Sangoma.

One underlying force behind Open Source is the collective and ever shifting brain trust that the openness nurtures. It’s through this combination of the constant giving back to the project, and the continuous inflow of new ideas as significant contributors enter the project for their tenure before moving on. Just as this cycling of various community members fuels the innovation in a project, so does the life cycle of its various leaders. Rob Thomas had a charisma and openness to invite the huge influx of contributions during the project’s early days at a time when that’s what it needed. Although Rob could never say ‘no’ and it resulted in plenty of headaches that took years to undo, it was also absolutely the right thing to do. It gave momentum, ideas, innovation and fuel to a great project. I was able to take that momentum and steer it in a direction to give stability and confidence while continuing to allow innovation but at the same time, occasionally having to say no. That took it well into the Schmooze days when we began the transition to let a new wave of creative energy take FreePBX to the next level and move Andrew into the role to take it somewhere I never could have.

Andrew’s leadership has taken the project to new levels that would never have happened had I stayed at the helm. The work that Andrew did, as well as Rob who resurfaced after a 5 year sabbatical, and James, Jason, Kapil, Philip, Mohit, Franck and others is simply astounding. Andrew has led the project through total rewrites and architectural enhancements of everything from its underlying core to the server side infrastructure that supports FreePBX to the surrounding ecosystems such as Zulu and beyond.

I’m very excited about what is possible going forward. For the first time in over a decade we’ve brought the two underlying technologies of FreePBX and Asterisk under a common umbrella. This has been an evolution that was once ridden by old school grumpy “real men program in dialplan” … they don’t use GUIs. Fast forward 14 years and we have these two symbiotic technologies under one roof. I know all of us who have been close to the project, whether visibly active or silently watching, won’t be far in keeping tabs on what this recent marriage can do in taking FreePBX into its next leap into the future.

For now, please join me in giving a huge thanks to the contributions that Andrew has achieved in his leadership and wishing him well in his next endeavors. Thank you Andrew!

To read Andrew’s post check it out here: https://www.freepbx.org/an-open-source-journey/

-Philippe Lindheimer

To participate in the conversation about this post go here: https://community.freepbx.org/t/farewell-andrew/58812