Samza REST can expose any JAX-RS Resource. By default, it ships with a JobsResource which is discussed below. You can implement your own Resources and specify them in the config.
Samza REST uses the Jersey implementation of the JAX-RS specification. The Jersey documentation and examples are helpful for creating a new Resource.
In addition, Samza REST imposes the following conventions, which should be followed for all Resources.
By convention, all resources prefix their path with a version number to enable supporting legacy APIs in the future. For example, the base URL for the JobsResource is
/v1/jobs
If a future version of JobsResource implements a different API, it will use a different version number in the base path.
/v2/jobs
All resources should be exposed on the latest version so clients can use a common version base for all requests.
Every error response will include a JSON message body containing a single message
field describing the problem. For example:
{ "message": "Unrecognized status: null" }
There are a few extra steps for Resources that require configuration values.
Resources are added to the Samza REST Service via config. There are two ways to add a new Resource depending on whether the Resource requires properties from the config file or not. In the former case, the Resource is instantiated once with the config and the instance is registered with the SamzaRestApplication. In the latter case, the Resource class is registered and it can be instantiated many times over the lifecycle of the application.
rest.resource.factory.classes
property in the service config.rest.resource.classes
property in the service config.For more information on these config properties, see the config table in the Overview page.