Whether you know it (like it) or not, the Internet is driven by open data. When you go to an ecommerce site to search for new shoes they are most likely showing inventory pulled from several suppliers in real time. The only way the reseller can provide immediate results when you type in Elton John mirrored platforms is if the shoe data is available from the suppliers in some kind of structured, open data format.
To keep a manageable scope around the term “open data” let’s consider only the data sets that organizations publish via APIs. Depending on their mission and goals, organizations open their data for various reasons:
- They may charge for access to the data
- They may be looking to expand the reach of their brand by giving it away
- Their business model may rely on paying developers to push their content to their own customers.
In our case, software engineers from the shoe reseller initially create those connections by integrating with their own system the APIs that the shoe suppliers publish. If the engineers find that working with the APIs is easy and even pleasant then everyone wins: the supplier gets their inventory exposed widely and the shoe reseller makes money providing a broader range of choices and satisfying its customers.
However, if the engineers’ user experience is frustrating then there’s a good chance they will look to other suppliers for their mirrored platform needs. If there are no other good options then they might give up and everyone loses. Therefore, it is paramount that the engineers setting up the initial connection between a data supplier and a data consumer have a gratifying user experience.
If you are a UX-pert or the owner of a suite of APIs then you have several opportunities for improving the open data user experience. Let’s break them up into two categories:
- Working with the data from the APIs
- Learning from the documentation on how to use the APIs.
Let’s actually start with the documentation.
Good UX for API Documentation Makes Sense
Because API documentation is typically presented on websites, common sense web usability applies. The pages should all be:
- Visually appealing: software engineers are people too!
- Responsive: you never know where an engineer will be when reading up on the documentation.
- Written in plain language: engineers speak many languages but your organization’s self-important jargon is not one of them.
- 508 compliant: build it in from the start and you will naturally integrate alternate channels of communication into your documentation.
Beyond these obvious points, software engineers have their own specific UX use cases. Pay attention to the information architecture and the interactive design. Group APIs logically in the navigation and hyperlink to other related APIs in the suite. Organize each documentation page similarly so as engineers get comfortable with one page they can easily move through another one.
Each documentation page should have these basic elements:
- Info on what the data is and why it’s valuable.
- The resource URL for getting the data. Make the URL clickable so the engineer can see results immediately.
- Search parameters for getting access to specific subsets of the data. Provide clickable examples.
- Return values described in plain language to help the engineer to anticipate what kind of results to expect.
- Details about any controlled vocabulary or taxonomy that the queries require or return. Bonus points for links to a taxonomy API.
- Notes regarding unique behavior about that specific API.
Build off of these basic starting points as you consider all of the facets of user experience.
Next up are the APIs themselves.
A Good API Experience So Everyone Wins
Ultimately, software such as a web page or a mobile app will be reading the data from the API. But initially engineers will be looking directly at the data as they start working with it. Make the calls intuitive and help them predict what the APIs will return.
Starting with the queries or request for data, name them logically. If you want to let shoe resellers find the amount of stock available in various shoe types, provide an API called count and give them a search parameter called shoe type. If the materials are key to your inventory (leather vs. mirrors) then let engineers do a search on shoe material as well. By standardizing the queries you empower engineers to quickly learn how to use the APIs and to experiment on their own all while keeping their interest and excitement.
Finally, return the data in a palatable form. JSON has become (arguably) the de facto format for returning web-related data. It’s lighter than XML and easy to ready by both humans and machines. Within the JSON, group the meta data separately from the data itself. Visual cues like these help engineers quickly understand what they’re looking at.
Pay attention to both the visual and interactive design when delivering the results. For example, organize the results logically. If the shoe reseller is making queries about available inventory, organizing the results by ascending shoe size helps them understand what they’re looking at.
Similarly, conform the data types. If the shoe supplier is providing the weight of a pair of shoes for shipping purposes, include both the pounds and ounces, even if ounces equals zero. If the ounce field is not sent, because it equals zero, then the engineer wonders what happened to the field and thinks there’s a data integrity error. Along those lines, make sure API and server errors are meaningful to help the engineer more quickly track down what’s gone wrong.
Not surprisingly, the earlier you start considering an engineer’s user experience the more likely the organization will integrate key elements of UX into the way they publish APIs. Push hard on the data owners and let them know that the UX of their API will make or break the success of their open data program and, ultimately, their organization’s goals.
