Getting Started with the REST-API

Getting Started with the Server-Side API

The ClearFactr API is your gateway to building solutions to problems in ways never before possible. It has all the features you’ll need to interact with your models in ways limited only by your imagination. The ClearFactr team wants to help ensure that you not only “get it working”, but that you “get it right.” A bit of strategizing around how to best use the API for different types of situations — and figuring out which one most closely matches your own — will help guarantee your solution will perform at its best, and endure.

QUICK TIP

If you're simply looking for the endpoints to the API, they're here. The purpose of this document is to help decide which endpoints to call, when, and why.

The Basics

A ClearFactr model is often referred to as a "plan" because they are often time-based. Understanding a few basic concepts and idioms will help you to make the most of the API:

• GUIDs - Guaranteed Unique IDs (GUIDs) are used by ClearFactr to refer to each of the various parts of the data model that collectively make up a model. The nice thing about GUIDs is that they never change. Once you get a particular GUID for a particular aspect of the model, you may be able to use other endpoints that operate directly on, and only on, that item. GUIDs are always case-sensitive and include all 26 letters of the English alphabet, plus the digits 0-9. Most GUIDs are 16 characters in length.
• POSTs - All of the endpoints in the API use POSTs. This affords maximum flexibility and security, prevents the API from being brittle, and can assist in making your own code more self-documenting. You may find it helpful to create and use convenience methods to create containers of key-value pairs with which to generate your POST.
• Zero-based indexes - In cases where numerical indexes are required, like for a row or column index, they are zero-based. So, the first row in a sheet is row index 0, the second row is index 1, etc. Likewise for columns and any other collection of items: the first item in the collection is item 0.
• Evaluated versus Minimal Cells - There may be many cases where you are not concerned with the evaluated values of a group of cells, for example, if querying a bunch of input cells to a model. In this case, the formula strings are the evaluated values (10 evaluates to 10.0). Any formula-driven cell can only return a value when the entire model is evaluated (or at least, any of its computational parents). Therefore, two families of endpoints exist for querying cells: one that returns evaluated cells and another that returns minimal cells. The latter return type will not have a 'value' property. HOWEVER, this latter type will almost always be a faster endpoint call as the entire model does not need to be loaded and evaluated to return the result. Caches are used to make the evaluated use cases as fast as possible.

The ClearFactr Data Model

A ClearFactr model/plan is logically broken down into a number of important components. Understanding how these work with each other can aide in your own solution's architecture. The components include:

• An ownerID, which is the GUID corresponding to the ClearFactr user that owns the model/plan.
• A planID, which is the GUID that differentiates one model/plan from another.
• One or more tabIDs, which are GUIDs assigned to each of the Tabs (or Sheets) in the model/plan.
• One or more rowIDs, which are GUIDs assigned to each of the Rows in a Tab. Note that Rows are also sometimes referred to as attributes of model/plan.
• One or more columnIDs, which are GUIDs assigned to each of the Columns in a Tab. Note that Columns are also sometimes referred to as timepoints of the model, in the case of a time-based plan. In this case, the column itself will have a datetime value associated with it.
• Optionally, one or more columnIDs maybe grouped within a columnSpanID, corresponding to a Column Span that semantically and visually groups one or more adjacent columns. A given tab may have multiple spanning headers, but no column will ever be part of more than one span. Only one level of spanning is supported (spans cannot contain other spans),
• One or more cellIDs, which are GUIDs assigned to each of the Cells. Any Cell can also be referred to in row/column coordinates, or using a rowID/columnID pair.

QUICK TIP

The latter "key" has the nice benefit of not needing to know or care what the physical location of the cell is and, depending on your program design, can yield a solution that is more resilient to changes in the physical layout of the model.

The Component Inspector

[Deleted image]

The Components Inspector can greatly facilitate working with any particular model. Any GUID you might need for a model, sheet, cell, or range of cells, to be used by any given API endpoint, can be obtained via this interactive tool. Note that if you select a single cell, only the Upper Left fields will be filled in. In the example above, the selection was from C1:C2. Therefore, take note, the columnID is the same for both the Upper Left and the Lower Right cells of the range.

Access Tokens

Every API-based solution will start with a call to the apiLogin endpoint to obtain an accessToken, which in turn is required by every other endpoint. Access Tokens expire in 60 minutes, and the endpoint will return the time at which the token expires. Therefore, best practices are:

• If you know your work will take less than 60 minutes, get the accessToken up front and then re-use it for all subsequent units of work in your solution
• If your work might take longer than 60 minutes, determine some appropriate place in your workflow to get a new accessToken, either:
  1. According to how much time is remaining before expiration; leave a small margin for error with this to allow for latency
  2. Based on chunking up your work into logical units, with each unit being certain to complete before expiration (or otherwise gracefully fail)

Solution Strategies

Regardless of your use-case, you'll want to make some conscious decisions up front about how you'll work with your model or models. In some cases, you might have the luxury of being able to influence or control the design of the models themselves. In other cases, the design of the model might already be determined, and you'll need to "work with what you have." The rest of this section will present some issues for your consideration.

What Model, or Models?

If you know precisely which model or models you'll be working with, you can utilize their pre-existing planIDs that you can query ahead of time and preserve in a safe location. Otherwise, you can use the getUserPlanInfo endpoint to return back a collection of metadata for models that you have access to. That endpoint can also filter by model name. Iterate over the collection to determine the model or models you need to work with. Keep in mind that once you have a planID, you can rely on that GUID to identify your particular model, even if the owner or co-author of the model changes its name later on. This brings us directly to the next topic...

Stable or Unstable, Static or Dynamic?

The most important issue to consider when you begin to use design your solution around ClearFactr's API is whether or not your models are structurally stable, and to what extent. Keep in mind there can be a "continuum of stability": Beginning with any given sheet, the most structurally stable sheet can be counted on having the same number of rows and columns each time you work with it. Depending on how the owner or co-author of the model is working with the model, they might add or remove rows and/or columns. Likewise, the entire model may have a "stable" or "unstable" number of sheets. Or, the number of sheets might stay the same, but they might get renamed from time to time (likewise for names and/or column names!).

If the property or dimension of the ClearFactr model you're working with is stable – and therefore, trustworthy – you can optimize a solution that leverages the GUIDs of the associated property. Conversely, if you want or need to remain very dynamic, your solution can start with a call to the getMinimalPlanDefinition endpoint. This will return all of the structural information about the model, but none of the evaluated content. Then you can interrogate the resulting information for basic info such as the number of sheets, the structure of any given sheet, and properties thereof, such as the sheet's name, the columns, the column names, etc.

Keep in mind that somewhere in your design, you'll need to have some kind of anchoring mechanism and/or assumption. If you want to treat the fourth column of the second tab in a certain way, your anchor is the assumption that no tabs will be inserted to the left of that tab, and that no columns will be inserted prior to column four. That might be fine.

Conversely, you might want to anchor around a certain tab name, and find its location dynamically based on the names returned by getMinimalPlanDefinition. Then you might want to rely on certain column names – keeping in mind you can rename the legacy "A", "B", "C" column names to potentially more meaningful things. Or, you might want to designate a certain row to hold important information, and you'll explicitly "query" that row for your anchor points. In this way, could could insulate yourself from columns and/or rows from being inserted or deleted, as long as what you'll look for won't itself change.

Finally, of course, if your solution counts on finding a column called "Profit", and it doesn't find it, you'll want to handle that gracefully.

Adding Resilience

There are several ways the model's design – via the WebApp – can add resilience and reliability to your solution:

• ClearFactr's support for named ranges can eliminate the need to interrogate the model for the physical location of certain piece of data or result. They can be used as a logical insulation mechanism.
• Via the various user editing roles and permissions, you can minimize or eliminate the potential of structural changes being made to the model.
• Via cell permissions, you can ensure that cells containing key business logic cannot be changed.