Building APIs That Delight Customers and Developers

In June of 2022 at the National Apartment Association Conference, AppFolio announced its integration marketplace, AppFolio Stack, to address the increasing demand for integrations with the Property-Tech services our customers use daily to streamline their workflows. AppFolio Stack was carefully designed to address what our primary stakeholders, the customer – an AppFolio Property Management Company, and the partner – a third-party Property-Tech service, state is their number one technical challenge: integrations. In a survey conducted by AppFolio, we found that integrations often create the very same problems they intend to solve: double data entry, extra workflow steps for onsite teams, and data inaccuracies. Below are the key concepts that guided AppFolio Stack’s design, making sure our integrations were done right.

1. Optimize The Developer Experience From The Get-Go

Every API should be optimized for the developer's experience and ease of use. We use the “Time to Hello World” metric – the time it takes to execute a core functionality of an API (e.g. a user’s first GET request) - to measure our API’s ease of use. Our API documentation’s Getting Started section walks developers through account setup and their first GET request in right around 10 minutes.

Establishing confidence in our platform's ease of use from the get-go, with code samples, straightforward naming conventions, detailed error messages, and strict adherence to OpenAPI specifications provides developers with a familiar experience – optimized for exchanging data as efficiently as possible.

2. Enable Developers to Simulate Live Integrations 

Before going live with customers, we provide our partner developers with a sandbox environment with sample data that is tailored specifically for their use case. For example, if our partner deals with maintenance - the sample data we provide is robust enough to cover the different business models each company has in place for the maintenance domain.

By performing advanced testing against this sandbox environment with sample data that closely mimics the production environment, we set the right expectations for how partners’ software will perform once they enable a connection with real customer data, and increased load. 

3. Rate Limit to Provide Expected Performance 

To ensure all partners can rely on the availability of our system during periods of heavy load, we configure rate limits on a per-second, per-minute, and per-hour basis to prevent network disruptions that may occur once partner-customer connections go live.

We provide detailed error messages when these limits are exceeded -- and through continuous monitoring, we can promptly communicate ways to restructure our partner’s request patterns to improve their querying efficiency. 

Lastly, all rate limits are structured on a customer-partner pair basis. This provides partners with stable performance that is not impacted by adding new partners or enabling new customers for a specific partner.

4. Practice Quality Assurance in Development 

We implement numerous methods for catching errors before our code goes into production. The first line of coverage is unit testing of the source code and Selenium tests to account for any regressions in the UI. By contract testing and leveraging tools such as Postman and Pact, we ensure our integrations continually provide the stable service promised.

Internally, the Stack API is developed as an orchestration of microservices, and this robust contract testing enables us to independently develop each service with the confidence that we would be notified as soon as a code change violates an existing contract.

5. Proactively Monitor and Alert

In an ideal developer environment, users don’t have to report issues and details about what might have caused them. Tools such as NewRelic, DataDog, and Rollbar alert us as soon as any errors or anomalies happen with our customer’s API usage - and we can proactively inform them as soon as the errors occur. 

6. Allow Time to Introduce Breaking Changes

When developing and supporting a complex API platform, change is inevitable. Planning for change enables us to iterate faster while still being able to revisit previous decisions, and add improvements although these could be potentially breaking changes. Our approach is to support partners when transitioning to the new API version while continuing to support old versions throughout their transition. 

7. Maintain Open Lines of Communication With Developers

We are always receptive to feedback and maintain a direct channel of communication with all of our partners using Slack. Whether the input derives from a slack message, or as a result of our internal reporting system, the feedback is shared directly with our team and often results in constructive changes to our API. Through mutual collaboration, improving existing integrations is one of our highest priorities.

Stay tuned for future posts diving deeper into some of the topics touched upon above!

Authors and contributors: Nevena Golubovic and Tony Froccaro