API Design Matters - ACM Queue
Old!
"Good APIs are Hard

We all recognize a good API when we get to use one. Good APIs are a joy to use. They work without friction and almost disappear from sight: the right call for a particular job is available at just the right time, can be found and memorized easily, is well documented, has an interface that is intuitive to use, and deals correctly with boundary conditions.

So, why are there so many bad APIs around? The prime reason is that, for every way to design an API correctly, there are usually dozens of ways to design it incorrectly. Simply put, it is very easy to create a bad API and rather difficult to create a good one. Even minor and quite innocent design flaws have a tendency to get magnified out of all proportion because APIs are provided once, but are called many times. If a design flaw results in awkward or inefficient code, the resulting problems show up at every point the API is called. In addition, separate design flaws that in isolation are minor can interact with each other in surprisingly damaging ways and quickly lead to a huge amount of collateral damage.

Bad APIs are Easy

Before I go on, let me show you by example how seemingly innocuous design choices can have far-reaching ramifications. This example, which I came across in my day-to-day work, nicely illustrates the consequences of bad design. (Literally hundreds of similar examples can be found in virtually every platform; my intent is not to single out .NET in particular.)

"
apis  design 
17 hours ago
Introduction · Pact
"What is Pact?

The Pact family of frameworks provide support for Consumer Driven Contracts testing.

Consumer Driven Contracts

A Contract is a collection of agreements between a client (Consumer) and an API (Provider) that describes the interactions that can take place between them.

Consumer Driven Contracts is a pattern that drives the development of the Provider from its Consumer's point of view. It is TDD for services.

Pact is a testing tool that helps you write Contracts, and guarantees those Contracts are satisfied."
apis  contracts  testing  framework 
17 hours ago
Fifteen Years of RedMonk – tecosystems
via Pinboard (network items for earth2marsh)
IFTTT  Feedly 
10 days ago
What I've Learned...with Steve Willmott of RedHat - OpenChannel
"OC: Does that mean all API programs and ecosystems have to be monetized?

Steve: People assume that for an API to be valuable you have to be monetizing the API itself. Only about 20% of our customers do that. The rest are successful without monetizing their API. That means they’re driving supporting partners who are driving business to the company’s core business or they’re adding value to customers allowing them to integrate with the API and do more business with the company."
steve_willmott  apis  monetization 
12 days ago
302 Found
via Pinboard (network items for earth2marsh)
IFTTT  Feedly 
18 days ago
The Interpreter
“Where do you get your ideas?” is by far the most common question we get from friends, colleagues, and readers about our work here at The Times. So we thought we’d take this newsletter to talk a bit about how we decide what to write about.
The process isn’t precisely the same for both of us. Amanda’s interests tend a little bit more toward psychology, norms, and group behavior, while Max often looks first to macro-level stories about international relations. And of course we get a lot of our ideas from our editors, who often suggest stories to us.
But there are a few big things that we both do ourselves to shape the Interpreter’s coverage.
Ask the ‘Big, Dumb Questions’
When there is a big news story, we try to think about what big questions many people might have but be too embarrassed to ask.
For instance, on several occasions, smart (but perhaps stretched-thin) friends have asked us, with great embarrassment, to explain the Israeli-Palestinian conflict. It would be easy to offer a glib answer, or to dismiss that as a silly question only an ignorant uninformed person would ask.
But it’s actually neither silly to ask nor easy to answer. Different parties to that conflict tell different stories about the reasons for the violence, its historical roots, and what it would take to end it. And starting from the most basic “what is going on?” level of analysis is a good way to spot some of the dynamics that have made the conflict so difficult to resolve, but that often go unmentioned in stories about individual attacks or negotiations.
The same is true of conceptual questions like “what is populism?” Looking at that broadly, across many different countries, has given us a lens for understanding and explaining political events around the world. And it has also helped us notice warning signs in countries that have not yet had a populist surge, but seem to be at risk for one.
Look for Patterns
We realize that saying we look for patterns kind of makes it sound like the walls of Interpreter HQ are covered in Carrie Mathison-style diagrams made of photos and string.
But we don’t mean patterns in a conspiratorial, “it’s allll connected” sense. Looking for a few big ideas that play out in different countries can be a way to find the deeper dynamics that drive world events.
And knowing those patterns also makes it easier for us to jump on big stories and get up to speed quickly.
For instance, we know that when countries transition from dictatorship to democracy, they tend to have a period of instability, when old alliances and institutions have been shattered but new ones have not yet taken hold. Understanding that pattern has been a starting point for us in writing about stories in Mexico, Myanmar, and a number of former Soviet countries.
And we know that corruption works in similar ways around the world. Although the specifics vary by culture and system, research has shown that there are broad similarities in how corruption becomes endemic within particular countries or institutions, what makes it so difficult to fix, and how it can damage the institutions in which it takes hold.
(Also, in the interest of full disclosure, we have in fact gone Full Mathison on our walls and we don’t care who knows it.)
Just Ask
This one seems obvious, but can be the easiest one to overlook when things are busy and confusing: ask. We try to make a point of asking what other people — our sources, experts, researchers, and friends — think we should cover.
Sometimes that means calling up smart people and asking questions until they get sick of us and start making excuses to get away. After the Brexit vote and the 2016 general election, Amanda spent days just making calls to the most knowledgeable researchers she could get on the phone, asking them what they thought the most important things to understand about those events were. Those conversations weren’t in service of a particular story, but they have informed her coverage ever since.
Likewise, when we we travel, we try to finish interviews by asking people if there’s anything we haven’t asked about but they want to discuss. That’s often the question that gets the best answers, because it’s when we find out what we didn’t even know to ask about. It has helped us find sources, stories, and places to go.
Read, Watch, and Listen, Widely and Constantly
This is one you can probably guess from our recurring “What We’re Reading” section. But it’s probably the most important.
We are constant consumers of other people’s work. We read magazines and newspapers, academic articles, experts on Twitter, non-experts on Twitter, books, pamphlets, weird propaganda, podcasts, TV shows, texts from our moms...you name it, we’re probably devouring it.
Not all of that is work. Sometimes a book is just a book. But we’ve got eclectic tastes, and we’re always thinking about whether unusual sources might somehow inform our writing. (That’s how you get the occasional Interpreter newsletter about Harry Potter books or prestige TV shows.)
ideas  creativity  process  planning 
18 days ago
Questions for our first 1:1 | Lara Hogan
via Pinboard (network items for earth2marsh)
IFTTT  Feedly 
19 days ago
Manager handoffs | Lara Hogan
via Pinboard (network items for earth2marsh)
IFTTT  Feedly 
19 days ago
When did the golden age of The Simpsons end?
via Pinboard (network items for earth2marsh)
IFTTT  Feedly 
21 days ago
HEML
via Pinboard (network items for earth2marsh)
IFTTT  Feedly 
21 days ago
302 Found
via Pinboard (network items for earth2marsh)
IFTTT  Feedly 
23 days ago
Why can't they just...? | Lara Hogan
via Pinboard (network items for earth2marsh)
IFTTT  Feedly 
23 days ago
ongoing by Tim Bray · Working at Amazon
via Pinboard (network items for earth2marsh)
IFTTT  Feedly 
23 days ago
The Alumni Factor
Via How to Raise an Adult
"The Alumni Factor has three primary goals:

To give prospective students and their parents a more empowering, performance-based method of measuring and choosing colleges.
To give colleges and universities an objective assessment of their performance, based on the actual results of and input from their own alumni, that can be compared to other relevant colleges and universities. This is often difficult for an individual school to achieve on its own, but is essential to its improvement.
To give college alumni themselves a better perspective on the role their college played in their personal development and in the development of others, and how that compares to other colleges. This is interesting and entertaining for alumni, but it also helps improve colleges, since alumni are often active and influential voices as colleges set their improvement agendas.
The Alumni Factor Vision:

To become the most authoritative and trusted source of data and insights into the actual performance of colleges and universities."
colleges  universities  college  university  lives  education  parenting  alumni 
23 days ago
Colleges That Change Lives – Changing Lives. One Student At A Time.
From How to Raise an Adult
"CTCL is dedicated to the advancement and support of a student-centered college search process.

The Colleges That Change Lives, Inc. (CTCL) story begins in 1996 when a book by the same name — Colleges That Change Lives — was published by retired New York Times education editor and journalist Loren Pope. A longtime student advocate and independent college counselor, Mr. Pope sought to change the way people thought about colleges by dispelling popularly held myths and challenging the conventional wisdom about college choice. His groundbreaking ideals were welcomed by students and the college counseling community alike. As a result, many of the colleges featured in the book began working together to further promote this philosophy of a student-centered college search. In 1998 the CTCL organization was formally organized, independent of Mr. Pope (although with his blessing) and his publisher.

Today, CTCL is regarded as a leading advocate on the subject of higher education access and college choice. In additional to the resources available through this web site, CTCL offers printed materials and numerous outreach efforts to students, families, college counselors, schools and education agencies. Additionally, CTCL supports those in college counseling roles who ascribe to a similar philosophy and are working to help students frame their college search beyond the ratings and rankings.

Furthermore, CTCL was founded on a philosophy of building the knowledge, character and values of young people by introducing them to a personalized and transformative collegiate experience. Although the member colleges approach this challenge with varying perspectives, institutional missions, and pedagogical strategies, a student-centered mission is common to all campuses. As an organization, CTCL will provide information and the opportunity to pursue a best-fit college to all students regardless of race, color, religion (creed), national origin (ancestry), sex, gender, sexual orientation, age, socioeconomic status, political affiliation, marital status, disability, military status, or any other means by which a student could be discriminated."
colleges  universities  college  university  lives  education  parenting 
23 days ago
Making IT Culture Change Work
"No, unfortunately not at the time of this writing. For teams looking to try using OpenAPI documents as artifacts that proceed through a governance process, I would recommend giving Swaggerhub a look. Or possibly Stoplight.io. Neither appears to support configuration of editorial and approval workflows. However, many of the other features (issue tracking, source control, style validation) are present.

I may be missing some alternatives. So many of the search results for “API lifecycle management” are about client credential issuance and request throttling. Or, if the tool does address design time considerations, the goal is for a single user, or team, to generate a mocks.

When ‘reality checking’ our lifecycle approach, I repeatedly referenced commercial web publishing workflows. In that space, an item from any number of creators (usually an article, but sometimes a video essay or listicle) proceeds through a series of checks. Along the way, revisions occur which may send the item back for re-evaluation. That model resonated strongly with our need to involve numerous stakeholder groups (product, security, risk, architecture, etc.) on a design.

"
apis  governance  change  lifecycle 
24 days ago
Cracking the Code of Change
The brutal fact is that about 70% of all change initiatives fail.
change  management  culture  hbr 
24 days ago
Copy lines containing "xyz" - Technical Support - Sublime Forum copy lines containing
"These are the steps you would need to accomplish it:

You could use Ctrl+D to select all "xyz" in your document or use the search function to select all of them.
After that press Ctrl+L to expand all selections to the whole lines.
You might need to use Shift+Left to move the cursors back to the selected lines.
Copy all the lines with Ctrl+C
Paste anywher Ctrl+V"
sublime  tricks  copy  cut  lines 
26 days ago
Twitter
Looking forward to APIStrat next week! LMK if you'll be there—it's nice to meet IRL sometimes. :)
from twitter
27 days ago
formatting numbers as 1st 2nd - Google Groups
=A1&MID("thstndrdth",MIN(9,2*RIGHT(A1)*(MOD(A1-11,100)>2)+1),2)
ordinal  ordinality  excel  sheets  google:sheets  formula 
29 days ago
« earlier      
!to_read addon advertising advice ajax amazon analytics android api apis apps architecture art article audio authentication backup blog book bookmarklet books browser business change chrome code cognition collaboration communication community comparison cool copyright creativity css culture data design development diy documentation economics editor education elearning email environment extension extensions facebook family favorite feedly finance firefox flash flickr food for free freeware fun funny future games generator github google graphics green hack hacks hardware health history home howto html http humor identity ifttt iftttfeedly iftttgr images information innovation inspiration interesting interface internet javascript jquery kids language later law learning library life linux list lists lsi mac management map mapping maps marketing math media metrics microsoft mobile money mp3 music network online opensource organization osx parenting patterns pdf performance philosophy phone photo photography photos php plugin plugins politics presentation privacy productivity productmanagement programming psychology read recipes reference research resource resources rest rss ruby sanfrancisco saved science script search security seo service sharing shopping social software startup startups statistics storage strategy sustainability teaching technique technology testing text time tips tool tools tracking travel trends tutorial twitter ubuntu ui usa usability usb useful utilities utility ux via:pocket video visualization web webdesign webdev wiki windows word wordpress writing xp youtube

Copy this bookmark:



description:


tags: