JavaScript API Design Principles

NET + Offline Salon | Mobile app Mode innovation: give you a reason to do the app >>

Good API design: In the self-description, at the same time to achieve abstract goals.

Well-designed APIs allow developers to get started quickly, without the need to keep manuals and documentation often, or to visit the tech support community frequently.

Smooth interface

Method chain: Smooth and easy to read, easier to understand

2. Common API Call methods: Change some colors, add event listener
4. var elem = document.getElementById ("Foobar");
6. Elem.style.background = "Red";
8. Elem.style.color = "green";
10. Elem.addeventlistener (' click ', Function (event) {
12. Alert ("Hello world!");
14. }, true);
18. (conceived) method chain API
20. Domhelper.getelementbyid (' foobar ')
22. . SetStyle ("Background", "Red")
24. . SetStyle ("Color", "green")
26. . addevent ("click", Function (event) {
28. Alert ("Hello World");
30. });

Settings and get operations can be combined; the more methods, the more difficult the document may be to write

1. var $elem = jQuery ("#foobar");
3. Setter
4. $elem. Setcss ("Background", "green");
5. Getter
6. $elem. GETCSS ("color") = = = = "Red";
8. Getter, Setter merged
9. $elem. CSS ("background", "green");
10. $elem. CSS ("color") = = = = "Red";

Consistency

The relevant interface maintains a consistent style, and a full set of APIs that convey a sense of familiarity and comfort will greatly reduce the developer's adaptability to new tools.

Naming this thing: both short and self-describing, and most importantly, maintaining consistency

"There is only a problems in computer science:cache-invalidation and naming things."
"There are only two headaches in the computer science: Cache invalidation and naming problems"
-phil Karlton

Choose a language that you like, and then continue to use it. Choose a style, and then keep that style.

Processing parameters

You need to think about how you can use the methods you provide, and whether they will be repeated calls? Why is the call repeated? How does your API help developers reduce repetitive calls?
Receiving map map parameters, callbacks, or serialized property names not only makes your API cleaner, it's more comfortable and efficient to use.

The JQuery css() method allows you to style the DOM elements:

1. JQuery ("#some-selector")
2. . CSS ("background", "Red")
3. . css ("Color", "white")
4. . CSS ("Font-weight", "bold")
5. . css ("padding", ten);

This method can accept a JSON object:

2. JQuery ("#some-selector"). CSS ({
4. " Background": "Red",
6. "COLOR": "White",
8. " font-weight": "bold",
10. "padding": ten
12. });
16. Bind events by passing a map map
18. JQuery ("#some-selector"). On ({
20. "click": Myclickhandler,
22. "KeyUp": Mykeyuphandler,
24. "Change": Mychangehandler
26. });
30. Binding the same handler function for multiple events
32. JQuery ("#some-selector"). On ("Click KeyUp Change", MyEventHandler);

Processing type

When defining a method, you need to decide what parameters it can receive. We are not sure how people use our code, but can be more visionary and consider what parameter types are supported.

2. The original code
4. DateInterval.prototype.days = function (start, end) {
6. return Math.floor ((end-start)/ 86400000);
8. };
12. The modified code
14. DateInterval.prototype.days = function (start, end) {
16. if (! ( Start instanceof Date)) {
18. Start = new Date (start);
20. }
22. if (! ( End instanceof Date)) {
24. end = new Date (end);
26. }
30. return Math.floor ((End.gettime ()-start.gettime ())/ 86400000);
32. };

Adding a short 6 lines of code, our approach is powerful to receive Date objects, numeric timestamps, and even Sat Sep 08 2012 15:34:35 GMT+0200 (CEST) strings like this

If you need to ensure that the passed parameter type (string, number, Boolean) can be converted like this:

1. function Castaway (some_string, Some_integer, Some_boolean) {
2. Some_string + = "";
3. Some_integer + = 0; //parseint (Some_integer, 10) more secure
4. Some_boolean =!! Some_boolean;
5. }

Handling undefined

To make your API more robust, you need to identify whether the actual undefined value is passed in, and you can examine the arguments object:

2. function testundefined (expecting, someargument) {
4. if (someargument = = = undefined) {
6. Console.log ("someargument is undefined");
8. }
10. if (Arguments.length > 1) {
12. Console.log ("However it is actually passed in");
14. }
16. }
20. testundefined ("foo");
22. Result: Someargument is undefined
24. testundefined ("foo", undefined);
26. Result: Someargument was undefined, but it actually came in.

Give the parameter a name

1. Event.initmouseevent (
2. "Click", True, true, window,
3. 123, 101, 202, 101, 202,
4. true, false , False, False,
5. 1, null);

Event.initmouseevent This method is simply insane, without looking at the document, who can say what each parameter means?

Give each parameter a name and assign a default value.

2. Event.initmouseevent (
4. Type="click",
6. Canbubble=True,
8. Cancelable=True,
10. View=window,
12. Detail=123,
14. screenx=101,
16. screeny=202,
18. clientx=101,
20. clienty=202,
22. Ctrlkey=True,
24. Altkey=false,
26. Shiftkey=false,
28. Metakey=false,
30. button=1,
32. relatedtarget=null);

ES6, or Harmony has default parameter values and rest parameters.

Parameter Receive JSON object

Instead of receiving a bunch of arguments, you might as well receive a JSON object:

1. Function Nightmare (accepts, async, beforesend, cache, complete,/ * etc 28 Parameters */) {
2. if (accepts = = = "text") {
3. //Ready to receive plain text
4. }
5. }
7. function Dream (options) {
8. options = Options | | {};
9. if (options.accepts = = = "text") {
10. //Ready to receive plain text
11. }
12. }

It's also easier to call:

1. Nightmare ("text", true, undefined, false, undefined,/ * etc 28 parameters */);
3. Dream ({
4. Accepts: "text",
5. Async: True,
6. Cache: false
7. });

Parameter Default value

Parameters are best with default values, which can be overridden by jquery.extend () http://underscorejs.org/#extend) and Protoype object.extend.

2. var default_options = {
4. Accepts: "text",
6. Async: True,
8. Beforesend: null,
10. Cache: false,
12. Complete: null,
14. //...
16. };
20. function Dream (options) {
22. var o = jquery.extend ({}, default_options, Options | | {});
24. Console.log (o.accepts);
26. }
30. Dream ({async: false});
32. Prints: "Text"

Scalability

Callback (callbacks)

With callbacks, the API user can overwrite a portion of your code. Open up some features that you need to customize into configurable callback functions that allow API users to easily overwrite your default code.

Once the API interfaces receive callbacks, make sure they are documented and provide code examples.

Event (events)

The event interface is best known for its name, and the event name can be chosen freely to avoid the same names as the original event.

Handling Errors

Not all errors are useful for developer debug code:

1. jQuery allows this to be written
2. $ (document.body). On (' click ', {});
4. Click the Times wrong
5. TypeError: ((P.event.special[l.origtype] | | {}). Handle | | L.handler). Apply is not a function
6. In JQuery.min.js on line 3

Such errors are painful to debug, do not waste the developer's time, tell them directly what is wrong:

1. if (Object.prototype.toString.call (callback)!== ' [Object Function] ') { //See note
2. throw New TypeError ("Callback is not a function!");
3. }
4. Remark: typeof callback = = = "function" There will be a problem on the old browser, and object becomes a function.

Predictability

A good API is predictable, and the developer can infer its usage based on an example.

Modernizr ' s feature detection is an example:

A) the attribute name it uses is fully matched to HTML5, CSS concepts, and APIs

b) Each individual detection consistently returns a value of TRUE or False

1. All of these properties return ' true ' or ' false '
2. Modernizr.geolocation
3. Modernizr.localstorage
4. Modernizr.webworkers
5. Modernizr.canvas
6. Modernizr.borderradius
7. Modernizr.boxshadow
8. Modernizr.flexbox

A concept that relies on the familiarity of the developer can also achieve predictable purposes.

The jQuery ' s selector syntax is a notable example, and the CSS1-CSS3 selector can be used directly with its DOM selector engine.

1. $ ("#grid") //Selects by ID
2. $ ("Ul.nav > li") //All LIs for the UL with Class "Nav"
3. $ ("ul Li:nth-child (2)") //Second item in each list

Proportional coordination

A good API is not necessarily a small api,api size to match its function.

For example, Moment.js, the famous date parsing and formatted library, can be called equalization, its API is both concise and functional clear.

A library of specific features, such as moment.js, is important to ensure that the API is focused and small.

Writing API Documentation

One of the hardest tasks in software development is writing documents, in fact everyone hates to write documents, complaining that there is no good documentation tool.

Here are some document auto-generation tools:

• Yuidoc (Requires node. js, NPM)

• JsDoc Toolkit (Requires node. js, NPM)

• Markdox (Requires node. js, NPM)

• Dox (Requires node. js, NPM)

• Docco (Requires node. js, Python, Coffeescript)

• Jsduck (Reqires Ruby, Gem)

• JSDoc 3 (Requires Java)

JavaScript API Design Principles