How we designed the Remote API for an excellent developer experience

In our opinion, if APIs are designed well, then developers will love them — and if developers love them, they will invest heavily and even become evangelists for that API. At Remote, excellence is one of our core values. We respect a developer’s time and the resources they risk by building on our platform.

With the Remote API, we are enabling developers to utilize global employment endpoints we have created to white label and offer Remote’s employer of record (EOR) services easily through their HR and payroll platforms. Ultimately, it is our mission to provide the tools and resources needed to create a delightful developer experience and to create value for our partners and joint customers.

I just mentioned that one of the Remote values is excellence. Excellence extends to everything we do. That includes the way we communicate and, even more importantly, the things we build, the code we write, and the way we treat our people. We are making hard, boring things easy. But because we deal with important matters, like employee data and payslips, we must do so perfectly.

We believe developing your own API style guide can’t completely save you from challenges or risks, but this type of guide will help you make decisions openly, honestly, and with clarity. In this post, we will describe our API design principles, as well as our process for how new APIs are specced, reviewed, and tested. By the end, you should have at least a few ideas that you can take back to your own team.

Our top six design process tips

Here is what we have learned from building the Remote API over the past year.

1. Don’t try to boil the ocean.

It is very easy and tempting to try to solve too many problems at once, hence boiling the ocean. Pick a specific use case to tackle first rather than trying to solve many issues simultaneously. That way, you can focus on a single design and keep your API clean from the start.

Remember, it is easy to add new features to an API but hard to remove them. Also, narrowing the scope and solving for a specific use case gives you an opportunity to get your API out into the world sooner and get developer feedback quicker so you can continue to make refinements.

At Remote, we tackled our global employee capabilities of the API first. To stay focused, we saw this iteration as solving the most common problem employers face in today's world — which is how to hire and onboard international employees easily!

2. Make sure it is fast and easy to get started.

It is no use building an excellent API if developers cannot understand it or get started quickly. You want to ensure developers who are unfamiliar with your API can complete a “Hello world” exercise in a reasonable amount of time. One metric you can use to evaluate this is “Time to First Hello World.”

At Remote, we ensured developers would have a fast and seamless experience with our API by focusing on clear, easy-to-use documentation with lots of real-world examples and sample coding. As a result, our time to create a new employee in Remote is less than a minute.

3. Consistency is king.

Ideally, your APIs are intuitively consistent. That should be reflected in your endpoint names, input parameters, and output responses. Developers should be able to guess parts of your API even without reading the documentation. This means it should work similar to what they already know.

We see a couple of requirements with consistency:

• Consistency with industry standards: We decided to go with a REST API, and we are applying the industry standard criteria for predictable and consistent interactions with the API. You should adhere as closely as possible to accepted best practices in the industry.

• Consistency with your product: Your chosen field names should be based on what you call them in your product. Always avoid abbreviations, acronyms, and jargon. Be transparent.

One of the best ways to achieve consistency is by making sure your opinions and communication around the API design are concrete and written down. There is always a different way to look at something, but it is imperative you pick a side and stick with it. At Remote, we wrote down comprehensive API design guidelines in Notion, making sure we defined the consistent practices and patterns that we follow for our API. Then, we distributed those guidelines to every team member who might be involved in building, reviewing, or using our API.

4. Make troubleshooting less troublesome.

Incorrect and unclear errors are incredibly frustrating and will negatively affect adoption of your API. Still, it is common for engineers to pay little attention to the errors returned by their APIs. The result is developers getting stuck and eventually abandoning the project. For a better developer experience, make sure you return error messages that are easy to understand and actionable for those building to your API.

At Remote, we built a REST API and used the standard HTTP status codes so clients can easily understand whether a request succeeded or failed.

5. Design for scale and performance.

Bad design can limit performance. While designing an API, you should ensure a couple of things:

• Rate limit your API. For rate limits, when you are in the early stages of developing a new API it is hard to know what limits to implement. That is why we are taking a try-and-see approach. At Remote, we have started with a limit that seems reasonable based on what others have done, and we plan to closely monitor that and seek feedback from partners to determine if the limits are appropriate. Based on that we can always make adjustments. Setting rate limits are important to protect the infrastructure while increasing reliability and availability of the application.

• Paginate big collections: Quite often, APIs need to handle large datasets. An API call might end up returning thousands of items. This can overload the web application backend and even slow down clients that can’t handle large datasets. For that reason, it is important to paginate any large result sets.

6. Avoid breaking changes.

What is a breaking change? Any change that can stop an existing app from functioning as it was before your change.

We all live in fear of a new API update breaking a client’s code. Just thinking about it makes us break out into a cold sweat. This is the last thing any developer needs, am I right?

At Remote, we are only just starting to think about how we will handle breaking changes. It is a balance between not being a drag on the development and the evolution of our product by insisting other teams can't make changes, and protecting our partners and customers from breaking. A few thoughts here:

• The entire engineering organization needs to be aware of the API and how it is being used; thoughtful about how their changes impact the API; and contributing to incorporating their product changes into the API with the least impact possible.

• Keep a good log of minor changes and share it with developers.

• When breaking changes are unavoidable, have a policy on when a new version of the API becomes necessary, how you will support end of life older versions, and how to communicate this policy so developers feel comfortable they won't find themselves stranded on an old version.

The reality is, things don’t always break when you want them to. Be sure to have a solid communication plan at the ready, just in case you have to respond to a breaking change you didn’t anticipate and cannot roll back.

Key takeaways for building your API

Let’s face it: creating excellent, intuitive, consistent, and easy-to-use APIs is really difficult. Hopefully, we covered enough of the API design principles we follow at Remote to give you a great starting point. It is also important to mention that at Remote, we believe in learning together, listening to feedback from our developer community, and continuously making improvements based on the feedback we receive. So, while all our tips are important to a good design process, we are always keeping ourselves flexible as we move through the process.

As a bonus, here are our top takeaways when you are building an API:

• Spend time thinking about your API design up front

• Be intentional with your design choices

• Collect feedback from multiple stakeholders

The Remote API is now available for Partners and Remote Customers, learn more here.