Content Types
The REST Proxy uses content types for both requests and responses to indicate these data properties:
Serialization format: json
API version (e.g. v2
or v3
)
Embedded formats: json
, binary
, avro
, protobuf
and jsonschema
Important
The jsonschema
and protobuf
embedded types are supported beginning with
REST Proxy v2.
REST Proxy supports the Avro®, JSON Schema,
and Protobuf serialization formats. The versions
of the REST Proxy API are v2
and v3
.
The embedded format is the format of data you are producing or consuming. These formats
are embedded into requests or responses in the serialization format. For
example, you can provide binary
data in a json
-serialized request; in
this case the data should be provided as a base64-encoded string.
- For
v2
, the content type will be application/vnd.kafka.binary.v2+json
.
- For
v3
the content type will be application/json
.
If your data is JSON, you can use json
as the embedded format and embed it directly:
- For
v2
, the content type will be application/vnd.kafka.json.v2+json
.
- For
v3
the content type will be application/json
.
With avro
, protobuf
, and jsonschema
embedded
types, you can directly embed JSON formatted data along with a schema (or schema ID) in the request.
These types use Schema Registry, and the ID of the schema is serialized in addition to the data and payload.
- The Avro content type is
application/vnd.kafka.avro.v2+json
.
- The Protobuf content type is
application/vnd.kafka.protobuf.v2+json
.
- The JSON schema content type is
application/vnd.kafka.jsonschema.v2+json
.
The format for the content type is:
application/vnd.kafka[.embedded_format].[api_version]+[serialization_format]
For more information, see Schema Registry API Reference.
The embedded format can be omitted when there are no embedded messages
(i.e. for metadata requests you can use application/vnd.kafka.v2+json
).
The preferred content type for v2
is application/vnd.kafka.[embedded_format].v2+json
.
However, other less specific content types are permitted, including application/vnd.kafka+json
to indicate no specific API version requirement (the most recent stable version
will be used), application/json
, and application/octet-stream
. The
latter two are only supported for compatibility and ease of use. In all cases,
if the embedded format is omitted, binary
is assumed. Although using these
less specific values is permitted, to remain compatible with future versions you
should specify preferred content types in requests and check the content types
of responses.
Your requests should specify the most specific format and version information
possible via the HTTP Accept
header
For v2
, you can specify format and version as follows:
Accept: application/vnd.kafka.v2+json
For v3
, do not specify the version. The latest version (v3
) will be used:
The server also supports content negotiation, so you may include multiple,
weighted preferences:
Accept: application/vnd.kafka.v2+json; q=0.9, application/json; q=0.5
This can be useful when, for example, a new version of the API is preferred but
you cannot be certain it is available yet.
Errors
All API endpoints use a standard error message format for any requests that
return an HTTP status indicating an error (any 400 or 500 statuses). For
example, a request entity that omits a required field may generate the
following response:
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/vnd.kafka.v3+json
{
"error_code": 422,
"message": "records may not be empty"
}
Although it is good practice to check the status code, you may safely parse the
response of any non-DELETE API calls and check for the presence of an
error_code
field to detect errors.
Some error codes are used frequently across the entire API and you will probably want to have
general purpose code to handle these, whereas most other error codes will need to be handled on a
per-request basis.
-
ANY
/
Status Codes: |
- 401 Unauthorized –
- Error code 40101 – Kafka Authentication Error.
- 403 Forbidden –
- Error code 40301 – Kafka Authorization Error.
- 404 Not Found –
- Error code 40401 – Topic not found.
- Error code 40402 – Partition not found.
- 422 Unprocessable Entity – The request payload is either improperly formatted or contains semantic errors
- 500 Internal Server Error –
- Error code 50001 – Zookeeper error.
- Error code 50002 – Kafka error.
- Error code 50003 – Retriable Kafka error. Although the operation failed, it’s
possible that retrying the request will be successful.
- Error code 50101 – Only SSL endpoints were found for the specified broker, but
SSL is not supported for the invoked API yet.
|