CGRateS APIs

CGRateS APIs

CGRateS is a powerful open-source, carrier-grade rating system, but one of the more confusing aspects of it is how to interact with it.

Of course, CGRateS has a configuration file (nominally /etc/cgrates/cgrates.json) which should be used to configure which elements are running, how they are set up, how they connect to databases and other elements, and things like CDR structures.

There is also a structure for the rating plans which can be imported using cgr-loader.

But once it is running, how should the outside world interact with it? Specifically, we want to do things like:

  • Add a new subscriber
  • Add credit to a subscriber
  • Add a “bundle” to a subscriber
  • See the status of a subscriber (e.g. how much credit they have left)

We want to do these things, and others, without having to reload the rate plans every time. So, how do we do this?

The answer is to use one of the rich set of APIs that CGRateS provides. These APIs can be access in the following ways:

  • cgr-console – a command line tool to manage CGRateS
  • JSON RPC – For JSON formatted RPC calls
  • GOB RPC – For Golang specific RPC calls
  • Websockets

cgr-console

This is a command-line tool that is built into CGRateS and which, with the default CGRateS configuration, can be launched by simply running as follows:

cgr-console

The cgr-console tool communicates with CGRateS using JSON RPC calls. On the default configuration of CGRateS, this is running on localhost on port 2012, which cgr-console will use by default too. So as long as you are running cgr-console on the same host as CGRateS, this should work.

If you wish to use a different port for JSON RPC, or if you wish to use cgr-console to access CGRateS on a different host, this can be configured in CGRateS within the listen section of the configuration file. Remember, that to access from a remote host, you will need to bind to an IP address other than 127.0.0.1.

You can then launch cgr-console using the “server” parameter to specify the port and/or remote host, as in the examples below:

# Access CGRateS on remote host on standard port
cgr-console -server 192.168.0.20

# Access CGRates on localhost on port 2020
cgr-console -server 127.0.0.1:2020

# Access CGRates on remote server on port 2020
cgr-console -server 192.168.0.20:2020

On running cgr-console, you will be presented with a prompt:

> cgr

Typing help will list all of the commands available, along with some usage information. Typing help <command> will give details of a specific command, for instance:

cgr> help account_set

        Usage: account_set Tenant="" Account="" ActionPlanIDs=null ActionPlansOverwrite=false ActionTriggerIDs=null ActionTriggerOverwrite=false AllowNegative=null Disabled=null ReloadScheduler=false 

There are a lot of commands and, unfortunately, there isn’t really good documentation on all of these commands and what they do, although many are obvious from the name.

All of these commands use one of the CGRateS API calls for which there is reference documentation available showing the command structure, but not really describing the function. Unfortunately, the cgr-console commands often use slightly different names to the API. For instance, the account_set command in cgr_console actually uses the ApierV2.SetAccount API. Similarly the cgr-console command accounts actually calls the API ApierV2.GetAccounts.

That being said, cgr-console is a useful tool to have around, and it’s worth learning some of the more handy commands.

In my next post I will explore how to use cgr-console to manage accounts and account balances.

Leave a Reply

Your email address will not be published. Required fields are marked *