Skip to content

Middleware API

Jump to bottom
laur4c edited this page Sep 8, 2014 · 50 revisions

Complete list

All entry points are relative to /api:

Errors

Very often (precisely when generic errors can be returned), the API will return a status code 400 (or other error code statuses) and the following json format:

  {
    "error": {
      "payload": "account_id,amount,description",
      "description": "missing_parameters"
    }
  }

Be prepared for those messages!

/version

Description

Returns the version number of the middleware and the switch.

Methods

  • GET

Returns

  • 200

Example

$ curl -k https://api.connexo.net/version

{
  "middleware_version": "1",
  "switch_version": "1",
  "webapp_version": "1"
}

In case of errors communicating with the switch, the switch_version field is "error"

/simulate

Description

Simulates a call, returning an array of json calls (1 per route found to terminate the call, see the Call Json Format).

Methods

  • GET

Returns

  • 200

Required Arguments

  • trunk: Trunk ID.
  • from: E164 number. MUST be an existant DID in the system.
  • to: Dialed number, as that particular subscriber would dial (i.e: probably not in E164).
  • call_length: Duration in seconds for the simulated call.

Example

$ curl -k "https://api.connexo.net/simulate? \
       "trunk=1 \
       "from=12035551234 \
       "&to=00154115551122 \
       "&call_length=15"

/subscriber/list

Description

Returns the complete list of all subscribers.

Methods

  • GET

Returns

  • 200

Example

$ curl -k "https://api.connexo.net/subscriber/list"

  [
    {
      "id": 1,
      "name": "Vip2Phone",
      "contact_name": "",
      "created": "2013-05-29T09:40:59-03:00"
    }
  ]

/subscriber/:subscriber_id/accounts

Description

Returns the complete list of all the accounts known for the given subscriber.

Methods

  • GET

Returns

  • 200
  • 404 (on unknown or invalid subcriber_id)

Required Arguments

  • subscriber_id: Integer > 0

Example

$ curl -k "https://api.connexo.net/subscriber/1/accounts"

  [
    {
      "id": 1,
      "funds": "100000.0",
      "credit": "0.0",
      "subscriber_id": 1,
      "plan_id": 1,
      "postpaid": true,
      "description": "account description",
      "billing_period": {
        "from": "2013-01-01",
        "to": null
      },
      "settings": {
        "postpaid": {
          "billing_day": "month:1"
        }
      },
      "created": "2013-05-29T09:40:59-03:00"
    }
  ]

/subscriber/recharge

Description

Adds a sum of money to the given account.

Methods

  • POST

Accepts

  • application/json
  • application/x-www-form-urlencoded

Returns

  • 204
  • 400 (on invalid account_id or invalid arguments)

Required Arguments

  • account_id: Integer > 0.
  • amount: String, represents a float, like "12.65".
  • description: String. A message giving additional information about this event.

Example (application/x-www-form-urlencoded)

$ curl -k -v -d "account_id=1&amount=12.33&description=here is some money" https://api.connexo.net/subscriber/recharge

Example (application/json)

$ curl -k -v -d@req.json -H "content-type: application/json" https://api.connexo.net/subscriber/recharge

Where req.json is something like this:

  {
    "account_id": 1,
    "amount": "12.33",
    "description": "here is some money"
  }

/plan/list

Description

Returns the complete list of all plans.

Methods

  • GET

Returns

  • 200

Example

$ curl -k "https://api.connexo.net/plan/list"

  [
    {
      "id": 1,
      "name": "Regular",
      "type": 0,
      "dids": 1000,
      "charge_incoming": 1,
      "allow_incoming": 1,
      "created": "2013-06-07T20:39:35-03:00"
     }
  ]

/plan

Description

Creates a plan.

Methods

  • PUT

Accepts

  • application/json
  • application/x-www-form-urlencoded

Returns

  • 201: Success operation.
  • 409 (If the plan name already exists)

Headers

  • Location: is returned with the url to access the resource.

Required Arguments

  • name: Integer > 0.
  • type: String, "postpaid" or "prepaid".
  • dids: Integer > 0.

Example (application/x-www-form-urlencoded)

$ curl -k -d -vX PUT "name=some_plan&type=postpaid&dids=1&allow_incoming=true&charge_incoming=true" -vX PUT https://api.connexo.net/plan"

Example (application/json)

$ curl -k -X PUT -v -d@req.json -H "content-type: application/json" https://api.connexo.net/plan

Result:

Location: https://api.connexo.net/plan/12
{"id":12}

Where req.json is something like this:

  {
    "name": "Regular",
    "allow_incoming": true,
    "charge_incoming": true,
    "dids": 3,
    "type": "postpaid"
  }

/plan/:plan_id

Description

Returns the plan information, by id.

Methods

  • GET

Returns

  • 200
  • 404 (if the plan id does not exist).

Required Arguments

  • plan_id: Integer > 0

Example

$ curl -k "https://api.connexo.net/plan/11"

  {
    "id": 1,
    "name": "Regular",
    "type": 0,
    "dids": 1000,
    "allow_incoming": 1,
    "charge_incoming": 1,
    "created": "2013-06-07T20:39:35-03:00"
   }

/stats/billing

Description

Income vs cost report.

Methods

  • GET

Returns

  • 200
  • 400 (on invalid or missing arguments)

Required Arguments

  • start: String, in the form "YYYY-MM-DD".
  • end: String, in the form "YYYY-MM-DD".
  • granularity: "daily" | "hourly"

Optional Arguments

  • type: cost|income. If specified, the report will only contains the specified values.
  • tag: String. If specified, the report will only contain this specific tag.

Example

$ curl -k "https://api.connexo.net/stats/billing? \
  start=2013-06-15 \
  &end=2013-06-20 \
  &granularity=daily"

[{
  "name": "Daily income",
  "pointStart": 1371254400,
  "pointInterval": 86400,
  "data": [0,0.01125,0,0,0,0.16875]
}, {
  "name": "Daily cost",
  "pointStart": 1371254400,
  "pointInterval": 86400,
  "data": [0,0.0110,0,0,0,0.2]
}]

/stats/carrier_seconds

Description

Total number of seconds of answered calls through all the known carriers.

Methods

  • GET

Returns

  • 200
  • 400 (on invalid or missing arguments)

Required Arguments

  • start: String, in the form "YYYY-MM-DD".
  • end: String, in the form "YYYY-MM-DD".
  • granularity: "daily" | "hourly"

Example

$ curl -k "https://api.connexo.net/stats/carrier_seconds? \
  start=2013-06-15 \
  &end=2013-06-20 \
  &granularity=hourly"

  [
    {
      "name": "Local",
      "pointStart": 1356998400000,
      "pointInterval": 3600000,
      "data":[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0]
    },
    {
      "name": "Vitelity",
      "pointStart": 1356998400000,
      "pointInterval": 3600000,
      "data":[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0]
    }
  ]

/stats/carrier_minutes

Description

Total number of minutes of answered calls through all the known carriers.

Methods

  • GET

Returns

  • 200
  • 400 (on invalid or missing arguments)

Required Arguments

  • start: String, in the form "YYYY-MM-DD".
  • end: String, in the form "YYYY-MM-DD".
  • granularity: "daily" | "hourly"

Example

$ curl -k "https://api.connexo.net/stats/carrier_minutes? \
  start=2013-06-15 \
  &end=2013-06-20 \
  &granularity=hourly"

  [
    {
      "name": "Local",
      "pointStart": 1356998400000,
      "pointInterval": 3600000,
      "data":[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0]
    },
    {
      "name": "Vitelity",
      "pointStart": 1356998400000,
      "pointInterval": 3600000,
      "data":[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0]
    }
  ]

/stats/trunk_usage

Description

By trunk type, returns how many channels were used. Trunk type is one of:

  • internal
  • subscriber
  • carrier

Methods

  • GET

Returns

  • 200
  • 400 (on invalid or missing arguments)

Required Arguments

  • start: String, in the form "YYYY-MM-DD".
  • end: String, in the form "YYYY-MM-DD".
  • granularity: "daily" | "hourly"

Example

$ curl -k "https://api.connexo.net/stats/trunk_usage? \
  start=2013-06-15 \
  &end=2013-06-20 \
  &granularity=hourly"

[
  {
    "name": "internal",
    "title": "internal trunk usage",
    "pointStart": 1381363200000,
    "pointInterval": 86400000,
    "data": [0,0,0,7,0]
  },
  {
    "name": "subscriber",
    "title": "subscriber trunk usage",
    "pointStart": 1381363200000,
    "pointInterval": 86400000,
    "data":[0,0,0,0,0]
  },
  {
    "name": "carrier",
    "title": "carrier trunk usage",
    "pointStart": 1381363200000,
    "pointInterval": 86400000,
    "data": [0,0,0,2,0]
  }
]

/stats/carrier_status

Description

Returns statistics about calls made using carriers, their status and driver_status.

Methods

  • GET

Returns

  • 200
  • 400 (on invalid or missing arguments)

Required Arguments

  • start: String, in the form "YYYY-MM-DD".
  • end: String, in the form "YYYY-MM-DD".

Example

$ curl -k "https://api.connexo.net/stats/carrier_status? \
  start=2013-06-15 \
  &end=2013-06-20"

{
  "status": [
    ["error",1], 
    ["finish",1071]
  ],
  "driver_status": [
    ["invalid_number_format",0],
    ["normal_temporary_failure",4],
    ["call_rejected",0],
    ["allotted_timeout",15],
    ["incompatible_destination",0],
    ["answer",704],
    ["normal_clearing",0],
    ["invalid_gateway",0],
    ["invalidargs",0],
    ["unallocated_number",0],
    ["cancel",81],
    ["error",0]
  ]
}

/stats/driver_status_by_carrier

Description

Returns statistics about driver statuses per carrier.

Methods

  • GET

Returns

  • 200
  • 400 (on invalid or missing arguments)

Required Arguments

  • start: String, in the form "YYYY-MM-DD".
  • end: String, in the form "YYYY-MM-DD".
  • carrier_id: Integer

Example

$ curl -k "https://api.connexo.net/stats/driver_status_by_carrier? \
  start=2013-06-15 \
  &end=2013-06-20" \
  &carrier_id=4

{
  "carrier": "Conexiant",
  "series": [
    ["invalid_number_format",0],
    ["normal_temporary_failure",4],
    ["call_rejected",0],
    ["allotted_timeout",23],
    ["incompatible_destination",0],
    ["answer",834],
    ["normal_clearing",0],
    ["invalid_gateway",0],
    ["simulated",0],
    ["dontcall",2],
    ["originator_cancel",230],
    ["success",0],
    ["early media",0],
    ["invalidargs",0],
    ["unallocated_number",0],
    ["cancel",85],
    ["error",0],
    ["missing",0],
    ["busy",35],
    ["user_busy",0],
    ["recovery_on_timer_expire",0],
    ["no_user_response",0],
    ["noanswer",48],
    ["user_not_registered",0],
  ]
}

/account/:account_id/billing_period/close

Description

Closes the current billing period, at the given date. Also opens a new billing period starting at date_to.

Methods

  • POST

Accepts

  • application/json
  • application/x-www-form-urlencoded

Returns

  • 204
  • 404 (on unknown account_id)
  • 400 (if the account does not have an open billing period)

Required Arguments

  • date_to: String, in the form "YYYY-MM-DD".

Example (application/x-www-form-urlencoded)

$ curl -k -v -d "date_to=2013-02-28" https://api.connexo.net/account/4/billing_period/close

Example (application/json)

$ curl -k -v -d@req.json -H "content-type: application/json" https://api.connexo.net/account/4/billing_period/close

Where req.json is something like this:

  {
    "date_to": "2013-02-28"
  }

Clone this wiki locally