Cavan Klinsky is the CTO and co-founder of Healthie, an all-in-one platform for health and wellness professionals to run their businesses. Cavan shared his recommendations for API design, the advantages of GraphQL, and his experiences with enforcing compliance as a company operating in a regulated field like tele-health.
We initially had an API that powered everything we do internally. One of the things we have been able to do is take that same API, and make it available for external use. Anytime we improve in one direction, we improve in all the others.
We use GraphQL. I'm a big advocate.
When we first started five years ago, I built the MVP really quickly. It was a rushed foundation and we were tacking things on top, including a REST API. We have a mobile app and a web app. The web app was server-rendered, and not using the REST API, so we were having to recreate functionality in an API just for the mobile app.
A significant factor in our decision to go with GraphQL is we have resources that are accessed in a lot of different ways and places. With REST, if you are trying to call a number of different resources in different places and have lots of parameters, you either return way too much data or you have to make a bunch of calls. And that is a huge pain for performance reasons.
With GraphQL, it is a kind of call and response, and you can only request what you need. It is faster and easier for developers when you need to get data in a lot of different ways.
Another advantage, especially if you are a startup, is it is built to be backwards compatible. It is additive so if you use the mobile app from 2 years ago, you can still use it. It will work forever. WIth REST APIs, you have to do different versions and issue warnings and notifications to users that an old version will be depreciated and no longer supported.
While not as important, a nicety of GraphQL is the self-documenting nature. We had been spending a lot of time documenting our API and updating it.
With GraphQL, it exposes the schema, and will tell you all the queries you can do. You can write annotations and descriptions in your code, and it goes into the documentation. This doesn’t generate Stripe-level docs, but it is a lot more efficient than manual documentation. It is perfect for a fast moving company.
We try to make it so you only have to log in to us. We build a lot of integrations with a huge range of platforms, most of those are through OAuth v2. So if you integrate your Google Calendar to Healthie, for example, you have to go through the OAuth v2 flow.
Other integrations, like our Stripe integration, work by being embedded in Healthie, so the user does not need to have an account with Stripe or authorize access to Stripe.
We were working with Hubspot this morning, and we decided to go with the API key for authentication. One thing to watch out for with API keys is if the company automatically rotates the keys. Some services, like Salesforce, rotate API keys by default, and this can be a problem if the user does not tell you and then the integration disconnects. It’s nice when you can avoid that.
We get notified when we have server errors, or when specific Cron jobs fail to run. These can alert us to integration failures. We are not using any third-party integration monitoring service, which could be a more sophisticated solution here.
We use Mixpanel for product analytics, and it covers that. When people go to the integration page, that is noted. We can see trends and changes over time. You can also see other basic information, like what browsers users are utilizing.
We are discussing this with the product team. Right now, integrations are put in the app in the flow of where you would use them in the product. We sync with a bunch of smart devices, and we have a separate page for that. We include integrations on certain plans so they will be shown to every user, but if they aren’t on your plan, it asks you to reach out to support if you want to upgrade.
It definitely does. We have to be in compliance with HIPAA, which is a crazy law. People in different industries might be familiar with SOC 2 which is a certification framework. HIPAA is about compliance.
There is no certification body for it, but in our space, you have to be HIPAA compliant. It requires taking the right safeguards, and ensuring data is handled correctly across the entire chain.
This has an impact on what vendors we can use, and what companies we can partner with. Often, if a vendor is HIPAA-compliant, they can 10x their prices.
Twilio has a fax API, for example, and I’m sure it is better than what we are using, but they don't offer an HIPAA-compliant version.
Compliance in our industry really does affect a lot of integration options. When we look at building versus buying different things, we have to consider compliance. For example we use hosting that handles the compliance as part of their offering. We're not a 200 person team so we are able to make the buy decisions that do comply to keep us nimble. But if there is not a good compliant offering, we have to build it in house.
My advice to other companies is do not try to be compliant if you do not need to. It’s a big commitment. If you’re enterprise software, make sure that there is significant payback on becoming compliant before you go down that road.
Currently, it is only available to customers. They are doing some cool things with it. It would be something nice to offer to partners down the line. But the technical challenges to offering it can be hard, especially due to compliance and security issues. Any one using it would have to go through the same security and compliance review that we go through.
If you’re a small company, don’t overthink things. A lot of our integrations have gone through iterations to add new functionality. We do a bunch of CRMs, and we are now building a pipeline that uniformly handles all the CRMs we integrate with. If we had overengineered the original integrations, this would have slowed us down. Remember your needs are going to change.
If you have an external API, it is part of your product. Make sure you’re solving the largest pain points first. If you’re not solving core pain points, people won’t use it. Focus on the need-to-haves, and then smooth the rest out later.
Utilize Open Source if you can. If we were on top of Ruby, for example, I might have used RubyGems. It might do everything I need at first, and you can always fork it and add on, or do it from scratch later.
Another element we found advantageous was dogfooding our API. As an API customer, you’re using the same API that our developers use every day. This allowed us to battle test it on a platform with hundreds of thousands of users before we even brought it to customers.
I don’t know of any technical reasons not to build it that way, though there might be business reasons. If you’re Stripe, for example, your whole business model is taking fees on use of your API, so they don’t have a way to dogfood it. Walmart, on the other hand, might spin a similar payment-processing API out, because they tested it by using it for their own needs. For API-first, API products, like Stripe, it isn’t an option.
I always say that tech doesn’t kill a company, people or a bad product kills a company. Shipping things out easier and quicker is my advice. Be flexible and be okay with the API and integration not being perfect.