chore/clarify-post-semantics

[narve]

Fixes #63

[cdmNSIDE]

Hello @narve,

How will the platform know if the resource must be created or updated when using those POST requests?

• If an ID is provided within the resource and this ID already exists in the database -> the resource will be updated
• If an ID is provided within the resource and this ID already does not exist yet in the database -> the resource will be created
• No ID provided within the resource -> the resource will be created Is that correct ? Can't we simply use the PUT and PATCH requests for that ? Isn't it redundant to be able to do it with two different endpoints ?

If we accept your modifications, then shouldn't we do the same for:

• portfolios
• orders
• flexibility zones ?

[narve]

Good points you make! I think that the "standard" behaviour for POST is to create (or fail if id already exists), and for PUT/PATCH to update (or fail if id is empty). This makes sense in most cases. Including flexibility zones, orders, portfolios etc.

However, for meter readings / baselines, when batch uploading (e.g. via text files), I think the behavour should be a bit different. For a given reference, e.g. portfolio, and a given period, there should only be one meter reading. One way of viewing this is that the identifier for a meter reading should have been (and can even be, thats up to the FMO) a concatenation of reference-periodfrom-periodto.

After first uploading a file containing meter readings for a given portfolio for a given day, all values are created. However, if you change one value in the file and upload the file again, I think the expectation is that the values are updated.

That is why I added the documentation to only those batch-uploading endpoints.

[cdmNSIDE]

So if it concerns the endpoints where a file is uploaded, shouldn't the modifications rather concern:

• POST /MeterReadings/import (which already exists, we may only have to update the description and the error code)
• POST /BaselineIntervals/import (which does not exist yet) ?

[narve]

Well... that is a good question. I see that I modified the descriptions of the POST single-item as well. I guess we can require that endpoint to only create. This is actually the way NODES behaves today anyway.

And we should probably add a /BaselineIntervals/import endpoint, since batch-uploading baselines is a normal operation.

[narve]

@cdmNSIDE @GiancarloNSIDE I've added a baseline interval batch import endpoint, and clarified that it is only the batch imports that will either create or update. POST operations will always create (or fail).

Is this PR ok now?

[cdmNSIDE]

Hi Narve,

I don't know why but I can't submit in line comments directly in the file, so I wrote them below:

• For the POST BaselineIntervals/import endpoint, the tag should be BaselineInterval instead of MeterReading
• For the POST MeterReadings/import endpoint, I think that the return code should be 204 instead of 201 as there is no content in the body of the response.
• For the POST BaselineIntervals/import endpoint, I think that the return code should be 204 instead of 201 as there is no content in the body of the response.
• Line 64: I would replace "Create a new Portfolio" by "Create a Portfolio" to be consistent with the change done for the baseline.
• Line 355: The operation ID of the endpoint POST BaselineIntervals could simply be "BaselineInterval_Create" instead of "BaselineInterval_Create_Single" (the word "single" is not written in the other operation Ids)
• Line 1072: I would replace "Create a new Order" by "Create an Order" to be consistent with the change done for the baseline.

I am ok with the rest of the file, this PR can be merged once the changes are done (if you agree with them)

[narve]

Great, thanks for the feedback! I've incorporated your suggestions and will merge it to main now.