REST HTTP Interface - Buckets (3.2)

Owned by Jenni Wallin
Jun 08, 2023
14 min read

Provisioning is supported via a REST HTTP Interface which is implemented using the standard HTTP methods  GET, PUT, POST and DELETE. The interface supports XML and JSON formats.

The REST HTTP Interface runs on the EC Web Interface and is started when the EC process is started. Authentication is performed against the platform, if possible. If the platform is unreachable the user is authenticated against the locally defined user (configured in  EC web interface properties).

Retrieving Buckets

To retrieve all buckets for a subscriber:

Example Retrieving Buckets

GET http://localhost:9090/PCC/Buckets/<subscriber key>/Bucket HTTP/1.0

Example output:

{
    "Buckets": [
        {
            "Product": 1001,
            "Counters": [
                {
                    "Usage": {
                        "entry": [
                            {
                                "key": 0,
                                "value": 0
                            },
                            {
                                "key": 1,
                                "value": 0
                            },
                            {
                                "key": 2,
                                "value": 0
                            }
                        ]
                    }
                }
            ],
            "ID": "1",
            "StartTime": "2014-08-04 12:00:00",
            "StopTime": "2014-08-12 00:00:00"
        }
    ]
}

Return Codes

No return codes will be sent. A list with 0 or more elements will be returned.

Retrieving a Specific Bucket

To retrieve a specific bucket with a certain ID:

Example Retrieving a specific bucket

GET http://localhost:9090/PCC/Buckets/<subscriber key>/Bucket/<id> HTTP/1.0

Example output:

{
    "Product": 1001,
    "Counters": [
        {
            "Usage": {
                "entry": [
                    {
                        "key": 0,
                        "value": 0
                    },
                    {
                        "key": 1,
                        "value": 0
                    },
                    {
                        "key": 2,
                        "value": 0
                    }
                ]
            }
        }
    ],
    "ID": "1",
    "StartTime": "2014-08-04 12:00:00",
    "StopTime": "2014-08-12 00:00:00"
}

Return Codes

CodeDescription
200Will be returned if the bucket was successfully retrieved.
204Will be returned if the bucket did not exist.
500Will be returned if a server error occurred. 

Creating a Bucket

To create a bucket:

Example Creating a bucket using xml

POST http://localhost:9090/PCC/Buckets/<subscriber key>/Bucket 
 Bucket HTTP/1.0 
 Content-Type: application/xml

 The xml-data should be structured as follows:
    <Bucket> 
         <Counters> 
             <Usage> 
                 <entry> 
                     <key>0</key>

                              <value>100</value> 
                 </entry>
                <entry>
                    <key>1</key>
                    <value>200</value>
                </entry>
                <entry>
                    <key>2</key>
                    <value>300</value>
                </entry>
            </Usage>
        </Counters>
        <ID>1016</ID> 
        <Misc>
            <entry>
                <key>mykey</key>
                <type>string</type>
                <value>myvalue</value>
            </entry>
        </Misc>
        <Product>1006</Product>
        <StartTime>2015-01-02 18:00:00</StartTime>
    </Bucket>

Example Creating a bucket using JSON

POST http://localhost:9090/PCC/Buckets/<subscriber key>/Bucket
 Bucket HTTP/1.0 
 Content-Type: application/json 

 The json-data should be structured as follows:
 {
    "ID": "1016",
    "Misc": {
        "entry": [
            {
                "key": "mykey",
                "type": "string",
                "value": "myvalue"
            }
        ]
    },
    "StartTime": "2015-01-02 18:00:00",
    "Product": 1006,
    "Counters": [
        {
            "Usage": {
                "entry": [
                    {
                        "key": 0,
                        "value": 100
                    },
                    {
                        "key": 1,
                        "value": 200
                    },
                    {
                        "key": 2,
                        "value": 300
                    }
                ]
            }
        }
    ]
}

Note!

The subscriber is created if it does not exist when the command is called.

Return Codes

CodeDescription
201Will be returned if the bucket was successfully created.
500Will be returned if a server error occurred.

Updating a Bucket

Updates are made using  PUT .

Example Updating a bucket

PUT http://localhost:9090/PCC/Buckets/<subscriber key>/Bucket/<id> HTTP/1.0

Return Codes

CodeDescription
200Will be returned if the bucket was successfully updated.
500Will be returned if a server error occurred.

Deleting a Bucket

To delete a bucket:

Example Deleting a bucket

DELETE http://localhost:9090/PCC/Buckets/<subscriber key>/Bucket/<id> HTTP/1.0

Return Codes

CodeDescription
200Will be returned if the bucket was successfully deleted.
204Will be returned if the bucket that was intended to be deleted did not exist.
500Will be returned if a server error occurred.

Retrieving All Sessions for a Subscriber

To retrieve all sessions for a subscriber:

Example Retrieving sessions

GET http://localhost:9090/PCC/Buckets/<subscriber key>/Session HTTP/1.0

Example output:

{
    "Sessions": [
        {
            "ID": "gx;222;1000009",
            "Misc": {
                "entry": [
                    {
                        "key": "origin_host",
                        "type": "string",
                        "value": "sim"
                    },
                    {
                        "key": "origin_realm",
                        "type": "string",
                        "value": "example.com"
                    }
                ]
            },
            "InstalledRules": [
                {
                    "Rules": [],
                    "QoS": 0
                }
            ],
            "Reservations": [
                {
                    "Granted": {
                        "entry": [
                            {
                                "key": 1,
                                "value": 1
                            }
                        ]
                    },
                    "Products": [
                        2
                    ],
                    "Misc": {
                        "entry": []
                    }
                }
            ],
            "LastActive": "2015-10-30 11:02:55"
        }
    ]
}

Return Codes

No return codes will be sent. A list with 0 or more elements will be returned.

Deleting a Subscriber

To delete a subscriber:

Example Deleting a subscriber

DELETE http://localhost:9090/PCC/Buckets/<subscriber key> HTTP/1.0

Note!

Deleting a subscriber means deleting the whole object found at:

http://localhost:9090/PCC/Buckets/<subscriber key>

Any Buckets and Subscribers belonging to this <subscriber key>-object will get deleted as well.

Return Codes

CodeDescription
200Will be returned if the subscriber was successfully deleted.
204Will be returned if the subscriber that was intended to be deleted did not exist.
500Will be returned if a server error occurred.

Retrieving Information about a Subscriber

To retrieve information about a subscriber:

Example Retrieving information about a subscriber

GET http://localhost:9090/PCC/Buckets/<subscriber key>/Subscriber HTTP/1.0

Example output:

{
    "Groups": [
        "Group1"
    ],
    "IsChanged": false,
    "SentNotifications": [2],
    "Misc": {
        "entry": [
            {
                "key": "billing_system",
                "type": "string",
                "value": "test"
            }
        ]
    },
    "Notifications": [1]
}

Return Codes

CodeDescription
200Will be returned if the information about the subscriber was successfully retrieved.
204Will be returned if the subscriber did not exist.
500Will be returned if a server error occurred.

Updating a Subscriber

To update a subscriber:

Example Updating a subscriber

PUT http://localhost:9090/PCC/Buckets/<id>/Subscriber HTTP/1.0

Return Codes

CodeDescription
200Will be returned if the subscriber was successfully updated.
50Will be returned if a server error occurred.

Error Codes

There are several different codes that can be returned for the different operations.

When creating a UDR:

Error code

Description

201

Will be returned if the UDR was created.

409

Will be returned if a UDR with the stated key already exists, or if there are dependencies missing.

415

Will be returned if the UDR key is of type string and the key is missing, or if the key type is incorrect.

500

Will be returned if the UDR requires references that are missing, or if there was an error.

When retrieving one UDR:

Error code

Description

200

Will be returned if the requested UDR was found.

204

Will be returned if there are no UDR with the stated id.

500

If there was an error.

When retrieving all UDRs:

Error code

Description

200

Will be returned with an empty list or with a list containing the UDRs.

When updating a UDR:

Error code

Description

200

Will be returned if the UDR was updated successfully.

408

Will be returned if the keys in the URL and the XML are different, or the key in the URL is set to "0".

409

Will be returned if the UDR requires references that are missing.

500

Will be returned if there was an error.

When deleting a UDR:

Error code

Description

200

Will be returned if the UDR was deleted successfully.

204

Will be returned if there are no UDR with the stated key.

409

Will be returned if the UDR is referenced by another UDR.

500

Will be returned if there was an error.