What's your strategy for building a new Pack?

Making Packs
,
1

Hi everyone, if you don’t know me, I’m the social media manager at Coda. If you’re actively engaging on Twitter or LinkedIn with Coda, we may have already met :slight_smile:

Anyway, I’ve been building a few Packs, some that leverage other APIs, and have settled into a strategy of going function by function as I build out the Pack. But I’m wondering if there are other approaches that I’m missing. For example, I notice that with a lot of APIs, you’ll re-use the same schema — do any of you end up going and building every objectSchema first before the functions or actions?

6 Likes
2

Hi @Brian_Klein !

As a FYI I use my own IDE to develop Packs and do heavy use of Typescript, the approach I usually have is:

  1. Use Postman or Insomnia to play with the third party API, see if the responses matches the documentation correctly and have an idea of the data structures.

  2. Build Typescript definitions for each entity, for example Customer, Invoice, etc and how each one relates to each other.

  3. Define the Coda schema using the types definition from 2.

  4. Crete the function that takes care of getting the data from the third party API.

  5. Build the sync table definition and test!

5 Likes
3

Kind of the opposite of @Leandro_Zubrezki *

I like to see quick results, so I usually go sync table by sync table or function by function. Sometimes sharing with others for feedback after just a couple elements, or sometimes just playing/testing myself. Some fields are mocked/placeholdered to get a feel for things before I have a chance to dig in and implement them properly (e.g. maybe they need advanced massaging or another API call or something).

These experiments tend to inform what elements I need to grab from the API responses, and where I might want to depart structurally from how the API sees the data model - in order to make things more approachable for the use cases I have in mind, or present them more appropriately in a Coda interface.

Then when I have a prototype, I go back through the docs, test with different data, etc. in order to make sure I’m handling all the fields properly and haven’t made any modelling mistakes.

I’m a bit newer to Typescript so while I use some types, they’re not as extensive as what Leandro does. I’d like to get more strict about it. I’d also like to get more into automated testing as right now it’s relatively manual.

*I admit that, like Leandro, I do start with Postman and at least a skim of the docs to orient myself with auth, overall data structure, example responses, etc.

2 Likes
4

I think that’s a really important point @Nick_HE. As someone who’s been working for years with engineering teams creating APIs, they very often model their API based on how the data is already stored or organized inside their internal codebase. While this is convenient for the folks maintaining the API, it may not correlate with how user’s perceive or interact with the product.

Likewise, it may be easiest for a Pack maker to just mirror what’s in the API. But it is worth evaluating whether your Pack would be more approachable if you differed from the model presented in the API.

3 Likes
5

@Leandro_Zubrezki and I have been talking about this in relation to the QuickBooks Packs we’re working on. One challenge we’ve identified is that we don’t know all of the use cases that people will have, and we don’t want to paint ourselves into a corner. At the same time, we don’t want things to be so complex as to be inaccessible to new users.

This is particularly true in situations where you’re simplifying some of the complexity of the API, for example:

  • Leaving out certain obscure API properties that we think will be rarely used, and may clutter things for the user
  • Flattening an object into a string representation, whether that’s just taking one of the properties (e.g. { name: "United States Dollars", code: "USD" } → just a string "USD"), or doing some concatenation to pull out a few key elements and present them as a simple string

Basically we have to try to anticipate, for each property, how often is this going to be the end use of the property, and how often are people going to want to manipulate further with formulas (such as connecting to other tables of data).

It gets further complicated by some very-deeply-nested data structures (e.g. different types of line items on an invoice) that we need to make digestible to users in a formula result / sync table, but also meaningfully editable via an action.

There’s a tradeoff that needs to be considered between simplicity and extensibility, which I think will depend a lot on what your Pack is and how you anticipate people will use it.

All of which I guess is an argument for user testing :slight_smile:

4 Likes