Spring-boot: Rename 'details' to 'components' in health actuator JSON

[philwebb]

Currently we have "details" in the JSON that represents both details of a Health and components of CompositeHealth. I would like to rename the latter to components.

The catch is we need to do this in a back compatible way.

[spencergibb]

This change broke a test in spring-cloud-netflix looking for 'details'. Doesn't seem to be backward compatible. https://github.com/spring-cloud/spring-cloud-netflix/blob/40ec6066c1e82a447314ebe0b45ca34e9e7034ce/spring-cloud-netflix-hystrix/src/test/java/org/springframework/cloud/netflix/hystrix/HystrixOnlyTests.java#L86-L93

Changing "details" to "components" fixes it. I can point you to the jenkins build if you'd like.

[wilkinsona]

As far as I can tell, there's no Accept header being sent in the test so it's saying that it'll happily accept anything. If you specify application/vnd.spring-boot.actuator.v2+json you should get a response with details in it rather than components.

[spencergibb]

Ok. I think of backward-compatible as the user shouldn't have to make a change. This is opt-in to backward-compatibility. There should be something in a migration guide then.

[wilkinsona]

I'm not sure I agree with that. Your client was saying that it was happy to accept anything, but was actually only capable of consuming application/vnd.spring-boot.actuator.v2+json. With an appropriate accept header that expressed the client's capabilities, no change would have been necessary.

That said, there may be plenty of users that have clients that do not send an Accept header and can also only consume application/vnd.spring-boot.actuator.v2+json. IMO, this fits within Boot's goal of minor updates causing at most minor pain on upgrade. Let's see what the rest of the team thinks.

[spencergibb]

there may be plenty of users that have clients that do not send an Accept header and can also only consume application/vnd.spring-boot.actuator.v2+json.

This was what I was thinking as well.

[philwebb]

I wonder how many users will have tools that actually need to the extract content from the JSON? This is a change that I feel is a tricky one to make because it's quite hard to know if users will really be effected or not. My thinking was as follows:

• Most users are probably using only the HTTP status with tools that monitor health.
• If the health check fails they may need to inspect the JSON, but this is probably manual so the change won't hurt.
• If a user wants to check a specific endpoint, they can use /actuator/health/<indicator> and this will work as before.
• For general purpose tools like Spring Boot Admin, the content type header is a good way to deal with the change.

There should be something in a migration guide then.

Indeed, we've just not written the release notes yet.

@spencergibb Do you feel like many Spring Cloud users are going to find this change disruptive? How common do you think parsing the health JSON to extract specific details is?

[spencergibb]

I have no insight into how many users this might affect. I'm fine either way (making no Accept return v2 or note in migration guide). We just had a test break because of it and wanted to alert you as has been requested in the past.

[wilkinsona]

Sorry, @spencergibb. I should have thanked you earlier for letting us know about the potential problem. It's much appreciated as it's prompted us to give this some extra thought.

[spencergibb]

No worries. I appreciate the conversation

[philwebb]

Hey @spencergibb, we discussed this on our weekly call and we'd like to try leaving it as it is for RC1 to see if any users complain. We're hoping that digging into the JSON content isn't that common and most people will be OK with the change. If it ends up breaking lots of users we can consider reverting it before GA.