no response from post to /identity/entity/id/:id

[jmls]

Describe the bug
The api documentation (https://www.vaultproject.io/api/secret/identity/entity.html) states that a post to /identity/entity/id/:id has a response similar to

{
  "data": {
    "id": "8d6a45e5-572f-8f13-d226-cd0d1ec57297",
    "aliases": null
  }
}

The actual response is null

To Reproduce
Steps to reproduce the behavior:

1. curl http://localhost:8200/v1/identity/entity/id/
2. no response

Expected behavior
the response suggested by the documentation

Environment:

• Vault Server Version : 1.1.1
• Vault CLI Version: Vault v1.1.1 ('a3dcd63451cf6da1d04928b601bbe9748d53842e')

[jefferai]

Can you show output with the exact curl command with -vv as well?

[jmls]

sure. I've put in "read" statements as well to show that the data has changed ;)

/ # cat update.json
{
    "metadata": {
        "organization": "MYORG",
        "team": "MYTEAM"
    }
}
/ # 
/ # vault read identity/entity/id/08d17e14-be6f-4b77-2ef9-dd5f8dac9faf
Key                    Value
---                    -----
aliases                []
creation_time          2019-06-08T08:57:42.649653849Z
direct_group_ids       []
disabled               false
group_ids              []
id                     08d17e14-be6f-4b77-2ef9-dd5f8dac9faf
inherited_group_ids    []
last_update_time       2019-06-10T16:32:03.879409152Z
merged_entity_ids      <nil>
metadata               map[organization:hashi team:nomad]
name                   jmls22
policies               <nil>

/ # curl -vv -H "Content-Type: application/json" -H "x-vault-token: [token]" -d @update.json http://localhost:8200/v1/id
entity/entity/id/08d17e14-be6f-4b77-2ef9-dd5f8dac9faf
*   Trying 127.0.0.1...
* TCP_NODELAY set
* Connected to localhost (127.0.0.1) port 8200 (#0)
> POST /v1/identity/entity/id/08d17e14-be6f-4b77-2ef9-dd5f8dac9faf HTTP/1.1
> Host: localhost:8200
> User-Agent: curl/7.61.1
> Accept: */*
> Content-Type: application/json
> x-vault-token: s.aLZo8KsHzJhaHs13uKpalBrE
> Content-Length: 64
> 
* upload completely sent off: 64 out of 64 bytes
< HTTP/1.1 204 No Content
< Cache-Control: no-store
< Content-Type: application/json
< Date: Mon, 10 Jun 2019 16:33:39 GMT
< 
* Connection #0 to host localhost left intact
/ # vault read identity/entity/id/08d17e14-be6f-4b77-2ef9-dd5f8dac9faf
Key                    Value
---                    -----
aliases                []
creation_time          2019-06-08T08:57:42.649653849Z
direct_group_ids       []
disabled               false
group_ids              []
id                     08d17e14-be6f-4b77-2ef9-dd5f8dac9faf
inherited_group_ids    []
last_update_time       2019-06-10T16:33:39.083126972Z
merged_entity_ids      <nil>
metadata               map[team:MYTEAM organization:MYORG]
name                   jmls22
policies               <nil>****

so as you can see, the metadata has been changed, but no output

[jefferai]

What version of Vault? I believe this changed recently and the docs reflect the latest released version.

[jmls]

I mentioned in the initial description

Vault Server Version : 1.1.1
Vault CLI Version: Vault v1.1.1 ('a3dcd63451cf6da1d04928b601bbe9748d53842e')

[jmls]

yeah, I see that 1.1.3 is available. Will check that out.

Perhaps the docs could / should say what version of vault they apply to.

[mdgreenfield]

This looks to be the same issue I'm seeing (server version 1.2.3) with updating an entity using the identity/entity/name/:name endpoint. The documentation shows a response body being returned with create/update but it appears that it is only returned on creation of new entities.

A create/POST returns a 200 while an update/POST returns a 204 "No Content". Both identity/entity/name/:name and identity/entity/id/:id share the same logic which explicitly was written to return a 204 -

vault/vault/identity_store_entities.go

Lines 259 to 262 in 98b35d3

	// If this operation was an update to an existing entity, return 204
	if !newEntity {
	return nil, nil
	}

The original PR (#5355) shows documentation with status 200 being returned (status codes have since been removed from the documentation).

[drawks]

This ambiguous return behavior is present in a number of places where there is a POST endpoint that can either create or update. The result of the operation will either 204 and return empty if an update operation is being done against and existing object OR a 200 and a partial object representation will be returned.

This is really a maddening behavior as any clients working with these API objects (Entity, Alias, certificate auth roles, perhaps others) requires 2 API calls in order to conduct and update and then retrieve the complete updated object. The additional calls add complexity and latency to interactions with vault AND quickly breaks when you start dealing with tokens designed for a specific and limited number of uses.

It would be much better if the response on an update was a 200 and the entire object representation was returned and a 201 on a create and likewise the entire object representation was returned. This behavior would be consistent both with expectations and the relevant HTTP protocol standards.

[drawks]

Another issue open over a year, with no indication that any action will be taken. Pretty difficult to sell people internally on the value of hashicorp's enterprise solutions when issues like this just lay dormant forever.

[priyaaank]

Hello, I'd like to pick this issue and work on it. Before I go ahead with the implementation I would like to discuss the path that the change should take. Is the expectation only to update the status code? Or would it make sense to have the entire object representation be returned as pointed out by @drawks in both create and update scenarios and reflect so in the documentation as well?

[ncabatoff]

Hi @priyaaank,

Sorry, we made a mistake in tagging this as a good-first-issue. In fact, I think we're just going to update the docs to describe the current behaviour in more detail (namely, that updates yield an empty 204.)

@drawks: You make some good points, namely (1) it would be nice to return 201 for creations, and (2) it would be convenient for clients if we could save them a roundtrip by returning the resource on create/update. Unfortunately, both of these changes would make this API inconsistent with the rest of Vault. A wholesale change is possible in a v2 of the API, but we don't have any immediate plans of that nature.