Benefits of using an API are mostly seen if an API make it easy for a developer to understand and reuse its functions that indicates usability of an API. An aspect that plays a major role in the decision of whether an API will be used is the usability of an API. APIs can have various usability issues that can be generated due to design, resources, and technical constraints.

Design is not done once. It’s something that goes on and on. Customer requirements come from the consumers and internally architecture might change causing changes in the API. Of course in ideal world internal changes do not mandate API changes, but it’s wise to expect API to be quite volatile at least in the beginning. Designer should have tools to evaluate given design and adjust that to feature requirements. API usability is one of the corner stones of any API. If it’s not usable, it is not used. If it’s hard to use, some will ditch it and look for alternative. If it’s good, you have better chance to get more hapy customers.

Evaluation tools

Designers can evaluate the usability of an API through different methods such as API peer review, API profile dimensions, Cognitive Dimensions (CDs) Framework (Clarke), and text analysis. Building an API gets more complex when requirements continually evolve and there are time constraints. This constant change is reality and should be anticipated. The API designer should be using selected evaluation stack in the background to guide his/her work. Having just API Design Guide (important as well) is not enough.

Following just the API Design Guide can result to "valid APIs", but have serious usability issues.

The Cognitive Dimensions framework caught me attention today. The peer review is something that any Design-First API development company will do. Provide mockup API for selected or all customers for feedback and review before implementation. What happens before that is interesting. Any kind of shit should not be pushed to customer review. Experienced API designers rarely produce shitty designs, but sometimes the information on use cases has been inadequate. The designer simply did not have enough information to fit the design to market needs. Simple review process with mockup API will get you the feedback and you can fix the design before resource intensive implementation.

But the interesting question is what happens in the head of the API designer before the first version of API design is shown to anyone else. This is where battle tested design frameworks can help and remove the need to reinvent the wheel again. In the below illustration area of interest is the time and operations between the two dotted lines.

I claim that the role of API Design Guides reduces as the process goes forward. In the beginning it defines the overall options and limitations, but the further the process goes, the more it’s about the little things in the API design that matters. And those little things are about usability, not only the technical guides often found in API Design Guides. Great API designer “sees and feels” beyound the API Design Guide.

The Cognitive Dimensions (CDs) framework

You can usae the CDs without modifying the Cognitive Dimensions framework to enable to use the framework to describe and measure API usability. CDs was not initially designed for that and thus adjustments are needed.

In API design phase you should write code against the design to see how different developers solve tasks with it. Analysing the solutions with help of the CDs you’ll have systematic method to evaluate your design. Having systematic method is important because it increases the reliability of the process and is no longer person related. Eg the designer is not working on gut feeling and experience only. In many cases, a single issue can be described from the perspective of more than one dimension. The advantage of this approach is that it encourages teams to consider multiple solutions for resolving problems.

Some more to read from 100 Days DX