Java client for the Zulip REST API
APACHE-2.0 License
image:https://github.com/jamesnetherton/zulip-java-client/workflows/Zulip%20Java%20Client%20CI/badge.svg[title="Zulip Java Client CI", link="https://github.com/jamesnetherton/zulip-java-client/actions?query=workflow%3A%22Zulip+Java+Client+CI%22+branch%3Amaster"] image:https://img.shields.io/:license-Apache2-blue.svg[title="License", link="http://www.apache.org/licenses/LICENSE-2.0"] image:https://img.shields.io/maven-central/v/com.github.jamesnetherton/zulip-java-client.svg?maxAge=600[title="Maven Central", link="http://search.maven.org/#search%7Cga%7C1%7Cg%3Acom.github.jamesnetherton%20a%3Azulip-java-client"] image:https://img.shields.io/endpoint?url=https%3A%2F%2Fjamesnetherton.github.io%2Fzulip-java-client%2Fversion.json[title="JavaDoc", link="https://jamesnetherton.github.io/zulip-java-client/0.7.1/index.html"]
= Zulip Java Client
Java client for the https://zulip.com[Zulip] chat server https://zulip.com/api/rest[REST API].
Refer to the https://github.com/jamesnetherton/zulip-java-client/blob/master/COMPATIBILITY.adoc[compatibility matrix] to see which version of the Zulip server this library is compatible with.
== Quick start
Here's how to get started with the Zulip Java client and starting making API requests.
=== Dependencies
Add the zulip-java-client
dependency to your project.
==== Maven
==== Gradle
=== Instantiate the Zulip client
Zulip
instance by passing the user email address, https://zulip.com/api/api-keys[API key] and the base URL of the Zulip server.Now you can start interacting with the Zulip APIs.
When you are finished, it's good practice to close the Zulip client.
== Advanced configuration
There are a few ways of customising the Zulip client configuration if you need to configure a proxy server or disable SSL certificate validation.
=== Zuliprc file
There is the option to use a zuliprc
file as the configuration source.
ZulipConfiguration
directly.== API Request Builders
Each API has a request builder object which is used to set the various parameter values expected by the API endpoint.
Mandatory values will always be part of the API request method signature, while optional values can be provided through the 'with' builder methods.
Here's an example of this with the edit message API.
<1> The zulip client object exposes methods which aggregate the REST APIs together under logical groups such as messages, streams & users. The editMessage
API expects one mandatory parameter - the message id.
<2> Then follows a number of optional API parameters.
<3> The request builder is completed and sent to the Zulip server with the execute()
method. This MUST be called in order for the request to be sent.
== Exception handling
Zulip API error responses are thrown as ZulipClientException
. The exception object contains details about the error such as the code and a descriptive message.
If you exceed the API request rate limit, then the exception cause will be set to ZulipRateLimitExceeded
. It contains a method which enables you to get the time at which the rate limit is reset. Note that the value is a https://en.wikipedia.org/wiki/Unix_time[Unix epoch] value.
== Real time events API
There is some limited and experimental support for the Zulip https://zulip.com/api/real-time-events[real-time events API].
At present it is only possible to consume events whenever new messages are posted.
To consume messages posted to all streams.
EventPoller eventPoller = zulip.events().captureMessageEvents(new MessageEventListener() { @Override public void onEvent(Message event) { System.out.println(event.getContent()); } });
eventPoller.start();
// Do useful app work
To filter messages you may use one or more https://zulip.com/api/construct-narrow[narrow] expressions.
EventPoller eventPoller = zulip.events().captureMessageEvents(new MessageEventListener() { @Override public void onEvent(Message event) { System.out.println(event.getContent()); } }, Narrow.of("stream", "my-stream-name"));
eventPoller.start();
// Do useful app work