search

italia / api-padigitale2026-misura1.3.1-uni-afam

Specifiche API relative alla misura 1.3.1 per l'avviso dedicato alle Università e AFAM
Creative Commons Zero v1.0 Universal
5 stars 4 forks source link

It seems that most APIs only use POST method. #91

Open ioggstream opened 7 months ago

ioggstream commented 7 months ago

It seems that most APIs only use POST methods.

When possible, use a resource-oriented approach, with all methods: GET, POST, PATCH, ...

POST /academic-enrollment-change-request -> create the request GET /academic-enrollment-change-request/{id} -> get the request status

This https://github.com/italia/api-padigitale2026-misura1.3.1-uni-afam/blob/dev/src/IFS09_Iscritti-per-corso-per-anno.yaml#L19 is a typical statistics endpoint. I suggest having a flexible endpoint supporting such queries with GET. Using XML payloads to query data is a legacy.

cc: @denismarini

denismarini commented 6 months ago

Dear @ioggstream ,

Thank you for your recommendations 🐜

To avoid transporting sensitive data on the query string in get method, such as the "tax code" data, we have chosen to use the post method and not that one get. Furthermore, we chose to use the post method to avoid logging sensitive data to the web server side to stay to the less risk side of the solution, even though the interaction is machine to machine and this risk is limited. Since, the difference between the get and post methods is limited, sometimes the chose of post method was the favorite in the team although we agree your recommendations.

Following, some interesting documents:

  1. URIs, Addressability, and the use of HTTP GET and POST

  2. w3shools-ref Compare GET vs. POST chapter

Denis 🥑

ioggstream commented 2 months ago

Let's try to address some of these points. Please, always refer to IETF specifications, since HTTP improved significantly in time, especially after 2014 and now with the latest specifications RFC9110. Moreover consider that not everything that's on W3C is a proper standard (e.g., see this discussion on the HTTP mailing list about URI syntax https://lists.w3.org/Archives/Public/ietf-http-wg/2022AprJun/0173.html)

To avoid transporting sensitive data on the query string in get method, such as the "tax code" data, we have chosen to use the post method and not that one get.

I am not sure this makes sense for data such as "tax code": it is a personal data, but I am not sure whether it's sensitive.

Furthermore, we chose to use the post method to avoid logging sensitive data to the web server side to stay to the less risk side of the solution, even though the interaction is machine to machine and this risk is limited.

  1. The various components of a web infrastructure (proxies, gateway, intermediaries, ..) access a lot of data. Usually, if a server can access a target URI, it can access the message content too. Unless the message content is encrypted, the various parts of an HTTP message are accessible to the web infrastructure in the same way.

  2. using POST avoids logging sensitive information only if applications traces URLs. It does not protect from applications tracing both URL and content; if message content is logged and archived, then I cannot see any security advantage in using POST.

  3. moreover, using GET currently enables caching for frequently requested data, and enables cache validity checks using HEAD. This makes it easier to create services that always retrieve "fresh" data from authoritative sources. Since POST requests are more expensive, and responses cannot be cached, applications usually create "local" copies of the data that may become stale.

Since, the difference between the get and post methods is limited, sometimes the chose of post method was the favorite in the team although we agree your recommendations.

POST is a non-safe, non-idempotent method, using it for both "read" and "write" operations means that before blocking a POST, you need to inspect its content. For this reason, the HTTP WG is working on a new, cacheable, idempotent and safe QUERY method https://httpwg.org/http-extensions/draft-ietf-httpbis-safe-method-w-body.html that covers the above use case.

I suggest engaging with the HTTP wg to support the standardization of the QUERY method, and investigate in how to make it work with caching mechanisms.

denismarini commented 2 weeks ago

Dear Roberto @ioggstream,

Thank you very much for the detailed information and the well-supported arguments you provided with high-quality material. We completely agree with you and will certainly take your observations into consideration for the future. Your concerns and considerations have also been raised by other team members and stakeholders.

However, I must inform you that the entire working group has decided to keep the APIs as they are. For the currently anticipated use cases, there would not be significant differences, and the APIs have already been published in the call for proposals. Some institutions have already started developing them.

We greatly appreciate your feedback, which we consider invaluable, and it will undoubtedly be useful in the future. We are keeping this issue open so that anyone interested can further explore it.

Thank you again for your contribution 🤗

ioggstream commented 2 weeks ago

Thanks @denismarini . Really happy to provide insights, and sad not to have enough time to provide them more promptly.

Go on with the transformation, and Peace, R