Once the API changes, it could bring enormous costs related calls, users need to troubleshoot all the code calls, you need to adjust all related parts, these work for them, are extra. If after the completion of these hard, also found a related bug, that is even greater blow to the users. If the API are constantly changing, users will lose to lose confidence in the provider, which will also affect current operations.
But why should we modify the API it? API to look more beautiful? In order to provide more features? In order to provide better performance? Or just think to change the time? For users who prefer to use a stable but does not look so funky API, this does not mean we do not improve the API. When the API to bring bad maintenance costs more and more, I think it is our time to reconstruct it.
If you can go back and do it again, so good API should my mind is kind of how?
Whether an API is excellent, not simply give judgment in accordance with the first version, but look over time, whether the API still exists, whether still maintained quite well. API interface slot cake variety, but a good API interface for the user must meet the following points:
- Easy to learn: well documented and provide as many examples and copy-paste code, like with other design work, you should apply Least Astonishment .
- Easy to use: no complicated procedures, intricate details, easy to learn; flexible API allows sorting by fields, customizable paging, sorting and filtering and so on. A complete API means that the desired functions are included.
- Misuse difficult: for a detailed error message, some users experienced API can be used directly without the need to read the documentation.
For developers, the requirement is not the same:
- Easy to read: write the code only once again, but when debugging or modifications are required to read the code.
- Ease of development: a minimization of the interface is to use as few classes as well as few class members. This makes understanding, memory, and debugging is easier to change the API.
How do the above points, the following are some conclusions:
1, for the case design
If an API is widely used, it is impossible to understand all the users using the API. If the designer wants to design a widely used API, we must stand on the user's perspective to understand how to design the API library, as well as how to design such an API library.
2, the use of good design ideas
In the design process, if they can be designed in the following way, this API will live longer
- Designed for use cases, gather user suggestions, himself modeled as users, to ensure ease of use API design and reasonable
- Ensure subsequent requirements can be accomplished by an extended form
- The first edition content do as little as possible, because the new requirements can be done through an extended form, so as little as possible to do things is an effective program to suppress API design errors
- External provide a clear API documentation and specifications, to avoid user errors using the API, especially to avoid API (see section I) on the list is known to the user level API and misuse
In addition, the following lists some specific design approach:
- The method is superior property
- The method is superior to the factory constructor
- Avoid excessive inheritance
- Optimized or avoid the influence API code reuse
- Oriented programming interface
- Extended parameters should be convenient
- How many interface components reasonable position to determine exposure
- Provide extension points
3, to avoid extreme comments
In designing the API, be sure to avoid any extreme views, in particular the following points:
- Must be nice (API need not necessarily beautiful)
- API must be used correctly (difficult for users to understand how to properly use the API, API designers to fully consider the situation to be misused API: If an API might be misused, then it will be misused)
- Must be simple (we always faced with complex needs, the API can do both better API)
- Must be high performance (performance can be optimized by other means, it should not affect the design of the API)
- Must be absolutely compatible (Although this article has been mention of how to ensure compatibility, but we still have to realize that, in some rare cases encountered incompatible can be tolerated)
4, valid API Review
After the API design is completed, need to go through careful design review, the focus of the assessment is as follows:
- Use case-driven, you must provide complete use cases before the review, to ensure the legitimacy and completeness of use cases.
- Consistency, whether the system is consistent with other modules of the interface style, whether the design is consistent with the symmetry of the interface.
- Simple, easy to understand API should be simple, easy to learn and use the API was not easy to be misused, give us more trouble.
- API as little as possible, if an API may be exposed or may not be exposed, then do not expose him, until the user really needs and then it became a public interface is also late.
- Support continuous improvement, whether API the ability to easily add functionality and optimized by extending the way.
5, to improve testability API
API needs to be tested, the test should not rely on implementation, testing the full API, in particular through a rigorous "Compatibility integration testing," the API, to better ensure compatibility problems do not arise in the process of upgrading. Compatibility integration testing, refers to a group set of test cases, test cases of this group will stand on the user's position using the API. After the API upgrade, then test whether this set of test cases can be completely in line with expectations by testing, found that compatibility issues as possible.
6, to ensure backward compatibility with the API
For each API designers who are eager to be "backwards compatible" because both now and in the API user, or potential user of the API, only trust those API compatible. But there are backward compatible significance on many levels, and different levels of backward compatibility also means varying importance and complexity.
7, to maintain and gradually improve
In the past we always hoping existing "unreasonable" design completely overturned, then follow the "good" ideas now, to redesign the API, but after a period of time, will encounter the same situation, we need to overthrow once . If we do not have an effective way to improve gradually, relying on the overthrow of the existing design, redesign the API only allows us to return to the starting point, and then reproduce the process before. To a well-established approach to continuous improvement in API compatibility at the same time, improve the API to make it better.
8, grasp the life cycle of the API
Each API is a life cycle, we need to have a longer life-cycle API, and make it smooth API demise at the end of the life cycle.
- How do we tell the user is designed to avoid misuse, provide guidance, often using the wrong API shorten the life of a major killer
- Trial period, API stability is impossible to start, after the trial of API in order to have a stronger vitality
- API grade is: internal use; secondary development; development or trial; stability; deprecated API. API while avoiding abuse, we can adjust the level of the API, to expand its influence, but also more elegant end of the life cycle of an API.
API development process is actually a process of communication. Communication is both user and API API designer.
9, a number of specific embodiments
When an API inevitable demise or changed, we should accept and face this fact, several are listed below under the premise to ensure compatibility, API approach to adjusting:
- API marked as deprecated, to re-establish a new API. If an API is inevitable demise, this is the only way.
- To add additional parameters or parameter options to achieve the function add
- The existing API split into two parts, a streamlined core API, the API in the past achieved by the package core API. This is typically used when you need to solve a stripped down version of the code.
- Encapsulated API based on the conventional, provides a more versatile package or class
Some good API example:
- API Flickr , here is the document example , while providing a very convenient API testing tool .
- Mediawiki API
- API eBay , there is a very detailed document examples .
Original link: http://www.biaodianfu.com/how-to-design-a-good-api.html
In the mobile phone is widely popular today, mobile phone applications also will be more and more, but the pace of growth is very fast. Mobile application development software implementations with common PC software, is also divided into BS and CS mode. The use of CS way, mostly in the form of server-side interface provides data exchange (mainstream data interactively there: Json, WebService, etc.), we say today is how to design the interface.
Bridge interface as a data flow communication with the client database, plays an important role, directly affects the efficiency of the program, stability, reliability and accuracy of the data integrity. Client focus is beautiful interface, easy to operate smoothly, the most direct experience is the user experience, and the interface is the provider of all data, the user experience of deep meaning.
Dimensionless, interface design in a project, it is very important. So I would summarize the current experience of how to design the interface.
First, the design principle
1. The in-depth understanding of the needs
In addition to database design most people understand the needs, the second is the person who designed the interface, the interface developers sometimes also involved in database design. From the "Client - Interface - Database" level point of view, the interface plays a significant role in the nexus of, on the one hand to understand what the interface to the data, on the other hand to consider how to get from the database, organizing data. So if you do not understand the requirements, you can not correct the abstract object to organize the data to the client, and can not validate the data structure of the database can meet the demand. Database designer to understand the structural requirements of the data, and the interface is more logical to understand the structural requirements and the logical data structure derived therefrom.
2. Understanding Database Structure
Since the interface to understand how to get from the database, organizing data, of course, to understand the database structure it.
3. Understanding Client prototype
Learn prototype, in fact, more data to help you design and structure of the interface need to provide. But sometimes when you are not designed a prototype, so this provision is not necessarily required. But if the interface design finished prototype came out, we can also take the prototype verification interface design is correct and reasonable.
Second, the design principles
1. good reason
There should be not just a function interfaces, it is not just a requirement would add an interface. Each new interface, and we should have every reason to consider that the existence of this interface is very significant amount of value, meaningless interfaces not only increases the difficulty of maintenance, is more important for the controllability of the process is greatly reduced The interface will be very bloated. So I placed first.
2. clear responsibilities
An interface is only responsible for a business function, and design patterns in which the single responsibility principle is similar but different, because in a business function may contain multiple operations, such as querying member, the member may have acquired in addition to membership queries sheet other necessary information, but do not modify the query of members as well as rights and similar other business functions, should be divided into two interfaces also do.
3. The high cohesion and low coupling
Interface to include a complete business functions, and associated services of different interfaces to be as small as possible. Examples of members or the query, but sometimes queries members may be of the members of the relevant information will be changed (such as status), if the time a complete line of business, then it should be done in an interface, and should not be Interface to set up a separate operation is completed. That is a change in the interface should not be changed with another or to a premise of the presence of several interfaces.
4. Analysis angle clear
Angle analysis of the interface design to unify clear. Otherwise it will cause confusion in the interface structure. For example, do not for a while in the role of a design perspective, while necessary to design a functional perspective.
The unified format into the reference
Parameter format and style requirements of all interfaces to unify, not one interface parameters are separated by commas, and the other is an array; not a date parameter is the interface x, x, x day style, the other is xxx.
6. The status and message
Provide the necessary interface call status information. Whether the call was successful? If this fails, then the reason for the failure is. The necessary information must be told to the client.
7. The control data volume
An interface returns should not contain excessive amount of data, the amount of data is too complex not only deal with the pressure of data transmission is also very large, it will lead to slow client response. Excessive amount of data interfaces often are not clearly demarcated.
8. prohibit arbitrary parameter expansion
Similar to section 1, it is only for the purposes of argument. Future expansion interfaces may be difficult to avoid, but not free to add parameters, additional parameters must be necessary and meaningful, before changes in demand should first consider whether the maintenance of existing internal interfaces to meet the demand, rather than by adding a parameter to facilitate difficulty to achieve their own needs, because more change will directly lead to changes in the parameters of the client calls, prone version compatibility issues.
Third, the design method
1. Abstract business
In contrast abstract objects, abstract broader business, I think it is also relatively easier, but often not very good grasp abstract scales.
2. Data Format
Interfaces defined data format must have been fully considered, otherwise the data conversion fails or exceeds the length error. If you are unsure, directly to a string is the most appropriate.
3. meaningful name
Whether the interface or parameter names should be meaningful, people Nengkanmingbai.
In short, the interface design is a painstaking work, there will be a lot of conflicting design, but individuals tend to coarse grained design direction (ie cohesion higher), so not only to the client browser interface to facilitate clear, maintenance is also lighter the disadvantage is that when doing an interface extensions are not very flexible, but it can be remedied by redefining an interface, but, as on earlier, new interfaces or to think twice. Although there are many more theoretical explanation, but keep in mind that, combined with the actual work, will slowly deeply appreciate the meaning of them. That theory to guide practice, practice to verify the theory.
Turn: Links
Reproduced in: https: //www.jianshu.com/p/fd0bdb5dc31d