search

belgif / rest-guide

REST Guidelines of Belgian government institutions
https://www.belgif.be/specification/rest/api-guide/
Apache License 2.0
26 stars 4 forks source link

compare and reconcile belgif and Flanders REST guidelines #54

Open pvdbosch opened 4 years ago

pvdbosch commented 4 years ago

Informatie Vlaanderen has REST guidelines on:

These are more limited and different than both the DigiPolis and belgif/gcloud ones.

We should try to reconcile the Flanders and belgif/gcloud guidelines. Ideally the Informatie Vlaanderen guidelines could become a superset of the belgif/gcloud ones.

A first step is to make a summary of:

bertvannuffelen commented 4 years ago

In https://data.vlaanderen.be/standaarden/standaarden-in-ontwikkeling/api-guidelines/api-guidelines-index.html one can find a presentation containing a comparison between the different api-guidelines.

As one can see there is a lot of correspondence. Sometimes small details differ. But the spirit is the same.

pvdbosch commented 4 years ago

After a quick look, these seem to be the incompatibilities with the most impact in descending order:

Btw, slide 41: gCloud "Vermijd Vary: Accept" is incorrect. The gcloud guide mandates to use it when the API supports content negotiation. In other cases, it's unspecified.

"If a resource supports multiple content types through negotation, the response header Vary: Accept MUST be added to avoid undesired cache hits (also see Caching)."

bertvannuffelen commented 4 years ago

The 'vary' case, indeed, a misreading from my site.

pvdbosch commented 4 years ago

There's a next meeting on the differences between the guides organized by IV, to which we are invited. We can address the incompatibilities there.

bertvannuffelen commented 4 years ago

Next OSLO session takes place 9 june.
In this session we will retake the comparison between the existing REST API guidelines in Belgium presented in the first OSLO session on the REST API guidelines.

It will happen online via a Microsoft Teams meeting. After registration an invite will be sent. Short before the online meeting link will be shared. Registration can be done at
https://dynamicforms.crmiv.vlaanderen.be/EventModule/Page/Show/ad923f45-869a-46ab-bc43-f62f6a887e25?PreFillIds=d35997ca-cc41-ea11-a812-000d3ab7be54%2c92660270-159c-ea11-a812-000d3ab7b5a7&_cldee=YmVydC52YW4ubnVmZmVsZW5AdGVuZm9yY2UuY29t&recipientid=contact-cdf82105fc7ae411b1876c3be5beee80-0f14a6a172ab4161b9a81c59eac644d8&esid=ff8a6862-249c-ea11-a812-000d3ab7b5a7

pvdbosch commented 4 years ago

https://data.vlaanderen.be/standaarden/standaarden-in-ontwikkeling/api-guidelines/api-guidelines-index.html has two presentations (werkgroep 1 on REST standards, 2nd on data sync/events). Security werkgroep is being prepared.

pvdbosch commented 2 years ago

we should check if there are still any incompatibilities