Arc API versioning system and breaking and non-breaking changes definitions.
Versioning system
The Arc API uses a dated version scheme (YYYY-MM-DD). A new version is released when one or more breaking changes are made to the API. As we will always ensure changes are backwards compatible, breaking changes on new versions will not impact existing integrations. Though new functionality is often available to old API versions, we recommend you to use the latest version of the API.
Every API request must specify the desired version through the Arc-Version header. For example: Arc-Version: 2021-11-17. Every response will include the version used in the Arc-Version header. API requests that do not provide a valid Arc-Version header will return an error with HTTP status 400.
Every API request MUST specify the desired version through the Arc-Version header.
Breaking and Non-Breaking Changes
Breaking Changes
Here is a list of representative examples that we would consider as breaking changes:
Headers
- Removing a request header
- Removing a required response header
- Adding a required request header
- Changing a response header from required to optional
Request and Response Bodies
- Adding a required field to a request body
- Renaming a field in a request body
- Removing a required or optional field from a request body
- Removing a required or optional field from a response body
- Changing a field in a response body from required to optional
- Changing the type of a field in a request or response body
Downloadable CSV files
- Changing how the columns are ordered
- Updating column names
When we make breaking changes, it will always be accompanied by a new version release. We will update the Arc Platform Changelog and send an email to you with a link to the Changelog.
Non-Breaking Changes
We consider the following changes to be non-breaking changes:
Headers
- Changing a request header entry from required to optional
- Changing a response header entry from optional to required
- Adding a request or response header entry
Requests and Response Bodies
- Changing a field in a request body from required to optional, without a behavioral change
- Changing a field in a response body from optional to required
- Adding new optional parameters for existing endpoints
- Adding new properties to an existing API response schema
- Adding new webhook event types
Downloadable CSV files
- Adding new columns at the end of the template
Others
- Adding new endpoints
- Changing error_codes to be more specific for errors that cannot be resolved by the developer consuming the Arc API. For example, changing a 500 error code to a 504 error code.
Examples of Non-Breaking Changes in the Arc Context
Here are some examples of changes that will happen from time to time in the utility data context. We considered these types changes as non-breaking changes. Therefore, you need to build your integration in a way that can handle these types changes.
| Scenario | Who makes the change | Description | Impact on your data | Integration recommendation |
|---|---|---|---|---|
| Account number changes | Provider | These changes typically happen when the provider has a business reason to do so. For example, a provider may update their accounting system which requires them to update all existing account numbers. | The data you would expect for an account number will be presented under a different account number. | You should keep an internal mapping of old and new account numbers for future reference. |
| Meter number changes | Provider | Compared to account number changes, meter number changes happen more frequently and are a result of how meters work. Most meters have a three to five year lifecycle and may be replaced after that. When an old meter is replaced, the old meter number will no longer be updated with new data. New data will have the meter number of the new meter. | In most cases, you will continue to see the same number of meters in the meterData object or on the account, however, the meterNumber (and normalizedMeterNumber) and meterId would be updated. | You should keep an internal mapping of old and new meter numbers for future reference. |
| Summary Keys moving from account level to meter level and vice versa | Arcadia | In the Arc context, “Summary Keys” refers to a set of meta-information that may not fit easily into the Account, Meter, Usage, or Charge resource. Refer to this [link] for a full list of Summary Keys. Most of the time, we assign Summary Keys to the accountData resource. However, they can be assigned to any level of the Arc data model.We may make changes to where we assign a Summary Key in order to make the data model more intuitive. | A nullable and optional field that used to be populated at the account level is no longer populated. The same data will be populated in the same nullable and optional field at the meter level. Or vice versa. | You should build your integration to check for the same field at both the account and meter level. |
Number of meter resources returned in the meterData object. | Arcadia | When we realize a smart meter and a mechanical meter are duplicative of each other, we will remove the mechanical meter. You would see one or more less meter resources in the meterData object. | The overall usages and charges data at the account level would not be impacted as we would only remove duplicates. | For extra assurance to avoid double counting, only count resources that are flagged as CONTRIBUTING in the respective contributionStatus fields. |
Number of usage/charge resources returned in the usages/charges object.Utility account holder. | Provider | When the utility account holder switches tariffs or when providers update their invoice formats, it may result in a different number of usages/charges returned in the usages/charge object. | You would see a different number of usage/charge resources in the usages/charges object. | You should not expect the number of usages/charges in the usages/charges object to stay the same. |
| Tariff name change. | Arcadia Utility account holder Provider | The utility account holder may choose to update their tariff at any time. As a result of being on a different tariff, the tariff name will change. The provider may choose to update the names of their tariffs. We may update a tariff name when we realize that we we have a more accurate interpretation of the data. | The field tariffName will have a string that is different from the previous one. | Your API integration should be flexible enough to handle the string for this field to change. |
| Tariff Rate Component Type field change | Provider | The provider may change this on the bill from time to time. | This field is designed to suggest that changes should be expected. It is an enumeration of strings. | Your API integration should be flexible enough to handle all possible strings, rather than a subset of possible strings. For example, do not hardcode your integration to only handle the value maxPeak as this field may change. |
| Unit of measure change for a specific usage item | Provider Arcadia | As bill formats published may contain imprecise charge and usage descriptions, we often have to determine when a charge item or usage item is best identified as having no explicit unit measure. Our interpretation always derives from the bill and the bill only. When a usage or charge item has no explicit unit of measure, Arcadia will use UNDEFINED in the field response. | At times, seeing UNDEFINED as the unit of measure for charge items or usage items is expected. | If you have a preferred unit of measure mapping for specific accounts, you need to build custom logic on your end to account for the mapping. |
Usage item changes from citedUsage to measuredUsage or vice versa. | Provider Arcadia | citedUsage is not measured by a meter reading on the current statement. This is the billed usage. Whereas the measuredUsage is measured by a meter reading on the current statement. This is the actual usage.As bill formats published may contain imprecise charge and usage descriptions, we often has to determine when a charge item or usage item is best identified as cited or measured. Our interpretation always derives from the bill and the bill only. | For an account, whether you see both or either fields populated may differ from statement to statement. | You should always look for values in both fields to ensure you are not missing data |
usages/charges items changes from NON_CONTRIBUTING to CONTRIBUTING or vice versa | Arcadia | As bill formats published may contain imprecise charge and usage descriptions, Arcadia often has to determine whether a usage/charge item is best identified as a duplicate/redundant value. Our interpretation always derives from the bill and the bill only. | An usages/charges item that is considered as NON_CONTRIBUTING in one context may be CONTRIBUTING in a different context. | You should not assume if a usages/charges item is NON_CONTRIBUTING on one statement, that same usage/charge item will always be NON_CONTRIBUTING on all future statements. |
usages/charges item moves from the accountData object to the meterData object or vice versa. | Provider Arcadia | As bill formats published may contain imprecise charge and usage descriptions, Arcadia often has to determine whether the usage/charge item should be reflected at the account or meter level. Our interpretation always derives from the bill and the bill only. | A nullable and optional field that used to be populated at the account level is no longer populated. The same data will be populated in the same nullable and optional field at the meter level. Or vice versa. | You should build your integration to check for the same field at both the account and meter level. |