Dear Vendor: Can you do better with UI to API parity please?

We’re not asking for an API-first approach to development…I mean, that would be nice but at the very least we’d just like parity between UI and API options. In Higher Education, this is a constant point of frustration.

This topic causes issues for IT staff ALL. THE. TIME.

But…the most recent catalyst for this post was when my friend and colleague posted on LinkedIn about a particular issue related to Diversity, Equity and Inclusion (DEI). Specifically, the inability to set preferred pronouns (he/him/she/her/they/them etc) in certain services via API, even though users could set their own pronouns themselves via the UI.

This example is just one of many that cause frustration for higher education IT staff, especially those that administer cloud services. In larger organizations there’s frequent discussion of the need for an API first approach to development.

Understanding the API-First Approach to Building Products

By Janet Wagner Web APIs have been around for nearly 20 years, but it is only in the past few years that the concept of…

swagger.io

Larger organizations have to operate efficiently at scale. We have to build things programmatically, that run automatically without the need for manual intervention. There’s also an expectation for things like security, compliance, and consistency of approach.

The typical provisioning example

In Higher Education (or pretty much any organization these days), a central identity management system of record (SoR) is used as the central source of truth (ie: Active Directory, LDAP, ERP systems etc). User accounts are then provisioned automatically into multiple services based on eligibility.

The system of record is referenced for things like First Name, Last Name, Preferred Name, Pronouns, Title, Email Address and other important attributes about users. Some method of sync operation occurs to ensure that the everything is consistent across all services.

That means Jonathan Smith, who goes by Jon, using he/him as the preferred pronouns, should appear as that in all the different services. Should Jon have to do this manually everywhere? This is a common oversight when a consumer service is deployed in an enterprise environment. Users expect consistency, and don’t understand (and therefore blame the wrong people) when the IT support staff can’t handle this.

What about the reverse situation?

When something can be set by UI but not API, it’s bad. But, when something can only be set via API, that’s just as problematic.

In smaller organizations, they might not have a developer who can write code to work with APIs. So, if there’s settings that can only be set via API, the smaller organization is literally unable to actually configure the service. The best they can hope for, is another org with a developer will share some code that can be run without any developer-expertise…or are stuck paying a contractor/partner resource to do the development for them.

This issue is present for end-user configuration, where you need to set something on all users….AND where you just need to set a single option in an administration console for the service.

It’s not just user settings

Above I described a user specific situation regarding name information and pronouns. But the same consistency can be expected for other things too.

Maybe you want all your storage & collaboration platforms (Google Drive, Dropbox, Box etc) to have the same sharing restrictions so you can avoid unintended data loss or exposure. So you want to set an administrative environment-wide option to prevent anything from being shared “publicly.”

Or maybe it’s something as simple as wanting to set the “support contact information” as the same thing in all your services, so your users get consistent information when they click the in-app help/support icon.

Setting end-user attributes AND administrative settings, plus all the things in between via API or UI is vital.

Discovering the lack of parity

When there’s a UI setting it’s easy to see how people can discover that there’s no associated API for it. Because someone will notice a new checkbox, field, or option…and then IT will take a look to make sure it’s set correctly (or at least a default option is enforced) for all users.

On the flip side, when there is only an API setting, it takes research to discover it. You can’t just stumble upon a new API while using the service/software. It’s more likely you’ll see a new API option when checking out the API documentation for another reason.

So, please, vendors….don’t make us dig for this stuff.

Better late than never

New technology startups might subscribe to the API-first approach, and therefore never find themselves with UI parity problems. However, existing or established vendor services are prevalent across Higher Education (and other industries of course). Nobody expects the vendors to be able to pivot their development approach overnight or for them to refactor their entire codebase.

What we can expect is that any new features or options are handled consistently. At least then, the parity problem doesn’t get any worse.