What is our intention for how users will interact with third-party APIs

[joncodo]

Overview

From what I understand so far, the point of frig is to handle all of the requests sent to an API on the users behalf. This could include authenticating to the service, performing request to get data and refreshing authentication.

what we currently have

Right now it seems that we manage authentication and refreshing of authentication. But then if you look deeper many of these integrations are handling data from the API and processing that data in some way. This springs the companies business logic into the backend of create frigg app.

what I assume customers will do with a new frigg app

My guess is that you already have a software product where all of your back and logic is stored. In order to add logic into our application that stands alongside your application, you would end up adding logic in both places. This is probably not what people are going to do. My guess is that they will want all of their business logic in the classes that are already supporting their application.

treating frigg as a proxy

If we limit the responsibilities of frig to only handle authentication and request processing and authentication refreshing, then our job becomes a lot easier.

Possible Sample code

async myServerlessAuthRoute(config){
  frigg.salesforce.authenticate(config)
}

async myServerlessProxyRoute(request){
  if(notAuthed){
    refreshAuthentication()
  }
  return frigg.salesforce.proxy(request)
}

In this case, we don't need code like this

I just want to open the discussion here to start with the end user in mind in terms of how they will consume Frigg. Right now, it is too complex. We need to make the simple tasks much easier in my humble opinion

[joncodo]

I guess my main intention here is to redesign the interface of how users interact with Frigg. Imagine where the code requires and instructions are like this:

NPM install -G frigg create-frigg-app
create-frigg-app my app

echo Welcome to frigg!
Do you want to create a front end for this application? (Y/N)
From the list below, tell us which integrations you want to install (Note, you can add more anytime with `create-frigg-app generate integration Salesforce`)

echo We will now prompt your browser to log you into all the things you need and set up your config for you :)
npm start

Now the new user simply calls in their existing code:

frigg.salesforce.proxy(method, body, headers)

This will take more time to build but will get adopted much easier :)

[seanspeaks]

@joncodo I put together a diagram once to highlight this difference of "with Frigg, without Frigg"

After reading your thoughts/points, I have three immediate thoughts:

1. Frigg answers the question "How do we make a scalable framework so that we can build and maintain integrations that use a lot of common patterns and allow for isolated business logic with a manageable codebase". In other words, you'd have either started with Frigg and be set because you've got a separated out repo, or you'd reach for a Frigg-type solution as your core codebase gets larger/more mature. Any integration-based business logic should be put into its own area, not necessarily baked into the rest of your application's logic. Ideal for a microservice solution.
2. The other user/person here is not the one off developer, but rather the head of product, head of engineering, or someone whose job is to look at the bigger picture and say "how can we get all of these things built with the resources we have?". What Frigg enables for this person is the ability to look externally for engineering help with external APIs. Instead of having their core engineering learn an external API and its nuances/intricacies once, they can either leverage the ever-increasing value of Frigg abstractions, or they can hire an external team to contribute their knowledge just to an isolated integration codebase (so, they don't need a contractor to have access to their core code/they can just hire expertise in a specific application/marketplace/ecosystem). Or they can combine approaches. The point here is that leveraging Frigg is beneficial for what it unlocks with getting external expertise in the door to help.
3. As it currently stands, Create Frigg App and most of the stuff inside Frigg's core repo do not show half of the puzzle. The first half is "help me handle authentication for many popular APIs and give me a normalized API/framework to handle that whole integration management flow". The second half is "Give me the tools and primitives and common patterns to quickly add business logic to my integrations".

For point #3 above, some patterns that we have scattered around different repos (that need to be given some love in the form of further massaging/abstraction):

• Resumable processes (state machine + caching + common API patterns). One existing Left Hook client has this exercised pretty heavily in their repo.
• Syncing logic (bi-directional, one-way, multiple api mapping). There's an existing "Sync Manager" and "Sync Object", with a not-yet-converted-to-Jest unit test that could be used and exercised further. It's actively used in 3 Left Hook client repos.
• Webhook Handling. This should be an easy drop-in... need a new webhook handler? What type of webhook? (There are 3 common patterns). Handler drops into message into SQS queue (or Google Cloud PubSub topic etc.), and a separate function handles the actual message.
• Cron/Polling Based Eventing. This is used by every current Left Hook client, very common pattern.
• Target API Specific Code patterns. Primary example for this is HubSpot, where there are some common patterns that are immediately templateable and should be abstracted/made easier to consume for the end user developer. CRM Extensions (HubSpot makes a request to an API endpoint that you the developer informs HubSpot of; HubSpot calls the endpoint on every Contact/Company/Deal page load (configurable); HubSpot expects specifically formatted JSON in response in order to expose a UI widget inside HubSpot).
• Unified API patterns. We're just starting to scratch this surface. But the ultimate goal is to have a layer on the API Module (not sure where it should go yet) where the API is translated/mapped to a specific category, so as the consumer of the API you can expect a normalized body back regardless of the underlying API being used. (So, "Contact" from a CRM comes back with the exact same fields, just swap out the underlying API provider and it still works... this enables development of categorical integrations).

There's much more that we'd add to the mix, but I think the last comment I would say is: Anyone is welcome to use any of these packages as they'd like. In the proxy case you're expanding on here, I would instead suggest that the developer grabs the API module, figures out on their own where to store api credentials, and then uses the Manager and API module to handle the requests in whatever they're doing for their compute. That said, there's no reason that they/we couldn't make a proxy layer microservice out of a Frigg application; that would be a valid use, once we've added more tooling around logging and handling etc.; It just seems to me that it would be underutilizing all that Frigg has to offer (once we've done the work to make the abstractions and functionality available to pull in).

[joncodo]

Ok. That all sounds good to me. I can think of two take aways to be discussed.

1. @seanspeaks please approve - :) I think every api module should include the proxy method by default in the case where we do not have all of an API mapped over with helper methods.
2. I will write new tickets for use cases and we can refine that and put it in the docs. I think it is important to know who this is for and why you want to use it and why you don't want to use it.

@seanspeaks please validate these comments for the docs and modify to be more accurate 😄

Why you would want to use Frigg

• You need to work with many APIs that interact with a lot of data
• Its a scalable framework that handles interactions with many APIs
• You can use common patterns to interact with all API features that are exposed
• You can use Frigg as a micro service to handle your API interations
• If we all work on the same problem, we all win when it comes to dealing with APIs

Why you may not want to use Frigg

• You only need to interact with one API. (Frigg can still do this but the learning curve might out weigh the cost)
• You don't want to use serverless
• The methods on the API that you need have not yet been exposed by the frigg framework (Feel free to make a PR 😄 )

How is Frigg different than passport js?

• Frigg handles a data model
• Frigg handles authentication for you
• Frigg exposes API methods from the API with a layer of abstraction

[seanspeaks]

please approve - :) I think every api module should include the proxy method by default in the case where we do not have all of an API mapped over with helper methods.

Totally- though currently, that's achievable via access to the internal methods, which should inherit auth method/headers by default (api._get('url', optionsObject), ditto _post, _put, _delete, _patch)

I will write new tickets for use cases and we can refine that and put it in the docs. I think it is important to know who this is for and why you want to use it and why you don't want to use it.

Yup agreed

Why you would want to use Frigg

• You need to enable end users of your app to work with many APIs that interact with ~a lot of~ their external data in a low-touch, no-code UX
• ~Its a scalable framework that handles interactions with many APIs~ You want an architecture that allows for zero or low cost when there is little to no usage, but will scale quickly without DevOps/infrastructure management overhead
• ~You can use common patterns to interact with all API features that are exposed~ You want to use tried and true common integration patterns that take advantage of general API features and features specific to a given API, without having to come up with those patterns yourself
• You can use Frigg as a micro service to handle your API interations
• ~If we all work on the same problem, we all win when it comes to dealing with APIs~ As a whole community of developers solves bugs and adds features, we all benefit from an easier integration development experience. Thousands of developers will solve problems much faster than any one company or developer ever could.
• The library of API modules is ever growing and improving, and it's simple/easy to add your own
• New recipes, workflows, and code patterns are added at a regular basis by the core team and by community contributors that could greatly benefit your own integrations
• You'd like to involve external developers to contribute their code to your integrations, but you don't want them to get access to your whole primary codebase
• Other solutions are too costly

Why you may not want to use Frigg

• You only need to interact with one API. (Frigg can still do this but the learning curve might out weigh the cost)
• You don't want to use serverless, or you want to use a technology that is not yet supported by the core framework
• The methods on the API that you need have not yet been exposed in the Frigg API Module (Feel free to make a PR 😄 ) [Sean comment: Not sure this is a real objection when considering internal methods are readily available? see note above]
• Frigg is not yet mature enough
• You already have a working framework for developing integrations rapidly

How is Frigg different than passport js?

• Frigg handles a data model [Sean Comment: I don't know what this means?]
• Frigg handles authentication and credential storage for you
• Frigg exposes API methods from the API with a layer of abstraction
• Frigg's primary focus is on the actual development of the business logic that powers an integration; Passport.js focuses on user authentication and identification.
• Frigg has opinions on compute and has primitives based on serverless compute to build that integration logic

[joncodo]

Excellent work flow. I think this is a great new docs section!