Clarify lifecycle / required API poll time

[forsberg]

With #9 closed, the Tariff.product field became a persistent identifier that together with Tariff.validPeriod can be used to identify the same tariff over time.

What's still unclear to me is what to expect in the API response when it comes to historical and future tariffs. Will the response contain all previous tariffs for each product? When will a new version of a product become available?

In our use case, we will store which tariff a specific customer have in a database (see #38 for considations). We use this information to optimize the energy usage for our customers. We therefore need to ensure that there's always a valid tariff information available for the customer, i.e one where validPeriod matches the time of compute ("Today" or "Tomorrow").

I think the API specification need to clarify:

• Generally that it is expected that there will be multiple Tariff objects per Tariff.product, with varying Tariff.validPeriod.
• How much of historical Tariff objects should be available in the API? Ideally, it should be possible to retrieve historical Tariffs for each Tariff.product for some time in the past, as that allows calculating historical cost.
• At what point in time is it required for the API to reply with information about a future Tariff. I.e, if we have a Tariff that has a toExcluding 2026-01-01, when at the latest can an API consumer expect to get a reply that contains information about the replacement tariff with fromIncluding 2026-01-01? This also determines how often an API consumer needs to poll each API in order to always have valid information per Tariff.product available.

From a resilience point of view, the earlier the better when it comes to future Tariff availability - having more time to poll for new info means the uptime requirements on the Tariff API endpoints are less stringent.

[larwa99]

I completely agree with you that lifecycle management is critical and I can only answer from a Tekniska verken perspective how I view this and what our plan is.

• We normally have new pricing/models in place a couple of months before the current ones are invalidated to have time to update all administrative systems.
• Since this is the first year with a tariff-API I'm not sure of the exact timing, but I expect us to publish the new tariffs at least a month before they become valid, i.e. some time in November.
• From that time both the currently valid ones (2025-tariffs) and the upcoming ones (2026-tariffs) will be included in the API response when requesting all tariffs.
• At some point in january 2026 we will remove the 2025-tariffs and it will only be 2026-tariffs that will be part of the API response.

The above is for planned tariff updates. There can also be other reasons for an update and we did for example a small correction in March and replaced the definitions we first published in February. It makes no sense to keep incorrect tariffs, especially since their validity period would have been the same as the new ones. And it would be wrong to change some data in the definition and keep the same Tariff.id (UUID). If there is a change - set a new Tariff.id. In that way anyone interested in ensuring they have the latest and updated tariff definitions can request all tariffs once a day and verify that the Tariff.id for each Tariff.product is the same as your local copy. So the contract is simple - if the same Tariff.id is used the tariff is unchanged.

[mattiaspalmqvist]

That would be reasonable to enforce a requirement on DSO:s to provide the next in line definition for a product before the previous is invalid. But I'm not sure how we should document that kind of requirements. We could try to fit this one into the specification, but it could result in a cluttered specification. Another way of handling this is to have some kind of "DSO server side implementation ruleset" document.

Embedded in API specification:

• Pros: One place to handle all developer documentation.
• Cons: Adding several rules like this may clutter de specification with information that is not really OpenAPI specification documentation and can add complexity when implementing the API.

Separate document:

• Pros: We will have a clear place of documenting implementation guidelines more thoroughly than is possible in the OpenAPI specification.
• Cons: More places for a developer to look for information.

At the end I think that we will need a place for documenting implementation guidelines and rules at a more thourough level than is possible in the OpenAPI specification. So I vote for adding one implementation document for server/client side respectively. It can be one .md file for (one fore each client/server) to start with.

[larwa99]

I agree that we should keep the guideline documents outside the API specification. The specification should instead have links to the guidelines so it is easy to find them if you read the specification in its own context. Sounds great with .md files.