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()); } } }