Ten principles for good API design

Every software developer uses APIs. "Good" API design is like magic. However, I don't know many people who can explain why some APIs are complex and difficult to learn, while others are clean, simple, and a joy to use. In this article, I will answer this question and provide ten rules for good API design.

1. Do only what you need today

This is the top rule. Only solve the problems that must be solved today, and minimize the answers that need to be completed. The temptation to solve tomorrow's problems is huge. But resist the temptation! Don't release code early, focus on reducing the release cycle. If it takes a few hours to answer a new question, then you don't have to guess what problem will come up tomorrow.

2. API modularization

Break large problems into smaller, individually solvable ones. Modular APIs are easier to learn and can change over time. You can replace old modules with new ones. Modules can be taught one by one. Experimental parts of the API can also be separated from stable or traditional parts.

3. Use structured grammar

Use a structured API syntax: replace do_action_with_thing with thing.action or thing.property. The syntax will naturally adapt to a modular approach, where each module is a class.

4. Use natural semantics

Don't invent new concepts. Use only concepts that are well known to developers as the basis for your class system. If you find yourself needing to explain concepts, you're doing it wrong: either you're solving a later problem, or you're building your API incorrectly.

5. API Self-Agreement

Each class should strictly follow the same style and conventions. Consistency means that when a person learns one class, he can master all classes in a coherent manner. Document the conventions and make them a standard that contributors must follow.

6. API Scalability

Easy extensibility has many benefits, not just being popular with contributors. It also allows you to delay implementing features because "if you need it, it's easy to add it later." It's also a win-win if you don't add features that you don't need.

7. Thorough testing

Every class and method must be thoroughly tested against malicious code. Write tests as you would code, and use them as if they were documentation of the API's contract to the outside world. Run these tests every time the code changes. Don't worry about code coverage. What matters is the external contract. Consider using the contract lifecycle as well.

8. Layered Growth

Keep your APIs focused, then layer new APIs on top so they can grow over time. Extensibility does not mean indefinite growth. Be clear about the scope of your API, and enforce it within that scope.

9. Keep it simple and easy to use

The ultimate test is how simple your API is to use. Do the examples you write make your code look simpler? Are you forcing users to specify options they don't care about? Are there extra steps that add no value? Focus on reducing the visible area of ​​your API.

10. Maintain portability

Don't let system concepts leak into the API. Clean and purposeful abstractions: This API can run on any operating system. The API must be able to hide the implementation, but pay attention to the 4th rule and use natural abstractions.

Welcome to share your views