Helping developers understand role emulation

The Challenge

This was a long running project which we advocated for as one of our "sand" projects.

We faced a significant hurdle in refining its developer experience workflow.
At the heart of this challenge was the code, try, and test loop, an essential part of the development process.

While we had successfully integrated GraphiQL, a visual explorer for our APIs which empowered developers - a crucial aspect remained difficult:
clearly communicating to developers which role they were emulating when testing their API through the interface.

This challenge had multiple parts:

1. Role emulation had complex logic about what role was applied when.
   • Some of this logic had a precedence order in terms of which rule was applied first.
   • Because of the complexity, the bar for error was high in testing.
2. If developers deleted the admin token from their headers, they'd have to navigate back to the dashboard to retrieve it - a cumbersome process that disrupted their workflow and led to confusion.

These issues combined to create a less-than-ideal user experience, particularly for developers new to the platform.

Technical Implementation

The complexity of the challenge stemmed from the various scenarios that determined role emulation during the try-and-test stages.

The emulation was based on the request headers sent in the API request, with several possible configurations:

1. If a JWT token was defined:
   • The role specified in the JWT token would be used for the user in the editor.
2. If the x-hasura-admin token was defined:
   • User automatically assigned to an admin role.
   • User's would be able to emulate any role with the x-hasura-role header.
3. If both JWT and admin token defined:
   • The admin token would take precedence.
4. If neither JWT nor admin token defined (or were invalid):
   • Users would be restricted to an anonymous or unsigned-in user role.

This complexity made it difficult for developers to keep track of their current emulated role, leading to confusion and potential errors in API testing.

Solutions

We approached this challenge with two solutions, each building upon the other:

Good: Role Illustration

The initial solution focused on clearly illustrating to users which role they were currently using.
This approach was particularly important given the technical limitations of Hasura v2.

The main goal was to provide visual cues that would inform users about their current emulation scenario.
This helped developers understand which role they were emulating at any given time, reducing confusion and improving the overall testing experience.

Expand

Expand

Better: Role Abstraction

Expand

With the advent of Hasura v3+, we were able to implement a more user-friendly solution by abstracting away much of the role emulation complexity into a simple role selector.

This approach offered several benefits:

1. Simplified user interface
2. Reduced cognitive load for developers
3. Eliminated the need to manually manage tokens and headers
4. Provided a more intuitive experience for role switching during API testing

--

Early testing of this feature showed promising results.
Users found the role picker much more intuitive and easier to use compared to the previous method of managing roles through headers.