Seeking guidance on REST API Signature for an API.
To handle logistics, we want to support shipping label generation for courier packages.

Which of these would be a more RESTFul way to model these APIs.

Generate Label API : POST /package/{package-id}/label.
Regenerate Label API : POST /package/{package-id}/label/regenerate.

vs

Generate Label API : POST /package/{package-id}/label?operation=generate.
Regenerate Label API : POST /package/{package-id}/label?operation=regenerate.

Regenerate API ends up creating a new Label for the package, based on updated shipping dates, etc passed as part of request payload.

CodePudding user response：

Just use:

POST /package/{package-id}/label
PUT/PATCH /package/{package-id}/label

https://restfulapi.net/http-methods/

CodePudding user response：

If the /package/{package-id}/label is a 'label resource' that you're creating, then the appropriate method is probably PUT here.

But 'regenerating' is a bit hard to explain here. Could you just fetch the label over and over again by doing a GET request on /package/{package-id}/label.

If 'creating a label' or 'regenerating a label' doesn't have side-effects (such as a physical printer printing a label), then a GET might work best.

If 'creating a label' or 'regenerating a label' is not really returning a label but causing some external effect in a different system, then it feels better for this to be more like the RPC call you mentioned.

POST /package/{package-id}/label

Then my question is, why is there a difference between 'generating' and 'regenerating'. It sounds like you're just doing the same thing twice. Do you really need 2 endpoints? Can't the system figure out if a label was created before for the {package-id}?

If the system doesn't know the label is generated vs regenerated, and only the client can know I would be inclined to use the same endpoint and add some flag to the request body instead of having 2 different URLS.