Technical Documentation

Java SDK

36 views 0

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

    } 

}