API creation: framed and wall mounted

Each programmer is an API designer. Good programs consist of modules, and the module interaction protocol is also an API. Good modules are reused.

The API is a big power and a big responsibility. A good API will have thankful users; support for the bad will turn into a nightmare.

Public API - not a sparrow, publish - can not be removed. There is only one attempt to do everything right, so try.
')
The API should be easy to use, but difficult to use incorrectly. Making something simple using this API should be easy; complicated is possible; doing something wrong should be impossible, or at least difficult.

The API should describe itself. Studying the code on such an API does not cause a desire to read comments. In general, comments are rarely needed.

Before developing an API, collect the requirements with a fair amount of skepticism. Realize common tasks and solve them.

Design your requirements as API usage patterns. Check them in the design process.

In the first draft, the API should be brief, usually one page with signatures and one-line descriptions. If everything is wrong, it will be easier to redo it.

Encode usage patterns prior to implementing the API, even before detailed definition. Due to this, you will not spend time on a fundamentally unviable API.

Change the pattern of usage patterns as the API evolves. This will eliminate unpleasant surprises. Then templates can be used in examples, documentation and tests.

The code of examples should be exemplary. Users will copy it into their programs. The slightest mistake bugs a hundredfold.

You can not please everyone and in everything, strive to please everyone equally. Most APIs are too sharpened by the needs of their creators, which deprives flexibility.

Get ready for your own mistakes in API design. It would be naive to believe that you have thought through every single scenario of using the API, side effects of interacting with the environment, etc.

When developing an API, one in the field is not a warrior. Show the API to as many colleagues as possible and take criticism. They may notice your mistakes.

Names matter. Strive for clarity and symmetry. Be consistent. Each API is a small language, users will learn to read and write on it. The code on a good API is similar to natural text.

I can’t think of good names - go back to the design. Do not be afraid to shovel API. If the names fall one to one, you're on the right track.

Doubt - delete. Perhaps the main rule of development API. It concerns everything: blocks of functionality, modules, classes, functions, methods, parameters. Each separate part of the API should be as small as possible, but no less. You always have time to add something, but nothing can be removed. First of all, reduce the number of meanings, not classes or methods.

Make sure that implementation details do not get into the API. This knocks down users and hinders the development of the API. It is not always easy to understand what the implementation detail is: Beware of excessive detail. For example, do not specify the hash function in the API.

Reduce variability. Unchangeable objects are simple and safe.

Documentation matters. No one will use a good API without documentation. Describe every public entity: every class, every function, every argument, every field.

Keep in mind the implications of decisions in the API architecture for performance, but do not put it above the quality of the API. Fortunately, a good API is usually friendly with high performance.

Do not go with your charter in a strange monastery. The API should fit organically into the language and platform, follow agreements. A bad idea is to transfer the API from one platform to another without changes.

Reduce availability. Doubt - do private. This simplifies the API and reduces connectivity.

Apply inheritance only if you can’t say that every instance of a subclass is an instance of a superclass. The public class cannot inherit, only to reuse the implementation.

Consider and document the possibility of inheritance, or prohibit it. Describe in the documentation how and when class methods call each other. Without this, safe inheritance is impossible.

Do not force the user to do anything for the library. A sure sign is a duplicate code when working with an API. It is tiring and fraught with errors.

Follow the principle of least surprise. The function should do something most expected from its name and signature.

Aim for mistakes when used up as early as possible. Best of all - at compile time. At runtime, preferably at the first erroneous call.

Give programmatic access to everything that is available as text. Inhumane doom users to parse lines. Worse, the text format will actually become part of the API. Example: if you can print the stack trace, you should be able to get a list of frame references.

Overload methods / functions with care. If their action is different, it is better to give different names.

Apply the most appropriate types. For example, accept and transfer the IP address as a special type, not a number or string.

Hold on to the same order of arguments in the functions. Otherwise, users will confuse everything.

Avoid long lists of arguments, especially if several pieces of the same type go in a row.

Methods should not return values ​​that require special handling. Users will forget about checks. For example, return an empty array or list, not null .

Exceptions are for exceptional situations only. Exception handling should not be part of the main logic of client programs. It is ugly, fraught with errors and often beats on performance.

Throw unchecked exceptions if the user is unlikely to intelligently handle the error.

Creating an API is an art, not a science. Think about beauty, trust your intuition. Do not follow these rules blindly, but break them only occasionally and for good reason.

---

Presentation and video : the same, but in a few other words and with Java examples.