Guideline to using ermrestJS error handling and logging

We want the deriva webapps to use all the existing error handlings that we have in ermrestjs and chaise. This includes the retry logic and the logging. What this gives us is better error handling that is more understandable within the webapps. ErmrestJS handles mapping http errors to more readable errors with messages that help to point out what the problem could be. This guide will NOT include the UX modules that are available in chaise for showing errors as popups, this is purely the functionality from ermrestJS.

The intention is that this will be used with angular apps. For use in a javascript app without angular, see treeview/main.js for an example. This was initially explained in more detail in this issue.

// It isn't required to wait for ermrest.onload(), but it will help prevent any race conditions from occurring.
// it is necessary to wait for onload if your app relies on templating and some other ermrestJS utilities
ERMrest.onload().then(function () {
  // getting the service object and http module:
  var ermrsetServiceUrl = chaise-config.ermrestLocation || "example.com/ermrest";

  // the contextHeaderParams will be logged with every request that you will send
  var contextHeaderParams = {"cid": "deriva-app-name"};
  
  // with this API you can access http module and also get Catalog and all it's table, etc.
  // server.catalogs.get("catalog-id") will return a promise that will be resolved with the catalog
  // server.http will return the http module that you can use for sending requests
  var server = ERMrest.ermrestFactory.getServer(ermrestServiceUrl, contextHeaderParams);

  // log stuff
  var headers = {};
  headers[ERMrest.contextHeaderName] = {
    schema_table: "schema:table", // the name of schema and table in `<schema>:<table>` format 
    action: "", // a string representing the type of request. Something unique throughout the whole ermrestjs and chaise.
    cid: "<deriva-app-name>", // same from above 
    pid: "<random uuid string>",
    wid: "<random uuid string>"
  };

  // sending the request
  var uri = "the ermest uri";
  server.http.get(uri, {headers: headers}).then(function success (res) {
    ...
  }).catch(function (
    throw ERMrest.responseToError(err);
  });
}); // end onload

Note: For generic UI errors, chaise errors.js and its dependencies are all included. For custom errors, CustomError class of chaise is used.