Update API

[granders]

Update API to reflect today's discussion. We decided that HTTP POST method is legitimately used to make queries when data in the message body is required. The argument against using GET was that passing message body data is uncommon and may not be supported in some http libraries.

Change compatibility check:

• Add support for POST /compatibility/subjects//versions/
  schema string in message body is tested against schema in /
  return true, or false with incompatibility metadata produced by Avro
  this includes adding support for == 'latest'
• Remove dry_run support

Add ability to check whether a schema is registered under a topic:

• POST /subjects/
  schema string in message body
  return ?

Change /schemas/ to /schemas/ids/

We also concluded that POST to a collections resource should canonically be considered a create request, but that POST used elsewhere can be more flexible. E.g. POST /subjects//versions creates a version under the collection of versions.

[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