What Building an API Taught Me About Developer Experience

I thought I was testing an API.

I was actually testing the developer experience.

I built a small Express API with two endpoints:

GET  /hello
POST /hello

The API itself was intentionally simple.

What interested me was what happened when I stopped looking at it as the person who built it and started using it as a developer discovering the project for the first time.

I didn't just ask:

"Does the code work?"

I started asking:

"Can another developer actually use this without getting stuck?"

That changed the way I looked at the project.

I started with the README

The README included the usual setup instructions:

npm install
npm run dev

Looks fine, right?

Except there was a problem.

The project didn't actually have a dev script.

The documentation was telling developers to run a command that the project couldn't execute.

That was my first reminder:

Documentation is a promise.

If I tell a developer to run a command, that command needs to work.

I fixed the issue by adding tsx and configuring the development script:

{
  "scripts": {
    "dev": "tsx watch src/server.ts",
    "test": "vitest"
  }
}

After that:

npm run dev

successfully started the server.

A small fix, but an important lesson:

A documentation review isn't complete until the documented steps have actually been executed.

Then I discovered a portability problem

Next, I tested the POST request example from Windows PowerShell.

My original example used Unix-style curl syntax.

It didn't behave as expected.

The API wasn't broken.

My documentation was.

I had written an example without considering the environment in which another developer might run it.

I replaced it with a PowerShell-compatible example:

Invoke-RestMethod -Uri "http://localhost:3000/hello" -Method Post -ContentType "application/json" -Body '{"name":"Virginia"}'

This worked.

The API returned:

Hello, Virginia!

That led to another important lesson:

A code example isn't finished when it looks correct. It's finished when a developer can copy it, run it, and get the expected result.

That's an important distinction in developer documentation.

I tested the failure path too

Developers don't only follow the happy path.

They make mistakes.

They send incomplete requests.

They misunderstand parameters.

They use the wrong data type.

So I intentionally sent:

{}

The API responded with:

{
  "error": "Name is required"
}

That's useful API behavior.

The developer immediately knows what went wrong and what needs to be fixed.

They don't have to inspect the source code.

They don't have to guess.

They don't necessarily have to leave the terminal and search through documentation.

The API itself provides useful guidance.

And that made me think about something important:

Error messages are part of the developer experience too.

Tests became part of the API contract

I added automated tests covering:

• GET /hello
• A successful POST /hello
• An invalid name
• A missing name

The result:

Test Files  1 passed
Tests       4 passed

These tests aren't only there to catch bugs.

They also describe the behavior the API is expected to provide.

In that sense, tests become a form of executable documentation.

If the API behavior changes unexpectedly, the tests can expose that change.

That gives developers and documentation authors something concrete to rely on.

I documented the friction

After going through the developer journey, I created two additional documents.

DEVEX-AUDIT.md

This documents:

• The developer journey I tested
• The friction points I discovered
• Why the problems happened
• What I changed
• How I verified the fixes

TROUBLESHOOTING.md

This documents the actual problems encountered during setup and API usage, along with their solutions.

This distinction matters.

I wasn't writing troubleshooting content based on hypothetical problems.

I was documenting problems I had actually encountered while using the project.

That made the documentation much more grounded.

The workflow changed

The project eventually became this loop:

Build
  ↓
Document
  ↓
Follow the documentation
  ↓
Find friction
  ↓
Investigate
  ↓
Fix
  ↓
Test
  ↓
Update documentation
  ↓
Verify again

And this is probably the biggest lesson I've taken from the exercise.

Documentation shouldn't be treated as a final step after development.

It should be part of the development and feedback loop.

Developer Experience is bigger than documentation

A developer experience isn't just a documentation website.

It's the entire journey between:

"I found this project."

and:

"I successfully built something with it."

That journey can include:

• Installation
• Environment setup
• Commands
• APIs
• Code examples
• Error messages
• Tests
• Troubleshooting
• Documentation
• Tooling

Every one of those can either create momentum or create friction.

A beautiful README doesn't help if the first command fails.

A technically correct example doesn't help if it doesn't work in the developer's environment.

And an API that returns unclear errors creates friction even when the documentation is excellent.

Everything is connected.

The question I'm asking now

Instead of asking:

"Did I document this?"

I'm starting to ask:

"Can a developer successfully use this?"

That's a much better standard.

It pushes documentation beyond simply writing content and into:

building → testing → observing → improving.

And it gives you a way to collect evidence.

You can test the setup.

You can test the examples.

You can test the API behavior.

You can test the failure paths.

You can verify that the documentation reflects reality.

What I'm taking forward

This was a small API.

But the exercise taught me something much bigger.

I found a missing development command.

I found a platform-specific documentation issue.

I tested API validation.

I improved the error experience.

I added automated tests.

I created troubleshooting documentation.

And then I followed the documentation again to verify that the experience actually worked.

That changed how I think about Developer Experience.

Good developer documentation isn't simply about explaining how a system works.

It's about helping developers make progress.

And sometimes the best way to find out whether your documentation does that is to become the developer who has to use it.

Build it. Use it. Break it. Document it. Improve it.