The technical writing team at Wix stretches the boundaries of technical writing to include reviewing for developer experience (DX) and API usability. As such, we have front row seats to the constant internal battle between the need for speed and the quest for quality in API design and development.
Photo by Nathan Duck on Unsplash
Wix has set the ambitious goal of becoming an open platform that will attract others to build functional products on it. If we want to become a platform that people around the world use to build products that will drive their businesses forward while exponentially speeding up our own growth, we must meet developer needs and make it easy for them to do what they want.
API usability review is a major part of what we do as technical writers at Wix. Over time, while helping our development teams plan and QA their APIs for usability, we identified the following usability rules: Keep the design simple, make it easy to consume, and provide real value.
These rules are making it easier for product teams to meet the usability requirement and move us toward the goal of making Wix an open platform.
Keep the design simple
It should be easy for consumers to understand what the API does from just a quick look at the menu, entity, and endpoint names.
This means ensuring that all names are intuitive and represent what every API, function, and attribute does. If you can’t come up with a clear name, or if any stakeholder misunderstood what something meant or what it could do, these are red flags.
Some types of functionality are truly niche and might take a bit longer for someone not familiar with them (for example, an SEO Site Inspection API), but this should be covered in the introductory documentation and user flows.
This also means that if you divide your feature into microservices, for example, the organization should be clear to someone from the outside. In addition to thinking through all the standard architectural issues involved with microservices (for example, internal communication and dependency conflicts), take several steps back and look at the structure from the API consumer’s point of view.
Simplicity can be affected by all kinds of decisions. For example, is it 5x cheaper to develop a new, highly requested feature as an add-on to an existing feature’s API instead of building a new, separate API for it? Could be, but using one API to support two seemingly independent features definitely doesn’t qualify as simple.
Some questions to ask about this:
Can an outsider immediately understand what this API does?
Can a non-developer immediately understand why they might want their company to use it for their needs?
A word about simplicity vs. complexity - designing a simple API does not mean that we are sacrificing functionality, which often requires complexity. It means that we are taking responsibility for that complexity on ourselves so our API consumers won’t have to.
Make it easy to consume
How many times have you looked at an API that seemed simple and clear, only to get stuck in the weeds when you actually tried to build something with it? Yeah, us too…
There are lots of factors that go into this one. Here are the ones we’re focusing on:
Consistency: Using consistent naming and architecture saves the external consumer time and lines of code. For example, all GUIDs should be called IDs. When a team named their primary GUID `fileName` instead of `fileId`, Wix received so many support requests we had to write a forum post to clarify the situation for users (it has over 3k views).
Clear Application: This is closely related to simplicity, but from a different angle. Is it obvious how an API consumer might put together the various functions into steps that meet their use case? Have we provided everything that they’ll need along the way, such as input parameters, prerequisite data, and limitations? For example, assuming we provide one Orders API to get an order and another Invoices API to create an invoice for that order, how clear is the process (or is it even possible) to convert the payload received when an order is created into a create invoice request? Does it use the same terminology? Even better, could we have an endpoint in the Order API that creates an order and its invoice simultaneously?
Cost efficiency:
Allow for code reuse (consistency is crucial here)
Limit the need for validations
Cut down the need for external data storage and calculations due to lack of functionality on our side
Provide excellent error messages that include how to fix the issue
Minimize the need for deprecations by planning ahead
Provide ample warning about deprecations and end of life
Make it difficult to make costly mistakes, especially with sensitive data
For example, we should give external consumers the option to add identifying information to our entities. We shouldn’t expect external consumers to maintain their own database to map their entities to ours, when the simple addition of an attribute like `externalId` would save them the trouble.
And another example: Make it easy for the external caller to act on behalf of site owners (our shared customers). Not enabling external callers to filter data the way a site member or visitor would see it, increases the risk that their platform will display data to a customer that they shouldn’t have access to.
Some questions to ask about this:
Are we making it easy for an API consumer to build their service using our APIs?
Will external API consumers be able to build a successful business around our APIs?
Provide real value
The APIs we expose should enable API consumers to innovate and build features that will delight our customers and give them the tools they need and want. Wix can’t provide every feature requested by every site owner on its own - we need to empower our external API consumers to build the functionality that we can’t prioritize.
Some questions to ask about this:
Does an external API consumer have what they need here to build something worth selling?
Can they use this API to serve Wix site owners in the best possible way? Can they complete both basic and advanced user flows with the available functionality?
Can they build something with this API that will enhance Wix’s open platform?
Have we received any requests from external consumers for this functionality? If so, what did they want to build with it? Can you talk to a potential external consumer and get details about what they want/expect?
For example, the ability to trigger sending an email based on a Wix-defined template is a useful feature - but will it attract anyone to build a product around it? Chances are they will need the ability to edit the content sent in the email, and to control when and how the email is triggered within internal Wix flows to prevent it being sent twice, before anyone would consider using it.
Conclusion
All 3 of these golden rules require that we put ourselves in the consumer’s shoes and look at the APIs from their point of view. This is easier said than done, but when we get it right, the long term payoff will be huge. We can do it, and it can make our business skyrocket.
P.S. We’re not focusing on other critical issues like API performance and security here, even though they are extremely important to all API consumers, simply because we aren’t involved in this aspect of the company’s platform. For more about these crucial issues, see 7 Steps to Improve API Performance and Gartner’s Report on API Security.
This post was written by Aliza Solomon
For more engineering updates and insights:
Join our Telegram channel
Visit us on GitHub
Subscribe to our YouTube channel