Troy Goode, founder and CEO at Courier, and a member of the ExpressJS core team, shared his experiences and insights on Engineering an API-first Product at QCon San Francisco 2022.
Troy started his talk with the definition of API-first by referring to the 5 principles of API-first development from Algolia:
-
your API is a product;
-
has foundational design, not an ad-hoc retrofit;
-
has a team-wide focus on Developer Experience(DX);
-
is composable with reusable components;
-
has API contracts that are reliable, descriptive, and consistent.
Courier practices API versioning and maintains backward compatibility on all historical versions. Troy emphasizes that “although backward compatibility is hard, do it anyways” because customer acquisition cost is high, and your users will most likely stay on the version they started with. Most of the new features are going to be for the following sets of customers because the last customer who needed these features would have already solved it.
Troy shared that Courier is able to achieve backward compatibility by using the expand-and-contract pattern to send different versions of the payload to different versions of the infrastructure and eventually eliminate the legacy infrastructure when the new infrastructure has achieved feature parity.
Next, Troy recommends having a variety of good documentation for different purposes for API-first products. In addition to the standard reference docs for API consumers, Troy advocates creating different documentations for different scenarios and stakeholders, such as guides for narrow, use case-specific purposes, solutions for complex, multi-layered problems, and demos such as loom recordings and code examples on GitHub.
Working with his clients, Troy finds that SDKs are very valuable for client adoption and generally improve the developer experience for his clients. From his experiences, Troy points out that you are going to need about 7 SDKs for server-side APIs and about 6 more for client-side APIs to cover most of the popular languages and frameworks. Troy emphasizes that although building SDKs is time-consuming, they should not be auto-generated. Take a bespoke custom development approach for each SDK to make it feel idiomatic to developers.
Providing reliable logging and offering UIs for your customers for debugging can pay lots of dividends as you enable your customers to be self-serving. Troy offers a few insights, such as allowing your UI to do jump-to by server timestamps and returning and allowing lookups by correlation or trace ids to improve the product experience.
Troy believes that API-first products should be billed as usage-based. The two dominating models in the industry are prepaid wallets like Twilio and monthly true-ups such as Datadog. Usage-based billing model has implications for designing and implementing APIs - APIs need to be able to collect usage and calculate billing. APIs also have to be able to handle when payments are not made on time. While returning HTTP 402 can be a good starting point, insert the human factor, such as a grace period, if your application has real-world implications,
Troy pointed out that measuring success for API-first products is very different from traditional product-led growth. Off-the-shelf solutions might not be able to deliver the necessary reports and insights, and in-house developed custom solutions may be necessary.
Courier uses Segment to collect client-side and server-side activities; Fivetran to ETL the necessary data from the application database in AWS to data warehouses; Dbt to build intermediate tables; and Census to reverse-ETLs the necessary data to other platforms.
After the talk, Troy told InfoQ that using serverless and managed services like AWS Lambda and AWS DynamoDB had helped simplify building API-first products at Courier. Another great resource is AWS Aurora Serverless. However, that was not available at the time when he started Courier.
Lastly, note that the talk on modern APIs, building modern backends, and most other conference presentations will be recorded and made available on InfoQ over the coming months.
