Schema-registry: Update docs on /config/<subject> to clarify behavior

[granders]

The docs on /config are fairly terse, and can lead to some confusion when there is no config override for a subject (e.g. https://github.com/confluentinc/schema-registry/issues/213):

if GET /config returns {"compatibility": "FULL"}, and there is no override for subject "my_cool_topic", it's reasonable to assume that GET /config/my_cool_topic might return FULL.

However this is not correct. In 1.0 this request returns 200 OK {"compatibilityLevel": null}, and in master branch it now returns 404 to signal that there is no subject-specific override for my_cool_topic

The docs should clarify the behavior in this particular case

[rajim17]

I was under assumption that if compatibility level is not set for a subject, it would use the global default compatibility level. If not, how does global compatibility level is used ?

[granders]

@rajim17 You are exactly right about the compatibility check.

When a schema is registered in a subject, the compatibility check is done using the "derived" compatibility level just like you described: if a subject-level compatibility override is not set , the global default for compatibility level is used.

My guess is that source of confusion here is that /config/<subject> actually fetches the subject-level override, and not the "derived" compatibility level for the subject. I think you are expecting /config/<subject> to be returning the derived compatibility level.

[rajim17]

Yes @granders . I would expect /config/<subject> to be returning the derived compatibility level. Do you think this is making sense.. ??

[lucapette]

I just ran into this as well. I did not expect the endpoint to return null and a 404 if the compatibility level is not set for the queried subject. It's also not true that "it's not found" as far as I understand because subjects get the globally set compatibility mode. I agree with @rajim17 about what the expected behavior should be. Another argument there is that you can't really say from the response if the subject isn't there or if it has the default mode (which makes calling this endpoint hard... as 404 means two things here)

I'd be happy to contribute to the change of behavior (even though I'd personally consider it a bug fix... but that's semantics) if the change itself is welcome.

[mageshn]

@lucapette do you have a proposal on how you want to fix this? We certainly welcome contributions and I can help you through it.

[lucapette]

@mageshn My proposal would be:

• return 404
• return global config if it's not set
• return subject config if set

which is what @rajim17 suggested after all. If that's fine with you, I'll try to set some time aside next week and get a draft pull request going (I'm not the most fluent in Java, so I need some time to look around :))

[AlexNavara]

Hello, @mageshn !
I've made a fix for this topic. Could I ask someone to review it?

Update: I've looked through the failed tests for my PR, and now got even more confused. It seems like compatibility level can be set even for subject that doesn't exist. Is this behavior expected? It makes sense to me, just want to clarify.
Also, if this is expected, then I believe that endpoint "DELETE /config/not_existing_subject" should delete the custom config if set ( now it returns 404 ), or there should be another way to remove compatibility level of not-existing subject.

[junzebao]

any updates regarding merging the PR? the doc is really confusing.

[rayokota]

A ?defaultToGlobal query param was added.