Trigger walks through their document refactoring effort.
Let’s take a step back and consider what is critical when developing a web API:
- Documentation for end users to know how to consume your services.
- Consistent and reliable output so you don’t break client applications relying on your services.
This post is about 5 developer frameworks/APIs/tools/platforms that give great FUE, my fav 5 inspirations of the now.
They all do something awesome: They get you to request/response, action/reaction, bell/salivation, to their own personal Hello World as fast as possible. They constrain TTFHW (Time To First Hello World), if only in a test environment, to get you to the I TOLD YOU TO DO SOMETHING AND YOU DID IT moment, that moment of I SEE WHAT YOU DID THERE.
But then why any language feature at all? Why isn’t assembler good enough for everyone? Or C? Or C++?
Turns out the answer is “human frailty”. Or put a different way, the process of cognition depends on very limited amounts of short-term stack space in our wetware, and computing languages are about making the computer hospitable for the human, not about telling the system what to do. Our tradeoffs in languages would look much different if we could all easily recall 20 or 30 things at a time instead of 5-10. Languages are tools for freeing creative people from registers and stacks and heaps and memory management and all the rest; all while trying to keep the creative process grounded in the reality that it’s memory words in a Von Neumann architecture; without that grounding we’d end up too disconnected from the system to deliver anything practical.
“I often joke that API hackathons are basically API usability testing days, the best opportunity for API teams to see first-hand how developers use their APIs and what problems they ran into - so when I was invited to an AT&T API day, I assumed it was another hackathon. But in fact, it was a formal “API Usability Day”, structured and designed to find out what AT&T needs to do to improve their developer experience.”
“One of my own suggestions to them was for them to hold an internal hackathon using their competitor’s APIs - so they could see for themselves how their experiences differed and learn from them”
In which Mark Nottingham suggests it’s better to choose either JSON or XML than to choose both.
“When you’re designing HTTP APIs, you need to keep a lot of concerns in mind. Stealing a page from XP, let’s look at some possible personas and their user stories for HTTP-based APIs:”