Introduction to Momentum Energi External API

What is this?

Momentum Energi External API is the customer facing API of Momentum Energi, a SaaS solution mainly used for managing facilities' energy consumptions. We provide a REST API built on RESTful design principles.

Our API uses resource-oriented URLs that leverage built in features of HTTP, like authentication, verbs and response codes. All request and response bodies are JSON encoded, including error responses. Any off-the-shelf HTTP client can be used to communicate with the API.

API versions

This is a versioned API that uses the endpoints' URIs for routing between different versions of the API. Endpoints as well as whole API versions can be marked as deprecated indicating that they have been replaced by newer versions. It is strongly recommended to adapt to the newer versions because deprecated versions are subject to removal.

Endpoint definitions

All available API versions and endpoints can be found in the menu item API here above.

Quickstart guide

Prerequisites

Before being able to connect to the API, the following needs to be done.

API user

You will need to setup a specific user in Momentum Energi. The user must have a role containing the operation named Access external API acc_extapi. Setup the user's access rights according to your preferences. All data accessed through the API will be restricted by the user's access rights.

Client information

You will have your own client configuration in Momentum Energi. The client information is used when authenticating. In order to configure your API client, we need the below information. Please contact your account manager at Momentum to begin the process of enabling API access. If you don't have a specific account manager assigned to your company, please contact our help desk via Momentum Kontakt.

Mandatory information for API access:

  • Client name, for example YourCompanyNameIntegrationService
  • Client secret, which is a secret that is stored encrypted in Momentum Energi and used when authenticating. See section Authenticate below.
  • The purpose of accessing our API
  • Contact person with name, email and phone number

Authentication

This API is authenticated using OAuth2 Auth over HTTPS. Any requests over plain HTTP will fail.

All requests are associated with a specific user in Momentum Energi, see prerequisites section above, and permissions are limited to that user's capabilities.

Current OAuth flow is Resource Owner but please note that this will be a subject of change in the near future because plans are that we will switch to Authorization Code flow with PKCE.

The URL for authenticating is https://api-rc.momentum.se/identity/connect/token. Pass along the information in the table below in the request body as x-www-form-urlencoded

Upon succesful authentication you will be receiving your access token of JWT type in the response's header. Use that access token when performing your requests to the API.

Key Value Example
client_id Identification of the client. Value is preregistered by Momentum and it's value is external_access. external_access
client_secret Secret that only you know and which are set up during section Prerequisites above. The secret is coupled with the client id. MyPrivateAPISecret
grant_type In what way are you going to authenticate the API user. For now, only password is a valid value. password
username The user name and company name as configured in Momentum Energi. Please see section Prerequisites above. apiUser@myCompanyName
password The API user's password in Momentum Energi. mySecretPassword
scope Which scopes does the authentication request want access to? For now, only external_access is a valid value. external_access

Access token lifetime

The lifetime of the access token is one (1) hour which also is informed of in the authentication response headers. Currently there is no support for refresh tokens and requesting part therefor needs to handle renewing access token via above mentioned authentication procedure manually.

Requests

The base URL for all requests to the API is https://api-rc.momentum.se.

HTTP Verbs

We use standard HTTP verbs to indicate intent of a request:

GET To retrieve a resource or a collection of resources.

POST To create a resource.

PUT To set/update a resource.

DELETE To delete a resource.

JSON Bodies

All POST- and PUT-requests are JSON encoded and must have have content type of application/json, or the API will return a 415 Unsupported Media Type status code.

Responses

All response bodies are JSON encoded.

A single resource is represented as a JSON object:

{
  "field1": "value",
  "field2": true,
  "field3": []
}

A collection of resources is represented as a JSON array of objects.


    {
    "data": [
        {
        "itemKey": "sample string 1",
        "usageType": "sample string 2",
        "mediaClass": "sample string 3",
        "mediaType": "sample string 4",
        "startDate": "2021-10-15T10:41:04.393597+02:00",
        "stopDate": "2021-10-15T10:41:04.393597+02:00",
        "consumptionUnit": "sample string 7",
        "consumption": 1.1,
        "consumptionNormalized": 1.1,
        "energyUnit": "sample string 8",
        "energy": 1.1,
        "energyNormalized": 1.1,
        "lastUpdated": "2021-10-15T10:41:04.3946315+02:00"
        },
        {
        "itemKey": "sample string 1",
        "usageType": "sample string 2",
        "mediaClass": "sample string 3",
        "mediaType": "sample string 4",
        "startDate": "2021-10-15T10:41:04.393597+02:00",
        "stopDate": "2021-10-15T10:41:04.393597+02:00",
        "consumptionUnit": "sample string 7",
        "consumption": 1.1,
        "consumptionNormalized": 1.1,
        "energyUnit": "sample string 8",
        "energy": 1.1,
        "energyNormalized": 1.1,
        "lastUpdated": "2021-10-15T10:41:04.3946315+02:00"
        }
    ],
    "total": 36,
    "take": 2,
    "skip": 0
    }

In general, timestamps are in UTC and formatted as ISO8601. Unset fields will be represented as a null instead of not being present. If the field is an array, it will be represented as an empty array, i.e. [].

HTTP Status Codes

We use HTTP status codes to indicate success or failure of a request.

Success codes:

  • 200 OK - Request succeeded. Response included
  • 201 Created - Resource created. URL to new resource in Location header
  • 204 No Content - Request succeeded, but no response body

Error codes:

  • 400 Bad Request - The request was unacceptable, often due to missing a required parameter.
  • 401 Unauthorized - No authentication credentials provided or authentication failed
  • 403 Forbidden - Authenticated user does not have access
  • 404 Not Found - Resource not found
  • 415 Unsupported Media Type - POST/PUT/PATCH request occurred without a application/json content type
  • 422 Unprocessable Entry - A request to modify or create a resource failed due to a validation error
  • 429 Too Many Requests - Request rejected due to rate limiting. We recommend an exponential backoff of your requests.
  • 500, 501, 502, 503, etc - Something went wrong on Momentum's end.

Errors

All 400 series errors will be returned with a JSON object in the body and a application/json content type.

{
   "message": "Not Found"
}

Pagination

Requests for collections can return between 0 and 10.000 results, controlled using the query parameters Take and Skip. All end points are limited to 3.000 results by default. In the example below, the response is skipping the first 450 results and returning result 451 to 600, i.e. page 4.

GET api/external/v1/statistics/level/E/updatedAfter/2021-01-01?Take=150&Skip=450

Not all endpoints may support pagination. If not, the full result set is returned no matter what values Take and Skip has.