The Zephr Java SDK is available either as a JAR or as a Maven dependency using the Kuali S3 wagon. In either case, contact support@zephr.com to arrange for access.
Client-side SDK
The client-side SDK requires you to create an instance of the PublicApiClient, providing the tenantId.
PublicApiClient client = PublicApiClient.build(tenant);
Optionally, Zephr environment can be provided, too:
PublicApiClient client = PublicApiClient.build(tenant, Environment.STAGING);
It is possible to specify a base URL for the Zephr service, if it is non-standard (not normally needed):
PublicApiClient client =
PublicApiClient.build(tenant).overrideBaseUrl("http://localhost:8080");
For client-side implementations the SDK supports the following functions:
Register:
package io.blaize.sdk.examples;
import io.blaize.api.model.identity.CoreUserDetails.IdentifierType;
import io.blaize.api.model.identity.CoreUserDetails.ValidatorType;
import io.blaize.sdk.PublicApiClient;
import io.blaize.sdk.exception.WrongHttpResponseException;
import io.blaize.sdk.httpclient.AbstractClient; import org.apache.http.HttpStatus;
import java.util.HashMap;
import java.util.Map;
import java.util.concurrent.CompletableFuture;
public class SdkUserRegistration {
private static final String tenant = "mysite";
public static void main(String[] args) {
PublicApiClient client = PublicApiClient.build(tenant,
AbstractClient.Environment.STAGING);
Map<string, object=""> attributes = getAttributesFromRegistrationForm();
CompletableFuture <String> sessionId =
client.register(IdentifierType.EMAIL_ADDRESS, "helen@blaize.io",
ValidatorType.PASSWORD, "sup3r_s3cr3t", attributes);
sessionId
.thenAccept(System.out::println)
.exceptionally(e -> {
if (WrongHttpResponseException.class.isInstance(e.getCause())) {
final int actualResponseStatus = ((WrongHttpResponseException)
e.getCause()).getActualResponseStatus();
if (actualResponseStatus == HttpStatus.SC_CONFLICT) {
System.out.println("A user with that email address already exists... try resetting your password");
} else if (actualResponseStatus == HttpStatus.SC_PAYMENT_REQUIRED)
{
System.out.println("The email address you have supplied is not allowed for registration");
} else if (actualResponseStatus == HttpStatus.SC_BAD_REQUEST)
{ System.out.println("One of more of the mandatory fields were not provided or are incorrect");
}
} else {
System.out.println(e.getLocalizedMessage());
} return null;
});
}
private static Map<string, object=""> getAttributesFromRegistrationForm() {
Map<string, object=""> attributes = new HashMap<>();
attributes.put("first-name", "Helen");
attributes.put("age", 30);
return attributes;
}
}
Login:
package io.blaize.sdk.examples;
import io.blaize.api.model.identity.CoreUserDetails;
import io.blaize.sdk.PublicApiClient;
import io.blaize.sdk.exception.WrongHttpResponseException;
import io.blaize.sdk.httpclient.AbstractClient;
import org.apache.http.HttpStatus;
import java.util.concurrent.CompletableFuture;
public class SdkUserLogin {
private static final String tenant = "mysite";
public static void main(String[] args) {
PublicApiClient client = PublicApiClient.build(tenant, AbstractClient.Environment.STAGING);
CompletableFuture sessionId =
client.login(CoreUserDetails.IdentifierType.EMAIL_ADDRESS, "helen@blaize.io",
CoreUserDetails.ValidatorType.PASSWORD, "sup3r_s3cr3t");
sessionId
.thenAccept(System.out::println)
.exceptionally(e -> {
if (WrongHttpResponseException.class.isInstance(e.getCause()))
{ final int actualResponseStatus = ((WrongHttpResponseException) e.getCause()).getActualResponseStatus();
if (actualResponseStatus == HttpStatus.SC_NOT_FOUND) {
System.out.println("Your email address is not registered");
} else if (actualResponseStatus == HttpStatus.SC_UNAUTHORIZED) {
System.out.println("You have provided an incorrect password");
}
} else {
System.out.println(e.getLocalizedMessage());
}
return null;
});
}
}
Logout:
package io.blaize.sdk.examples;0
import io.blaize.sdk.PublicApiClient;
import io.blaize.sdk.httpclient.AbstractClient;
import java.util.concurrent.CompletableFuture;
public class SdkUserLogout {
private static final String tenant = "mysite";
public static void main(String[] args) {
PublicApiClient client = PublicApiClient.build(tenant, AbstractClient.Environment.STAGING);
CompletableFuture logOutComplete = client.logout(getSessionId());
}
}
Forget me:
package io.blaize.sdk.examples;
import io.blaize.sdk.PublicApiClient;
import io.blaize.sdk.httpclient.AbstractClient;
import java.util.concurrent.CompletableFuture;
public class SdkUserForgetMe {
private static final String tenant = "mysite";
public static void main(String[] args) {
PublicApiClient client = PublicApiClient.build(tenant, AbstractClient.Environment.STAGING);
CompletableFuture forgotten = client.forgetMe(getSessionId());
}
}
Entitlement challenge:
package io.blaize.sdk.examples;
import io.blaize.sdk.PublicApiClient;
import io.blaize.sdk.httpclient.AbstractClient;
import java.util.Collection;
import java.util.HashSet;
import java.util.Map;
import java.util.concurrent.CompletableFuture;
public class SdkEntitlementChallenge {
private static final String tenant = "mysite";
private static final String articleEntitlementId = "11664be6-9355-4537-b56f-d8ea0d218c6f";
private static final String videoEntitlementId = "13a120aa-8c4b-4faf-8942-8f3447a47774";
public static void main(String[] args) {
PublicApiClient client = PublicApiClient.build(tenant, AbstractClient.Environment.STAGING);
Collection challenge = new HashSet<>();
challenge.add(articleEntitlementId);
challenge.add(videoEntitlementId);
CompletableFuture<map<string, boolean>> results = client.entitlementChallenge(getSessionId(), challenge);
results.thenAccept(permissionsMap -> {
if (!permissionsMap.get(articleEntitlementId)) {
System.out.println("You cannot view articles");
}
if (!permissionsMap.get(videoEntitlementId)) { System.out.println("You cannot view videos");
}
});
}
}
Request-rule decision:
package io.blaize.sdk.examples;
import io.blaize.api.model.access.HttpResponse;
import io.blaize.sdk.PublicApiClient;
import io.blaize.sdk.httpclient.AbstractClient;
import java.util.HashMap;
import java.util.Map;
import java.util.concurrent.CompletableFuture;
public class SdkRequestRuleDecision {
private static final String tenant = "mysite";
public static void main(String[] args) {
PublicApiClient client = PublicApiClient.build(tenant, AbstractClient.Environment.STAGING);
String requestPath = "/some/content";
String requestMethod = "GET";
Map<String, String> requestHeaders = new HashMap<>();
requestHeaders.put("Referrer", "https://www.facebook.com");
CompletableFuture result =
client.accessDecision(getSessionId(), requestPath, requestMethod, requestHeaders);
result.thenAccept(decision -> {
System.out.println(decision.getStatus());
System.out.println(decision.getBody());
});
}
}
Get profile:
package io.blaize.sdk.examples;
import io.blaize.sdk.PublicApiClient;
import io.blaize.sdk.httpclient.AbstractClient;
import java.util.Map;
import java.util.concurrent.CompletableFuture;
public class SdkGetUserProfile {
private static final String tenant = "mysite";
public static void main(String[] args) {
PublicApiClient client = PublicApiClient.build(tenant, AbstractClient.Environment.STAGING);
CompletableFuture<map<string, object="">> result = client.getUserProfile(getSessionId());
}
}
Update profile:
package io.blaize.sdk.examples;
import io.blaize.sdk.PublicApiClient;
import java.util.HashMap;
import java.util.Map;
import java.util.concurrent.CompletableFuture;
public class SdkUpdateUserProfile {
private static final String tenant = "mysite";
public static void main(String[] args) {
PublicApiClient client = PublicApiClient.build(tenant);
Map<string, object=""> profile = new HashMap<>();
profile.put("favourite-color", "Red");
boolean merge = true; // if false, the new profile will completely replace the entire old profile, if true only provided fields will be replaced
CompletableFuture updated =
client.updateUserProfile(getSessionId(), profile, merge);
}
}
Get extended profile document:
package io.blaize.sdk.examples;
import io.blaize.sdk.PublicApiClient;
import io.blaize.sdk.httpclient.AbstractClient;
import java.util.concurrent.CompletableFuture;
public class SdkGetUserExtendedProfile {
private static final String tenant = "mysite";
public static void main(String[] args) {
PublicApiClient client = PublicApiClient.build(tenant, AbstractClient.Environment.STAGING);
CompletableFuture result = client.getUserExtendedProfile(getSessionId(), "reading-history");
}
}
Update extended profile document:
package io.blaize.sdk.examples;
import io.blaize.sdk.PublicApiClient;
import io.blaize.sdk.httpclient.AbstractClient;
import java.util.concurrent.CompletableFuture;
public class SdkUpdateUserExtendedProfile {
private static final String tenant = "mysite";
public static void main(String[] args) {
PublicApiClient client = PublicApiClient.build(tenant,
AbstractClient.Environment.STAGING);
String profileDocument = "{\"recent\": [\"1.html\", \"2.html\"]}";
CompletableFuture updated =
client.writeUserExtendedProfile(getSessionId(), "reading-history", profileDocument);
}
}
Server-side SDK:
The server-side SDK is essentially a REST client which performs HMAC request signing for the API. This SDK requires the implementor to specify the host, path, method, body, headers and query parameters for a request and returns the response as a JSON object or plain text.
In order to make requests to the Admin API you will need to first create a keypair, which you can do in the Zephr Admin Console.
You can also use the server-side SDK to sign request for use with a different HTTP client.
Example REST request
package io.blaize.sdk.examples;
import io.blaize.api.model.identity.UserModel;
import io.blaize.api.model.rest.RestCollectionResponse;
import io.blaize.sdk.AdminApiClient;
import io.blaize.sdk.exception.WrongHttpResponseException;
import io.blaize.sdk.httpclient.AbstractClient;
import org.apache.http.HttpResponse;
import java.util.concurrent.CompletableFuture;
public class SdkAdminApiRequest {
private static final String tenant = "mysite";
private static final String accessKey = getAccessKeySecurely();
private static final String secretKey = getSecretKeySecurely();
public static void main(String[] args) {
AdminApiClient client = AdminApiClient.build(tenant,
AbstractClient.Environment.STAGING, accessKey, secretKey);
CompletableFuture<restcollectionresponse> manyResults = client.getCollection(UserModel.class, "/v3/users", 200);
String userId =
manyResults.join().getResults().iterator().next().getUserId();
CompletableFuture singleResult =
client.getEntity(UserModel.class, "/v3/users/" + userId, 200);
CompletableFuture httpResponseData =
client.get("/v3/users", 200); CompletableFuture badResponse = client.get("/nothing-here", 200);
badResponse.exceptionally(e -> {
if (WrongHttpResponseException.class.isInstance(e.getCause())) {
WrongHttpResponseException wrongHttpResponseException =
(WrongHttpResponseException) e.getCause();
System.out.println("Error from Blaize :" +
wrongHttpResponseException.getActualResponseStatus() + " : " +
wrongHttpResponseException.getMessage());
} else {
System.out.println(e.getLocalizedMessage());
}
return null;
});
}
}
Example request using a 3 party HTTP client
package io.blaize.sdk.examples;
import io.blaize.api.exception.HmacException;
import io.blaize.api.utilities.security.HmacSigner;
import java.util.Date; import java.util.HashMap;
import java.util.Map; import java.util.UUID;
public class SdkAdminApiRequestWith3PartyClient {
private static final String tenant = "mysite";
private static final String accessKey = getAccessKeySecurely();
private static final String secretKey = getSecretKeySecurely();
public static void main(String[] args) {
String body = ""; // This needs to be bytewise identical to the payload, whitespace included
String path = "/v3/users";
String method = "GET";
String timestamp = new Long(new Date().getTime()).toString();
String nonce = UUID.randomUUID().toString();
String signature = null;
try {
signature = new HmacSigner("SHA-256").signRequest(secretKey, body, path, method, timestamp, nonce);
String authorizationHeader = "BLAIZE-HMAC-SHA256 " + accessKey + ":" + timestamp + ":" + nonce + ":" + signature;
Map<string, string> headers = new HashMap<>();
headers.put("Authorization", authorizationHeader);
client.httpGet("https://" + tenant + ".admin.blaize.io" + path, headers);
} catch (HmacException e) {
System.err.println(e.getLocalizedMessage());
}
}
}