Given the overall importance of APIs for SaaS products, dev teams are increasingly interested in API-first development. And that's a good thing. But, whether you are taking an API-first approach or the more traditional app-first approach, an API is essential for your SaaS product. This is especially true for all the integrations your customers will need to connect your product to all the other apps they use.
And building your API correctly makes all the difference. Everything begins with treating your API like a product – because your customers will. A big part of this is prioritizing the UX for your API from the beginning.
Here are a few things to consider as you plan and build your API.
Start with an API mockup
Before writing the full-fledged API, it can be helpful to build an API mockup. For the same reasons we have a UX designer mock up UI screens to test app flow and usability, it can be beneficial to mock up your API.
This mockup can be as simple as writing a partial API schema or basic API documentation and then attempting to write code to make a real interaction with your product. That code doesn't have to run or even be runnable; it's a mechanism to "UX test" your mockup by starting from your user's perspective.
While writing the mockup code, answer these questions:
- How does that code look? Is it obvious to read and understand?
- Does the API feel suited to the problem you are solving?
- Is it obvious what calls need to be made in what order or what data you want from each call?
- How about pagination or error responses? Is it clear what you should check for?
This type of doc-first development can be a cheap way to test your domain model and assumptions around usage without fully implementing your API. In just a few hours, you can have multiple developers solve several mock scenarios and generate helpful feedback.
Developing against an API has additional requirements
Part of an API's unique UX is that users likely need additional data, visibility, and access when developing against it. Some products solve this with API dashboards, or special sandbox accounts with additional logging or visibility enabled.
Stripe, a common reference point for high-quality developer experiences, has an entire "dev mode" you can enable for an account. It segments data, allows for simulated transactions, and can show all that data directly in a dashboard. It also has unique access controls and cannot interact with data outside of the development sandbox. It will generate unique errors if you attempt to interact with non-development resources.
Another popular API to reference is Github. Github doesn't include a special developer or sandbox mode, but it has comprehensive audit and event logs that include failed requests with detailed error messages to make debugging easier. Github's GraphQL-based API also has a "playground" that allows an authenticated user to try out queries directly in a browser alongside the documentation.
Both of these development approaches create an experience that shows focus and care on the development and debugging process and supports an overall impression of the API as a first-class product rather than a secondary concern.
Webhooks provide needed options
Some of your API user scenarios may encourage users to poll your API for resource changes. While this pattern may be fine, it can be costly to scale and potentially difficult for users to build against. One path to making those scenarios easier is implementing webhooks for your product.
However, this is not a small decision. For your team, adding webhooks brings complexity, a greater maintenance burden, and more scenarios that need thoughtful development and debugging. For your API users, webhooks may simplify certain interactions, or instead require them to build multiple interaction modes for their use case. That said, webhooks can provide huge wins for scalability and a greatly improved developer experience for both your team and for your API users.
Choose the right API type
There are nearly infinite ways to organize and arrange the structure of your API, although most commonly today, it's some form of REST or GraphQL. Where possible, stick to standards. GraphQL and OpenAPI are common and well-understood. Choosing a standard API structure will make integrating easier, give your customers more out-of-the-box tools, and simplify decision-making.
GraphQL is well-supported in various languages and has common approaches to solving issues like pagination, data filtering, and general querying. It's an awesome choice for complex domain models with lots of fields and gives your API consumers a lot of flexibility in how they interact. Rate limiting tends to be more complicated, as the cost to run a query may vary wildly between queries. It also tends to be weaker with complex, write-heavy scenarios, or those where a write isn't tied directly to a concrete resource.
OpenAPI includes more implementation options, although it tends to stick to RESTful approaches. It allows for a lot of flexibility while still providing support for evolving data schemas. In many cases, client generation via the OpenAPI schema is feasible.
Both toolsets provide great ways for generating and displaying documentation with popular tools and libraries.
Versioning is essential
Think about versioning early, before you release your API's first version. It may seem that worrying this soon about how your API will evolve and change is getting ahead of yourself. But versioning is one of the few things that's hard to change after customers use it. As your product evolves, so will your API. Deciding up front how you will handle versioning makes it clear to your API's consumers what to expect.
Versioning can be as complex as per-field schema evolution or as simple as putting a /v1/ into your URL.
Schema evolution systems like those used for most GraphQL APIs are incredible helpful for minor adjustments of data returned about a particular resource, adding fields, adjusting constraints, etc. However, they don't fully solve for version changes involving high-level resource reorganization or approaches to querying.
On the other end of the complexity scale, URL-based versioning is simple, highly visible, and easily understood. And it may already be included with your server-side tooling.
In addition, there is versioning that is HTTP header-based, content-type, and hybrids of all of the above. URL versioning is a good default if you don't have a solid technical reason for a more complex answer.
Use your own API
Lastly, be your own API consumer. The standard advice is that your public API should also be your internal API. This helps reduce possible maintenance and support, but internal and public use will likely diverge when you treat your API as a product.
Regardless, you should exercise the key use cases of your public API yourself and experience what a user will experience. Here are a few ways you can "dogfood" your API:
- Use your API for internal needs, whether admin tasks, small automations, or in-house integrations. Maintaining them over time while using your public API will give you a great perspective on actual user behavior and challenges.
- Prototype new features using the public API outside your primary code base to see how far you can stretch what your API can do.
- Create publicly available sample projects and keep them up-to-date and relevant as your API changes.
Make the most of your API
We've touched on several things you should keep in mind as you plan and build your API, from mocking up the API to ensuring that you use the API yourself – all to ensure that you are keeping the UX of your API in mind from day one.
Beyond these, and everything else that goes into building a great API, there are things you can do to make the most of your API once it is up and running. And one of those is to use an embedded iPaaS with your API to build all the integrations your customers need.
Schedule a demo, and we'll be glad to show you how leveraging an embedded iPaaS allows you to spend more dev time on your product, including your API, and much less time on integrations.
