search

DependencyTrack / dependency-track

Dependency-Track is an intelligent Component Analysis platform that allows organizations to identify and reduce risk in the software supply chain.
https://dependencytrack.org/
Apache License 2.0
2.45k stars 532 forks source link

Description for PUT and POST requests #3765

Closed tapmch closed 1 month ago

tapmch commented 1 month ago

Current Behavior

dtrack

Steps to Reproduce

  1. In the swagger json the description for post requests relates to updates whereas put requests relate to creation. Shouldn't it be the opposite?

Expected Behavior

POST -> create PUT -> update

Dependency-Track Version

4.7.x

Dependency-Track Distribution

Container Image

Database Server

PostgreSQL

Database Server Version

13.5

Browser

Google Chrome

Checklist

nscuro commented 1 month ago

Is that a personal opinion or do you have some sort of industry standard document that you can reference?

Honestly I personally don't really care, and I know people have been fighting over these conventions since forever. At this point I strongly believe what matters is that you choose one way to do it, and stay consistent with it.

aravindparappil46 commented 1 month ago

I agree with @nscuro.

According to IETF RFC 9110, PUT can also be for creates:

The PUT method requests that the state of the target resource be created or replaced with the state defined by the representation enclosed in the request message content

Best not to spend too much time on semantics here.

tapmch commented 1 month ago

PUT is idempotent (where POST is not) which in my opinion makes PUT more suitable for updates. But I agree, I didn't want to start a long discussion here. Feel free to close the issue.

markusmuellerusi commented 1 month ago

https://restfulapi.net/http-methods/ It is a common practice to use put for updates, patch for partial updates and post for creating resources. The response for creating with post is 201 (created), for updating 200 (ok). All rest APIs I know, use this pattern except alpine. The issue is not a swagger, it's the implementation in dtrack and alpine in using http verbs. But I think, it will be a big and incompatible change with an impact on frontend and all public APIs. So dtrack should keep its implementation.

nscuro commented 1 month ago

Closing for now, but still appreciate everyone's input. I think we can / should re-evaluate this when we start adding /v2 endpoints, where we don't have to worry about breaking changes.

github-actions[bot] commented 1 week ago

This thread has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.