CODEWITHSUNDEEP
restapipostapi-design
kosh
kosh

Reputation: 561

Variable payloads in POST

This is more of a design question. Lets say that I have an endpoint to create a home. Each home has an address, and other characteristics. Let's focus on address for now.

Envisioning a legacy world where we can post to /home with a payload containing an address_id that is a reference to an external system with address validation, etc.

Now we would like to support the creation of the address (in the external system) to simplify the number of calls our clients need to make. A client would/could just call us to create a home, with the address value specified, as opposed 2 calls.

Enter a POST to /home with either an address_id specified, or an address_value string (but not both). This would make our server look inside the payload, decide if it needs to call the external address system on behalf of the client, depending on which field (address_id vs address_value) is presented in the POST payload.

Question: Variable behavior based on fields within a request, feels like an anti-pattern. It also feels like a tight coupling between a legacy field and a new field that we are trying to support.

The other alternative is that we introduce a new endpoint, which takes a new payload that only has the address value, and eventually deprecate the old endpoint with address_id.

Are there any other design alternatives?

Upvotes: 0

Views: 171

Answers (1)

VoiceOfUnreason
VoiceOfUnreason

Reputation: 57279

Variable behavior based on fields within a request, feels like an anti-pattern.

It is probably less of an anti pattern than it feels like.

Historically SOAP, and more recently GraphQL have very much been "POST a payload to a resource, and we'll figure it out on the other side".

HTTP is an application protocol whose application domain is the transfer of documents over a network. -- Jim Webber, 2011

REST constrains us to use a limited set of messages -- "five verbs and the truth" -- so there's bound to be some doubling up somewhere.

The reason that we expect POST to handle multiple kinds of messages, is that cache invalidation rules apply to the target resource. So we want to use targets that invalidate the correct representations that have been cached by the client.

So in HTML, we might have many different forms that all POST to a single resource, because the successful processing of those forms invalidates the cached representations of that resource.

Yes, this means on the server side, we may need to hand roll some of our own routing logic, when the framework we are using only supports routing based on request meta data.

Which isn't to argue that you can't choose to use finer grained resources -- that's OK too. But they "should" be resources that have their own representations, not simply RPC endpoints with a different spelling for each "responsibility".

Upvotes: 1

Related Questions