New technologies emerge one after another, and what remains after the wave fades are some classic design ideas.

On the front end, there’s jQuery, which used to be well known, and more recently, vue.js. There are many reasons why both are popular, but one thing they have in common is the elegance of their API design.

So this time I want to talk about a big topic — the art of API design.

Discuss the domain of content

This article is not a jQuery API appreciation, and when we talk about API design, we are not limited to discussing how a framework should design exposed methods. As the basic collaborative means of dividing and dividing the complex logic of the program world, the design of the generalized API touches every aspect of our daily development.

The most common API exposure approaches are Function Signiture and Attributes; When it comes to front-end IO, we need to pay attention to the data structure of the communication interface (JSON Schema). If there is asynchronous communication, there is also the question of how Events or messages are designed; Even when you rely on a Package, the Package name itself is the interface. Have you ever come across a weird Package name and made fun of it?

In short, “API design” isn’t just about the designer of the framework or library, it’s about every developer.

grasp

Standard: morphology and grammar

A high-level language is not much different from a natural language (English), so the correct use of morphology and grammar is a programmer’s basic literacy. This is especially important when it comes to API code that users call.

But in fact, due to the generally poor command of English in Asia… So the reality is not good — if proper lexical and grammatical usage were the threshold for compliance, many apis would fall short.

The correct spelling

// json
[
  {
    "shopBottom": {
      "isTmall": "false",
      "shopLevel": "916",
      "shopLeveImg": "//xxx.jpg"
    }
  }
]
Copy the code

Accurate terminology

As we know, the meanings of Chinese and English words do not correspond one by one. Sometimes a Chinese meaning can be explained by different English words, so we need to choose appropriate and accurate words to describe it.

For example, “message” in Chinese can be translated into “message”, “notification”, “news” and so on. Although these different words can all mean “message,” there are subtle differences in their usage and context:

• Message: Generally refers to the message communicated between two parties. It is the content carrier. And they often come in pairs. Such as postMessage() and receiveMessage().
• Notification: Often used for short notifications, and now even for iOS/Android notifications. Such as new NotificationManager().
• News: A longer news message, heavier than notification. Such as getTopNews ().
• Feed: A word that has been around since the days of RSS subscriptions, RSS is dying out, but the word feed is being used in more ways than one. Its meaning is understood but not expressed. Such as fetchWeitaoFeeds (). So, even if the Chinese meaning is roughly the same, use the exact words so that the reader can more easily understand the API’s role and context.

There’s a positive case for React. React has two methods called:

React.createClass({
  getDefaultProps: function() {
    // return a dictionary
  },
  getInitialState: function() {
    // return a dictionary either
  }
});
Copy the code

They are used to define the initialization component information and return the same type of value. However, the method name is default and initial respectively. Why not use one method?

The reason has to do with the React mechanism:

• Props refers to an Element’s properties, either without an attribute value that was later assigned to it, or with a default value that was later overridden. So this behavior, default is a reasonable modifier.
• State is a specific state in the Component state machine, and since it is described as a state machine, the relationship between states is switched. So for the initial state, I’m going to use initial. This small detail gives you a glimpse of the React mechanism itself, and it shows the wisdom of the API designers.

In addition, I recently came across a set of event apis like this:

// event name 1
page.emit('pageShowModal');

// event name 2
page.emit('pageCloseModal');

Copy the code

These two events are clearly a pair of positive and antisense actions. In the case above, show is used for “show window” and close is used for “close window”, which is a very intuitive literal translation. Instead, the words should come in pairs: show & hide, open & close.

Therefore, it must be emphasized here that positive and antonyms appearing in pairs should not be mixed. Other words that often come in pairs in the programming world are:

• in & out
• on & off
• previous & next
• forward & backward
• success & failure
• …

In short, we can try to expand our English vocabulary and use appropriate words, which will help us to accurately describe the API.

Pay attention to singular and plural

var shopItems = [ // ... ] ; export function getShopItems() { // return an array } // fail export function getShopItem() { // unless you really return a non-array }Copy the code

class MarketFloor extends Component {
  state = {
    item: [
      {}
    ]
  };
}
Copy the code

// fail
var EVENT_MAPS = {
  MODAL_WILL_SHOW: 'modalWillShow',
  MODAL_WILL_HIDE: 'modalWillHide',
  // ...
};
Copy the code

Don’t get the part of speech wrong

Another silly mistake to make is to confuse parts of speech, i.e., nouns, verbs, adjectives…

asyncFunc({
  success: function() {},
  fail: function() {}
});
Copy the code

Success is a very popular word in the programming world, but some students may get it confused and use it as a verb. In the above cases, the parts of speech of the paired words should be the same. Here they should be written succeed and fail. Of course, in this context, it’s best to follow convention and use the noun combination success and failure.

The whole part of speech of this pair is as follows:

• Noun: success, failure
• V. Succeed, fail
• Adj. Successful, failed
• Do you want to do STH successfully?

Note that if some words do not have corresponding parts of speech, consider adopting other forms to achieve the same meaning.

So even though most of us know that methods are named with verbs, attributes are named with nouns, and Boolean types are named with adjectives (or their equivalent), unfamiliarity with the parts of speech of certain words can lead to the final API naming problem, which can be awkward.

Handle abbreviations

// before
export function getDomNode() {}

// after
export function getDOMNode() {}

Copy the code

Use the right tenses and voice

Because we generally call an API like “call an instruction,” syntactically, a function name is imperative and tenses use the present simple tense.

But in some cases, we need to use other tenses (continuous, past, future). For example, when we talk about life cycles, event nodes.

In some component systems, life cycles are definitely involved. Let’s look at how the React API is designed:

export function componentWillMount() {}
export function componentDidMount() {}
export function componentWillUpdate() {}
export function componentDidUpdate() {}
export function componentWillUnmount() {}

Copy the code

React divides several key lifecycle nodes (mount, update, unmount…). , describing these node fragments in the future and past tense, exposing the API. React uses componentDidMount instead of componentMounted. React uses componentDidMount instead of componentMounted. React uses componentDidMount instead of componentMounted.

Similarly, we need to consider using appropriate tenses when designing our event apis, especially if we want to provide a fine-grained event slice. Or, introduce prepositions like before and after to simplify:

// will render
Component.on('beforeRender', function() {});

// now rendering
Component.on('rendering', function() {});

// has rendered
Component.on('afterRender', function() {});

Copy the code

The other aspect is about voice, that is, the choice of active voice and passive voice. The best rule of thumb is to avoid the passive voice whenever possible. Because passive voice can seem confusing and unintuitive, we’re going to convert the API for passive voice to active voice.

Written in code, it looks like this:

// passive voice, make me confused
object.beDoneSomethingBy(subject);

// active voice, much more clear now
subject.doSomething(object);
Copy the code

Advanced: Semantics and usability

Single responsibility

Single responsibility is a well-known principle in software engineering. However, it is easier to know than to carry out. On the one hand, it may be difficult to divide “responsibility” in specific business logic, and on the other hand, some students have not formed the habit of implementing this principle.

From small function-level apis to large packages, it is important to maintain a single core responsibility.

// fail
component.fetchDataAndRender(url, template);

// good
var data = component.fetchData(url);
component.render(data, template);
Copy the code

As above, separate out the two independent things that are mixed up in a big blob of functions to ensure a single function level responsibility.

Further, (assuming) fetchData itself is better encapsulated by another class, split the original Component class (Component) and separate out fetching responsibilities that do not belong to it:

class DataManager {
  fetchData(url) {}
}

class Component {
  constructor() {
    this.dataManager = new DataManager();
  }
  render(data, template) {}
}

// more code, less responsibility
var data = component.dataManager.fetchData(url);
component.render(data, template);
Copy the code

The same is true at the file level, where only one class is written to a file, keeping the responsibility of the file simple (this is a natural rule for many languages, of course).

Finally, depending on the specific degree of business correlation, it is decided whether to make a package from a cluster of files or split into multiple files.

Avoid side effects

// return x.x.x.1 while call it once
this.context.getSPM();

// return x.x.x.2 while call it twice
this.context.getSPM();
Copy the code

var spm1 = this.context.getSPM();
var spm2 = this.context.getSPM();
var spm3 = this.context.getSPM();

Copy the code

Design function parameters properly

For a Function, the Function Signature is more important than the Function itself. Function name, parameter setting, return value type, these three elements constitute the complete function signature. Among them, parameter setting is the most frequent and most concerned part for users.

So how do you elegantly design the entry parameters of a function? My understanding is as follows:

Optimize parameter order. The more relevant the parameter is, the more advanced it will be.

This makes sense, the more relevant the parameter, the more important it is to come first. There are two more implications of this, namely, the postponement of omitted parameters and the setting of default values for omitted parameters. For some languages (such as C++), if you want to omit an argument in a call, you must define a default value for it, and arguments with default values must be postpended. This is mandatory at the compile level. For other flexible languages (such as JS), it is also a best practice to postposition the saving arguments.

// bad
function renderPage(pageIndex, pageData) {}

renderPage(0, {});
renderPage(1, {});

// good
function renderPage(pageData, pageIndex = 0) {}

renderPage({});
renderPage({}, 1);
Copy the code

The second point is to control the number of parameters. The user cannot remember too many entry parameters, so parameters are omitted if they can be omitted, or further, parameters of the same type are merged.

Merging parameters is particularly common in JS because of the ease with which composite data structures such as Object can be created. It is common to package many configuration items into a single configuration object:

// traditional
$.ajax(url, params, success);

// or
$.ajax({
  url,
  params,
  success,
  failure
});
Copy the code

The benefits of this are:

• The user still needs to remember the parameter names, but does not need to care about the order of the parameters.
• Don’t worry about long parameter lists. When parameters are merged into a dictionary structure, you can add as many parameters as you want without worrying about which ones need to be left behind.

Of course, everything has pros and cons, because of the lack of order, it is impossible to highlight which is the most core parameter information; In addition, setting the default values of the parameters can be more tedious than the parameter list form. Therefore, you need to design function parameters in an optimal way, for the same purpose: ease of use.

Use function overloading wisely

Element getElementById(String: id)

HTMLCollection getElementsByClassName(String: names)

HTMLCollection getElementsByTagName(String: name)
Copy the code

// fail
function getElementsBy(byWhat, name) {
  switch(byWhat) {
    case 'className':
      // ...
    case 'tagName':
      // ...
  }
}

getElementsBy('tagName', name);
getElementsBy('className', name);
Copy the code

// get elements by tag-name by default
HTMLCollection getElements(String: name)

// if you add a flag, it goes by class-name
HTMLCollection getElements(String: name, Boolean: byClassName)

Copy the code

Module handleModules(Module: module)

Collection<Module> handleModules(Collection<Module>: modules)

Copy the code

Make the return value predictable

Functions are easy to use in two ways: entry and exit. This section covers the exit: the function return value.

For getter-type functions, the immediate purpose of the call is to get the return value. So we want to keep the type of the return value consistent with the expectation of the function name.

// expect 'a.b.c.d'
function getSPMInString() {

  // fail
  return {
    a, b, c, d
  };
}
Copy the code

In this regard, the new ES2015 feature “deconstruction assignment” should be used with caution.

For setter-type functions, the call is expected to execute a series of instructions and then achieve some side effects, such as saving files, overwriting variable values, and so on. So most of the time we chose to return undefined/void — not always the best choice.

Recall that when we call an operating system command, the system always returns an “exit code”, which allows us to know how the execution of the system command turned out, without having to do anything else to verify that the operation actually worked. Therefore, creating such a return value style may increase robustness to some extent.

Another option is to have the setter API always return this. Return this to create a style of “chaining” to simplify code and increase readability:

$('div')
  .attr('foo', 'bar')
  .data('hello', 'world')
  .on('click', function() {});

Copy the code

One final anomaly is functions that execute asynchronously. Due to the asynchronous nature, callback can only be used to continue the operation of a value that takes some time to return. It’s especially necessary to wrap them with promises. Return a Promise for all asynchronous operations, making the overall API style more predictable.

Curing glossary

page.emit('pageRenderRow', {
  index: this.props.index,
  modList: moduleList
});
Copy the code

Follow a consistent API style

This is kind of a review section. Many sections of morphology, syntax, and semantics all point to the same point: consistency.

Consistency minimizes information entropy.

Okay, that’s either a quote or I just made it up. All in all, consistent performance significantly reduces the user’s learning costs and produces accurate expectations of the API.

In terms of morphology, refine the glossary, keep the same words globally, avoid the emergence of different but similar words. In grammar, follow the uniform grammatical structure (subject-verb-object order, active and passive voice), avoid arbitrary sentences. Semantically, the proper use of function overloading provides predictable and even consistent type of function entry and exit. It can even be consistent in more detail, just to give a few examples:

• Type logs in either Chinese or English.
• Asynchronous interfaces either all use callbacks, or they all change to promises.
• OnDoSomething = func or Object. on(‘ doSomething ‘, func).
• All setter operations must return this.
• …

It’s better to make the same spelling mistake for a word than to make the same spelling mistake once.

Yes, consistency, can’t be stressed enough.

Excellence: systems and the big picture

Version control

80% of development projects are bad at version control: arbitrary version names, empty and weird commit information, unplanned feature updates… It obviously takes a while for people to develop a disciplined development demeanor, but at least one thing needs to happen first:

The API guarantees forward compatibility when the large version number does not change.

The first <major> bit in <major>.<minor>.<patch>

This change represents a major change to the API as a whole, possibly incompatible, so users should be cautious about making dependency changes to the larger version; On the other hand, if the API has incompatible changes, it means that the large version number must be changed, otherwise the user is prone to routine update dependency and the entire system will not work, or worse, will cause online failure.

If the situation does not improve, users will choose never to upgrade dependencies, leading to more potential problems. Over time, these products (libraries, middleware, WHATEVER) will eventually be discarded.

So hopefully API providers won’t lock large versions to 0 in the future.

Ensure downward compatibility

/**
* @deprecated
*/
export function youWantToRemove(foo, bar) {}

/**
* This is the replacement.
*/
export function youWantToKeep(foo) {}
Copy the code

// modern browsers
document.hidden == false;

// out-of-date browsers
document.hidden == undefined;
Copy the code

if (document.visible) {
  // do some stuff
}
Copy the code

Design extension mechanisms

There is no doubt that while maintaining downward compatibility, apis need to have a corresponding extension mechanism for sustainable development — on the one hand, developers can add features themselves, and on the other hand, users can participate in the ecosystem.

Technically, interfaces can be extended in many ways: extend, mixin, decorate… There is no right or wrong choice, because different extension methods are suitable for different scenarios: logically there is a derivation relationship, and the need to use the base class behavior and custom behavior, use heavyweight inheritance; It’s just extending some behavior function, but there’s no logical parent-child relationship at all, use combination; Decoration is more applied to a given interface, packaging it into a variety of new interfaces applicable to different scenarios……

On the other hand, for different programming languages, due to different language characteristics… Static, dynamic, etc., are more suitable for some expansion methods. So, what kind of expansion method to use, or depends on the situation.

In the JS world, there are some classic technology products, their extension has even formed an ecology, such as:

• JQuery. $.fn. CustomMethod = function() {}; . This simple mixin approach has provided thousands of plugins for jQuery, and much of jQuery’s own API is itself built around this writing.
• The React. React themselves have dealt with all the component instantiation, life cycle, such as rendering and update trival matters, as long as developers to inherit from a component class based on the React.Com ponent. This is a classic approach for a Component system.
• Gulp. Compared to Webpack, which was a big hit in the last two years, I think Gulp is more like the logic of a building system — defining various “tasks” and then connecting them with “pipes”. A Gulp plugin is also pure, accepting file streams, returning file streams, and so on.
• Koa. For mainstream HTTP servers, the middleware design is pretty much the same: accept the previous request and return a new response. For Koa, which is inherently promise-oriented, the middleware style is more like Gulp, except that one is a file stream and the other is an HTTP stream.

It’s not just big frameworks that need to think about extensibility; designing extensible apis should become a fundamental way of thinking. Like this living business example:

// json
[
  {
    "type": "item",
    "otherAttrs": "foo"
  },
  {
    "type": "shop",
    "otherAttrs": "bar"
  }
]

// render logic
switch(feed.type) {
  case 'item':
    console.log('render in item-style.');
    break;
  case 'shop':
    console.log('render in shop-style.');
    break;
  case 'other':
  default:
    console.log('render in other styles, maybe banner or sth.');
    break;
}
Copy the code

Render a set of feeds based on different types: product module, store module, or whatever. One day, there was a new requirement to support rendering tmall store module (display more Tmall logos, etc.), so a type = ‘tmallShop’ was directly added to JSON interface — this interface modification is very simple and intuitive, but not good. Without changing the front-end code, the tmallShop type goes into the default branch by default, resulting in weird rendering results.

Considering the relationship between tmallShop and shop is an inheritance, tmallShop can be used as an ordinary shop, performing all the logic of the latter. In Java terms:

// a tmallShop is a shop
Shop tmallShop = new TmallShop();
tmallShop.doSomeShopStuff();
Copy the code

Reflecting this logic into the JSON interface, it makes sense to add a subType field that marks tmallShop, while its type remains shop. In this way, even if the original front-end code is not modified at all, it still works, except that it cannot render some of the characteristics of the Tmall store.

Here is a very similar positive case, which is the MODULE JSON Schema designed by ABS Building system (site building system produced by Taobao FED) :

// json
[
  {
    "type": "string",
    "format": "enum"
  }, {
    "type": "string",
    "format": "URL"
  }
]
Copy the code

Again, type is the main type, and the extension field is changed to format to accommodate some of the extension features. In practice, it is also very convenient to add all kinds of new data structure logic.

Controls the level of abstraction of the API

// abstract
I want to go to a place.
// when
{Today, Tomorrow, Jan. 1st} I want to go to a place.
// where
I want to go to {mall, cafe, bed}.

// concrete, no extends any more
Today I want to go to a cafe for my business.
Copy the code

Convergence API set

For a whole system of apis, the user is faced with the whole set, rather than a few of the individual apis. We should ensure that the apis in the collection are in the same abstraction dimension, and appropriately merge the API, reduce the information of the whole collection, and make subtraction as appropriate.

The product begins to do subtraction, is gentle to the user.

Convergence approximate meaning of parameters and local variables. There’s nothing wrong with the following set of apis, but it must be ominously intuitive for OCD:

export function selectTab(index) {}

export function highlightTab(tabIndex) {}

export function gotoPage(index) {}
Copy the code

Index, tabIndex, maybe pageIndex? To be sure, the naming of function parameters and local variables has no direct impact on the end user, but these inconsistencies are still reflected in the API documentation and can cause confusion for the developers themselves. So pick a fixed naming style and stick with it! If you forget, refer back to the “Solidified Glossary” section above.

Convergence approximates the function of duty. Exposing too many interfaces to users is not a good thing, but does merging different functions undermine the “single responsibility” principle?

No, because “single responsibility” itself depends on a specific level of abstraction. The following example is similar to, but different from, the previous example in “Using function overloading wisely.”

// a complex rendering process
function renderPage() {

  // too many APIs here
  renderHeader();
  renderBody();
  renderSidebar();
  renderFooter();
}

// now merged
function renderPage() {
  renderSections([
    'header', 'body', 'sidebar', 'footer'
  ]);
}

// call renderSection
function renderSections(sections) {}

// and the real labor
function renderSection(section) {}
Copy the code

Similarly, avoid exposing too many similar apis, and take advantage of abstractions to combine them to reduce the user’s stress.

For a scenario with a clear inheritance tree, convergence APIs are more natural and significant — Polymorphism is used to build Consistent APIs.

// bad: type-checking here
function travelToTexas(vehicle) {
  if (vehicle instanceof Bicycle) {
    vehicle.pedal(this.currentLocation, new Location('texas'));
  } else if (vehicle instanceof Car) {
    vehicle.drive(this.currentLocation, new Location('texas'));
  }
}

// cool
function travelToTexas(vehicle) {
  vehicle.move(this.currentLocation, new Location('texas'));
}
Copy the code

There’s a guy who’s taken the API to extremes: jQuery’s $(). Isn’t this style one of the killer features of jQuery back then?

Stop giving me foo() and bar() if $() will do it for me.

Convergence approximation function package. One level up, we can even merge similar packages.

In the Rax system of Taobao FED (RN-like framework), there are basic component labels, such as <Image> (in @ali/ rax-Components), <Link> (in @ali/ Rax-Components), as well as some package with enhanced functions. Such as <Picture> (in @ali/rax-picture), <Link> (in @ali/rax-spmlink).

In this case, the latter is an enhanced version of the former with more features. In practice, it is recommended to use <Picture> instead of <Image>. In this environment, the exposure of basic apis like <Image> becomes a nuisance. Consider incorporating the functionality of the enhanced package completely into the base component, i.e. <Picture> into <Image>, leaving the user with a single, standard component API.

Divergent API set

// the func is used here requestAnimationFrame(() => { // what? trigger an event? emitter.emit('moduleDidRenderRow'); }); / /... and there requestAnimationFrame(() => { // another one here, I guess rendering? this.setState({ // ... }); });Copy the code

// simple polyfill
export function requestIdleCallback(callback) => {
  callback && setTimeout(callback, 1e3 / 60);
};
Copy the code

Develop an API support strategy

We say that a set of public apis is a product. The product must have a specific audience, whether it’s a global developer, or just a cross-departmental colleague; Products also have a shelf life, or life cycle.

For the target user group, we need to formulate the API support strategy:

• How long is the support cycle for each large release.
• Whether there is a long-term stable VERSION of API support. (Long – term Support)
• How to upgrade from an older version.

Older versions are probably still running, but the maintainers have no time or energy to deal with these relics, so it’s better for developers and users to point out that certain versions are no longer maintained. Of course, don’t forget to provide upgrade documentation to guide existing users on how to migrate to the new version. It would also be better to identify the end of the life of the previous version as soon as we start a new version and inform users in advance.

There is also a technical caveat: it is best to have clear isolation between large versions. For a complex technical product, API is only the ultimate interface directly facing users, and there are specific environments, tool sets, dependency packages and other supports behind it, which cannot be mixed with each other.

For example, KISSY, once a classic front-end library. KISSY 6 relies heavily on TNPM (NPM of Alibaba’s internal network) and DEF Suite (front end tool suite of Taobao FED), although there are few API changes compared to the previous version 1.4. But you still can’t use version 6 directly in the old environment… This reduces the flexibility of free composition to some extent, but in fact, as the complexity of business problem scenarios increases, the solution itself will need to be more customized. Therefore, it is the status of the industry to package the environment, tools and other upstream and downstream associations together with the code into a whole technical solution.

So, isolate the large version, develop a good API support strategy, make our products more professional, so that users do not have to worry about.

conclusion