Update API about schema-registry

[nehanarkhede]

As per our discussion today, assigning this to you @junrao

[junrao]

To support Hadoop ETL, we need to add the following api to get the version from a schema string.

POST /subjects/<subject>

body is the schema string; return the version if the schema exists; otherwise 404 status.

However, it does feel weird that on the following similar api, we return the id and not the version.
POST /subjects/<subject>/versions

[nehanarkhede]

I found an issue with the compatibility API while updating the docs. Maybe we should check in the docs so they get updated as part of the same patch.

POST /compatibility/subjects/{subject}/versions/{version}

The compatibility API takes in a subject and version. And we discussed about supporting a special "latest" version to make it convenient to check compatibility against the latest version of the schema. However, this API now accepts version as a string, which is weird and inconsistent with all other APIs. I think supporting a special latest version indicator is useful, though it should be an integer.

There are 2 choices

1. -1
2. Int.MAX_VALUE.

Option 2 is intuitive but annoying to use. Option 1 is easy to use but a little confusing to reason about "latest" with a negative value.

@granders @junrao @ewencp Thoughts?

[granders]

Users have to encode the whole url as a string anyway, so it doesn't seem totally crazy to have "latest" as an option.

If we do go with an integer, Won't Int.MAX_VALUE vary between languages? -1 seems better defined, though slightly weird. If we wanted to have some logical approach behind negative indices, they could be interpreted like they are in python lists (if i < 0 arr[i] gives arr[len(arr) + i])

[nehanarkhede]

@granders
Since version is an int, it seems odd that we describe it to be a string. Also, all other APIs that deal with either schema id and version still expect integers, except this particular one.

If we do go with an integer, Won't Int.MAX_VALUE vary between languages?

Sorry, should've been more specific. I just meant the highest possible value for an unsigned int (2^31 - 1), not necessarily Java's definition of it. But this number is just cumbersome to express is what I thought. So suggested -1 similar to the latest offset definition in kafka