Apps Script library for Ephemeral exchange

Deprecated

NOTE – as of 20 Nov 2017, Ephemeral exchange is migrating to a Firestore/ Firebase cloud function back end. See Migrating from App Engine to Cloud function

The REST API interface is pretty straightforward, so you can recreate this with UrlFetch if you like. However this packages all the things you can do from the client in a simple library, and is has same call formats as the JavaScript version.

Page Content hide

Where to get it

You can include the library in your project – the key is

19rhki6VDTWk4v1RDb6u1d5E-nNaQq8sXCnRnFzUpp4V4lmZ9Z6R_PP9n

or get a copy here from Github.

Code

Most of the demos and libraries mentioned in these pages are available in their own GitHub repo, but for convenience, there is a consolidated repo where I’ll push all the associated code. If you’d like to contribute, please make a PR there.

Demo

Before starting

You’ll need to get a boss key. If you want to play with the tests below (or on github). You can get a boss key by visiting the API home, registering, and creating one in the Console. I also recommend you take a look at the tutorial there to get a feel for some of the concepts.

Examples

This is a series of tests that exercise the common functions available in the library. Check the log file for which Urls the requests are turned into.

function testEfx() {
  
  // set up client 
  var efx = EffexApiClient.setProd().setVerbose(true);
  
  // boss key comes from console /// replace this with your own
  var bossKey ="bx-----------------";  
  
  // check service is up
  var result = efx.ping();
  assure ( result && result.ok ,"ping", result);
  
  // give up if its not
  if (!result.ok) {
    throw 'service is not up:' + JSON.stringify(result);
  }
  
  // get some service info
  var result = efx.info();
  assure ( result && result.ok ,"info", result);
  
  // check boss key hasnt expired
  var result = efx.validateKey(bossKey);
  assure ( result && result.ok ,"validate bosskey", result);
  
  // get 1 writer key expiringin in 5 minutes
  var writers = efx.generateKey (bossKey,"writer", {seconds:5*60});
  assure ( writers && writers.ok && writers.keys.length === 1 ,"writerkeys", writers);
  
  // get 2 readr keys  expiringin in 5 minutes
  var readers = efx.generateKey (bossKey,"reader", {seconds:5*60, count:2});
  assure ( readers && readers.ok && readers.keys.length === 2 ,"readerkeys", readers);
  
  // get 1 updater keys  expiringin in 5 minutes
  var updaters = efx.generateKey (bossKey,"updater", {seconds:5*60});
  assure ( updaters && updaters.ok && updaters.keys.length === 1 ,"updaterkeys", updaters);
  
  // set the keys up as default so we dont have to bother specifying them later
  efx.setKeys ({
    updater:updaters.keys[0],
    writer:writers.keys[0],
    reader:readers.keys[0]
  });
  // more convenient for later
  var keys = efx.getKeys();
  
  //---reading and writing
  var someData = {name:'xyz',a:[1,2,3],b:2000};
  
  var data = efx.write(someData);
  assure ( data && data.ok ,"write-post", data);
  
  // read it back with the same key
  var result = efx.read( data.id, keys.writer);
  assure ( result && result.ok && JSON.stringify(result.value) === JSON.stringify(someData) ,"read", result);
  
  // do it again, but use a GET for writing
  var data = efx.write(someData, keys.writer, "get");
  assure ( data && data.ok ,"write-get", data);
  
  // read it back with the same key
  var result = efx.read( data.id, keys.writer);
  assure ( result && result.ok && JSON.stringify(result.value) === JSON.stringify(someData) ,"read-get", result);
 
  // now do all that with some text data
  var textData = "some text data";
  
  var data = efx.write(textData);
  assure ( data && data.ok ,"write-post-text", data);
  
  // read it back with the same key
  var result = efx.read( data.id, keys.writer);
  assure ( result && result.ok && result.value === textData ,"read-text", result);
  
  // do it again, but use a GET for writing
  var data = efx.write(textData, keys.writer, "get");
  assure ( data && data.ok ,"write-get-text", data);
  
  // read it back with the same key
  var result = efx.read( data.id, keys.writer);
  assure ( result && result.ok && result.value === textData ,"read-get-text", result);
  
  //-- assigning readers and updaters
  var data = efx.write(someData,keys.writer,"post",{readers:keys.reader,updaters:keys.updater});
  assure ( data && data.ok ,"write-for-others", data);
  
  // read it back with a reader key
  var result = efx.read( data.id);
  assure ( result && result.ok && JSON.stringify(result.value) === JSON.stringify(someData) ,"read-reader", result);
  
  
  // read it back with an updater key
  var result = efx.read( data.id, keys.updater);
  assure ( result && result.ok && JSON.stringify(result.value) === JSON.stringify(someData) ,"read-updater", result);
  
  // update it
  var result = efx.update (textData , data.id);
  assure ( result && result.ok ,"update", result);
  
  // check it took - i'll just use the reader key
  var result = efx.read( data.id);
  assure ( result && result.ok && result.value === textData ,"read-updated", result);
  
  //----work with aliases
  // assign an alias for the reader key to use
  var alias = efx.registerAlias( keys.writer, keys.reader, data.id, "somename");
  assure ( alias && alias.ok ,"alias", result);
  
  // read it back with a reader key, using the data alias
  var result = efx.read( alias.alias);
  assure ( result && result.ok && result.value === textData ,"assign-alias", result);
  
  // write another rec to the same alias
  var otherData = efx.write(someData,keys.writer,"post",{readers:keys.reader,updaters:keys.updater});
  assure ( otherData && otherData.ok ,"write-for-others-alias", otherData);
  
  // assign the alias to the new data
  var otherAlias = efx.registerAlias( keys.writer, keys.reader, otherData.id, alias.alias);
  assure ( otherAlias && otherAlias.ok && otherAlias.alias === alias.alias ,"other-alias", otherAlias);

 // read it back with a reader key, using the data alias
  var result = efx.read( alias.alias);
  assure ( result && result.ok && JSON.stringify(result.value) === JSON.stringify(someData) ,"read-otheralias", result);
  
  // assign and update alias to an updater key
  var updateAlias = efx.registerAlias( keys.writer, keys.updater, otherData.id, alias.alias);
  assure ( updateAlias && updateAlias.ok && updateAlias.alias === alias.alias ,"updater-alias", updateAlias);
  
  // update it
  var result = efx.update(textData , alias.alias);
  assure ( result && result.ok ,"update-alias-write", result);
  
  // read it back using the reader alias
  var result = efx.read (alias.alias);
  assure ( result && result.ok && result.value===textData,"read-update-alias", result);
  
  // try deleting the underlying data item using the alias.. should fail because we didnt assign an alias to the writer key
  var result = efx.remove (alias.alias);
  assure ( !result.ok ,"remove-should-fail", result);
  
  // assign alias to the writer key
  var writerAlias = efx.registerAlias( keys.writer, keys.writer, otherData.id, alias.alias);
  assure ( writerAlias && writerAlias.ok && writerAlias.alias === alias.alias ,"writer-alias", updateAlias);
  
  // now this should work
  var result = efx.remove (alias.alias);
  assure ( result && result.ok ,"remove-should-work", result);
  
  // check the underlying is gone
  var result = efx.read (alias.alias, keys.writer);
  assure ( !result.ok,"read-should-fail", result);  
  
}


function assure (b , message , result) {
  verbose = true;
  if (!b) {
    Logger.log ("failed:"+message + ' : result : ' + (result ? JSON.stringify(result) : ""));
  }
  if (verbose && b) {
    Logger.log ("passed:"+message);
  }
  return b;
}

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

128

129

130

131

132

133

134

135

136

137

138

139

140

141

142

143

144

145

146

147

148

149

150

151

152

153

154

155

156

157

158

159

160

161

162

163

164

165

function testEfx() {

// set up client

var efx = EffexApiClient.setProd().setVerbose(true);

// boss key comes from console /// replace this with your own

var bossKey ="bx-----------------";

// check service is up

var result = efx.ping();

assure ( result && result.ok ,"ping", result);

// give up if its not

if (!result.ok) {

throw 'service is not up:' + JSON.stringify(result);

}

// get some service info

var result = efx.info();

assure ( result && result.ok ,"info", result);

// check boss key hasnt expired

var result = efx.validateKey(bossKey);

assure ( result && result.ok ,"validate bosskey", result);

// get 1 writer key expiringin in 5 minutes

var writers = efx.generateKey (bossKey,"writer", {seconds:5*60});

assure ( writers && writers.ok && writers.keys.length === 1 ,"writerkeys", writers);

// get 2 readr keys expiringin in 5 minutes

var readers = efx.generateKey (bossKey,"reader", {seconds:5*60, count:2});

assure ( readers && readers.ok && readers.keys.length === 2 ,"readerkeys", readers);

// get 1 updater keys expiringin in 5 minutes

var updaters = efx.generateKey (bossKey,"updater", {seconds:5*60});

assure ( updaters && updaters.ok && updaters.keys.length === 1 ,"updaterkeys", updaters);

// set the keys up as default so we dont have to bother specifying them later

efx.setKeys ({

updater:updaters.keys[0],

writer:writers.keys[0],

reader:readers.keys[0]

});

// more convenient for later

var keys = efx.getKeys();

//---reading and writing

var someData = {name:'xyz',a:[1,2,3],b:2000};

var data = efx.write(someData);

assure ( data && data.ok ,"write-post", data);

// read it back with the same key

var result = efx.read( data.id, keys.writer);

assure ( result && result.ok && JSON.stringify(result.value) === JSON.stringify(someData) ,"read", result);

// do it again, but use a GET for writing

var data = efx.write(someData, keys.writer, "get");

assure ( data && data.ok ,"write-get", data);

// read it back with the same key

var result = efx.read( data.id, keys.writer);

assure ( result && result.ok && JSON.stringify(result.value) === JSON.stringify(someData) ,"read-get", result);

// now do all that with some text data

var textData = "some text data";

var data = efx.write(textData);

assure ( data && data.ok ,"write-post-text", data);

// read it back with the same key

var result = efx.read( data.id, keys.writer);

assure ( result && result.ok && result.value === textData ,"read-text", result);

// do it again, but use a GET for writing

var data = efx.write(textData, keys.writer, "get");

assure ( data && data.ok ,"write-get-text", data);

// read it back with the same key

var result = efx.read( data.id, keys.writer);

assure ( result && result.ok && result.value === textData ,"read-get-text", result);

//-- assigning readers and updaters

var data = efx.write(someData,keys.writer,"post",{readers:keys.reader,updaters:keys.updater});

assure ( data && data.ok ,"write-for-others", data);

// read it back with a reader key

var result = efx.read( data.id);

assure ( result && result.ok && JSON.stringify(result.value) === JSON.stringify(someData) ,"read-reader", result);

// read it back with an updater key

var result = efx.read( data.id, keys.updater);

assure ( result && result.ok && JSON.stringify(result.value) === JSON.stringify(someData) ,"read-updater", result);

// update it

var result = efx.update (textData , data.id);

assure ( result && result.ok ,"update", result);

// check it took - i'll just use the reader key

var result = efx.read( data.id);

assure ( result && result.ok && result.value === textData ,"read-updated", result);

//----work with aliases

// assign an alias for the reader key to use

var alias = efx.registerAlias( keys.writer, keys.reader, data.id, "somename");

assure ( alias && alias.ok ,"alias", result);

// read it back with a reader key, using the data alias

var result = efx.read( alias.alias);

assure ( result && result.ok && result.value === textData ,"assign-alias", result);

// write another rec to the same alias

var otherData = efx.write(someData,keys.writer,"post",{readers:keys.reader,updaters:keys.updater});

assure ( otherData && otherData.ok ,"write-for-others-alias", otherData);

// assign the alias to the new data

var otherAlias = efx.registerAlias( keys.writer, keys.reader, otherData.id, alias.alias);

assure ( otherAlias && otherAlias.ok && otherAlias.alias === alias.alias ,"other-alias", otherAlias);

// read it back with a reader key, using the data alias

var result = efx.read( alias.alias);

assure ( result && result.ok && JSON.stringify(result.value) === JSON.stringify(someData) ,"read-otheralias", result);

// assign and update alias to an updater key

var updateAlias = efx.registerAlias( keys.writer, keys.updater, otherData.id, alias.alias);

assure ( updateAlias && updateAlias.ok && updateAlias.alias === alias.alias ,"updater-alias", updateAlias);

// update it

var result = efx.update(textData , alias.alias);

assure ( result && result.ok ,"update-alias-write", result);

// read it back using the reader alias

var result = efx.read (alias.alias);

assure ( result && result.ok && result.value===textData,"read-update-alias", result);

// try deleting the underlying data item using the alias.. should fail because we didnt assign an alias to the writer key

var result = efx.remove (alias.alias);

assure ( !result.ok ,"remove-should-fail", result);

// assign alias to the writer key

var writerAlias = efx.registerAlias( keys.writer, keys.writer, otherData.id, alias.alias);

assure ( writerAlias && writerAlias.ok && writerAlias.alias === alias.alias ,"writer-alias", updateAlias);

// now this should work

var result = efx.remove (alias.alias);

assure ( result && result.ok ,"remove-should-work", result);

// check the underlying is gone

var result = efx.read (alias.alias, keys.writer);

assure ( !result.ok,"read-should-fail", result);

}

function assure (b , message , result) {

verbose = true;

if (!b) {

Logger.log ("failed:"+message + ' : result : ' + (result ? JSON.stringify(result) : ""));

}

if (verbose && b) {

Logger.log ("passed:"+message);

}

return b;

}

For more like this, see Google Apps Scripts snippets.

Accordeon

Google Apps Scripts Snippets topics

Desktop Liberation

The definitive resource for Google Apps Script and Microsoft Office automation

Apps Script library for Ephemeral exchange

Where to get it

Code

Demo

Before starting

Examples