Hypermedia Links in POST response

[chrised]

Is your feature request related to a problem?

We would like to be able to return a status URI for asynchronous operations with a HTTP 202 response.
i.e.

POST /api/object

202: {
  "status_uri": "/api/object/{id}/status",
}

Describe the solution you'd like

Ideally we'd see something like an X-TERRAFORM-** flag on a response field which would be used to poll for the operation's success.

Acceptance criteria

A method by which we can return a pollable URI for object transitions.

Describe alternatives you've considered

At the moment we return the entire object with the 202 response, which is a valid workaround, though not as flexible as we'd like.

Checklist

Don't forget to go through the checklist to make sure the issue is created properly:

• I have added a corresponding label (feature request/bug/etc) to the issue (right side menu)
• I have added this issue to the 'API Terraform Provider' GitHub project (right side menu)

[dikhan]

Hi @chrised , thanks for raising this issue! Glad to see this request. Haven't put much thought into the actual design here, but preferably I'd like to keep the design compliant with HATEOAS/HAL spec so the response follows the standard.

Added to the prioritized backlog :)

[chrised]

Sure, we're pretty flexible, that sounds like the right way to go too!

[qrkourier]

In addition to asynchronous HTTP ACCEPTED (202) responses, the same approach would be useful for HTTP CREATED (201) responses, which indicate the POST operation was synchronously completed. Configuration alternatives could include a response HEADER or a parameter on the terraform.required_providers part of the TF plan or the plugin's config YAML to configure this plugin to recognize POST responses that include a compliant link to the created entity.

EDIT: more context: Presently, the plugin ignores asymmetrical responses that have fewer properties than the POST request. A flexible configuration proposed in this issue would allow for affirmative synchronous and asynchronous responses that have a hypermedia link to either the synchronously-created entity with all the same properties as the POST request, or a link to the asynchronous process that should be polled for status.