Mobile Energy Reduction API Guide v6.1

Introduction

The purpose of this document is to specify the RESTful API over which network operators interact with the Energy Reduction Power State Controller (PSC).

The Power State Controller API may differ as each version is released, and functionality is tailored.

The PSC provides energy savings recommendations based on the current network traffic patterns as well as the energy state of each cell site. PSC exposes the following endpoints for this purpose:

• OSS Power State. Accepts the current power of one or more cell sites. This endpoint should be called every minute (or other interval at which the recommendations change) including the whole network state. Failure to do so will cause the PSC to generate power recommendations based on inaccurate data, which may lead to low quality recommendations.
• Recommended Power State. Returns the recommended power state of cells in the network. Energy Reduction generates recommendations on a minute-by-minute basis. As a result, the rec-power-state endpoint should be called every minute to receive the most current recommendations.

Authentication

This ER Power State Controller version does not require any type of authentication to call the endpoints. Therefore, operators should ensure network access controls are in place to appropriately limit access to the endpoints.

All API requests must be made over HTTP.

All PSC endpoints are accessible from a common base URL. The value of the base URL may vary from deployment to deployment, but will follow this format:

    http://{psc_server}:{port}

For example, if the ER server’s IP address is 10.100.90.34, and the Power State Controller is listening on port 8084, then the base URL would be http://10.100.90.34:8084.

Error Handling

In the event of an error, endpoints will return standard http error codes. Given the critical importance of ensuring the availability of the network, Operators are strongly encouraged to implement fail-safe mechanisms based on some error threshold or based on the lack of recent recommendations.

Endpoint: OSS Power State

This endpoint should be called every minute (or other interval at which the recommendations change) including the whole network state.

To update the oss-power-state:

curl {base_URL}/oss-power-state --request POST --header "Content-Type: text/csv" --data power_state_csv

Where power_state_csv is a list of ECI’s and their current power state in comma separated values format.

Calls to the oss-power-state will return a success message HTTP 200 when the power state status is successfully received. However, the endpoint does not currently return any errors in the event there is invalid data within the csv.

Example with Powershell:

> $csvString = @" Eci,powerOn 0x1928,false "@> Invoke-WebRequest -Uri "http://10.100.90.34:8084/oss-power-state" -Method POST -ContentType "text/csv" -Body $csvString

Response should be similar to:

StatusCode        : 200
StatusDescription :
Content           : {"message":"Processed 1 records with 0 errors.","status":0,"count":1,"errorCount":0}

Example with Bash:

$ csvString=$(cat <<EOFEci,powerOn0x1928,falseEOF)$ curl -X POST "http://10.100.90.34:8084/oss-power-state" -H "Content-Type: text/csv" --data-binary "$csvString"

Response should be similar to:

{"message":"Processed 1 records with 0 errors.","status":0,"count":1,"errorCount":0}

Endpoint: Recommended Power State

The rec-power-state object represents the recommended power state of ECIs across the network. Recommendations are made as frequently as every minute.

This endpoint should be called every minute to ensure timely adjustments to the power state of the network. Failure to do so may result in lost energy savings opportunity or congestion as a result of not powering up an ECI in advance of predicted load.

To receive Power State recommendations:

$ curl {base_URL}/rec-power-state --request GET

Calls to the rec-power-state endpoint return a list of power state recommendations in comma separated value format.

Example with Powershell:

> Invoke-WebRequest -Uri "http://10.100.90.34:8084/rec-power-state" -Headers @{ "Content-Type" = "text/csv" }

Response should be similar to:

StatusCode        : 200StatusDescription :
Content           : Eci,powerOn
                    0x9dc2f23,true
                    0x93ff502,true
                    0x9c41632,true
                    0x9412f01,true
                    0x92adc43,true
                    0x9c68f32,true
                    0x9407641,true
                    0x9dbf603,true
                    0x98dc001,true
                    0x9c69b21,true
                    0x9c68a02,true
                    0x9c68f03,true
                    0x9f60f2...

Example with Bash:

$ curl -X GET "http://10.100.90.34:8084/rec-power-state" -H "Content-Type: text/csv"

Response should be similar to:

Eci,powerOn0x9c40142,true0x9c65a23,true0x92a2922,true0x9dbf222,true0x9c66e21,true0x9c42e22,true0x9dc3303,true0x93fa522,true0x9dbee42,true