From graffiti to publishing-understanding the design process of the API

English Original: From doodles to Delivery:an API Design Process

The basic understanding of Web-based applications is a good foundation for designing web APIs that work properly. But if your goal is to create a good API, that's not enough. Designing an excellent API is a tough process, and if it happens to be your current job, you're likely to feel overwhelmed.

However, a good design is absolutely achievable. The process described in this article will help you succeed, and we will work together on what good design is and how iterative processes can help us achieve that goal. We will also describe the three important stages of design: sketch design, prototyping, and implementation, along with tools that will make your work easier.

　　Excellent API design comes from the iterative process

Before we start designing the API, we have to understand its purpose. Before you manually design, you should understand why you should design this API, if you need help in this area, there are many ready-made information to refer to. However, defining your motivation is only the first step, and the real trick is to keep making the right design decisions until it's done.

A successful API design means designing an interface that is designed to work in a way that fits its purpose. As an API designer, every decision we make will affect the success or failure of the product. Some important decisions need to be made during the design process, such as the transport protocol used by the API, or the message format it supports. But beyond that, there are a number of related secondary decisions, such as interface control, name, association, and order. And when you put all your decisions together, they drive the usage patterns of the API. If you can make every decision right, then this model will create the perfect support and promotion for the API.

If you want to make the right design decision, it is likely that you will make a wrong decision and learn from the lessons. In fact, you're likely to get close to the right decision after many mistakes. This is the key to the iteration, because no one can succeed, but as long as there is enough opportunity, you can be close to perfection.

An iterative approach to API design is easy to say, but it is not easy to do so in real-world applications. One of the common challenges we face is the difficulty of making changes after an API is released. In fact, the cost of making changes to an in-use API is significant and risky. Or borrow Joshua Bloch: "The Open API is like a diamond, it is immutable." ”

One way to deal with this problem is not to break the existing interface in each change, which is a good habit and a major principle of good API design. Sometimes, however, disruptive changes are unavoidable, and design changes at the basic level are particularly aggressive.

In other ways, we should make these changes before the interface is released. Ideally, you should eliminate usability and design problems before the cost of change becomes high. At that time, the problems could be found and fixed only if the iterations were started as early as possible before the first release and the frequent iterations were maintained.

　　Iterative design Process

In each iteration, we were given an opportunity to evaluate the design candidates by their usage. For example, can a developer achieve his goals by using the products we create? Can this interface really be implemented? What would they feel if we asked others to use the API?

By designing and implementing multiple interfaces without publishing them, you should be able to achieve the best API design. By reviewing and testing each interface, we have good insight into how to improve the final product.

But in practice, this spectacular iterative design is impossible to achieve. Few people have enough time, money, or patience to continually design and implement APIs that can be run. For any interface with a certain degree of complexity, the iterative design of this approach takes up too much of your time.

A more sensible approach is to iterate early in the design process, which should have enough detail to show the best timing for improvement, but without the need for over-design to make the implementation difficult. Over time, we can gradually increase the level of detail (or fidelity) and eventually get a complete implementation.

This progressive design process has become very popular in the design world, and it is often broken down into three important phases:

1. Sketch Design
2. Prototype design
3. Realize

　　The powerful role of sketch design

Sketch design is a kind of general behavior in design. The famous architect Frank Gehry's sketches are so famous that they have produced a film that describes these sketches. Many of his architectural projects began with a series of sketches drawn on a stack of paper. Gehry always draws hundreds of such sketches, each of which is a step closer to a good design.

Bill Verplank, the Interactive designer, describes the sketch design as an essential first step in the design process. Bill Buxton also wrote an entire book describing the value of the sketch design approach to user experience design, and considered its key feature to be its deprecation and the lowest cost in all exploration methods.

Incorporating the sketch design process in the early stages of the API design process gives us an opportunity to experience the conceptual model of the interface. This is not only a good opportunity to define the ideas that we have in mind, but it also gives us the opportunity to explore new ways and to propose "if ... What will happen? "Such a problem, and gradually moving towards true innovation.

Good sketches should be easy to create and can be discarded arbitrarily. If creating these sketches takes a lot of time, or is too difficult, then it's hard to discard them. This kind of abandonment is very important, it gives us the opportunity to withstand the risk.

We can try out different types of interface styles through sketch design, and catch the abstract concepts that flash in our minds. Once these ideas are embodied, we are able to review and discuss them. Decide in the process that we like or dislike a particular concept and then start the process again after digesting the knowledge and drawing a new sketch.

For users outside of the design team, they rarely evaluate sketches. Not only is it worthless to validate assumptions prematurely, but the number of user tests that can be performed in the actual project is limited. The idea of testing each sketch with a real user is too expensive, and the harvest is very limited.

　　Using files for sketch design

Using the archive (profile) or meta-language (meta language) is a very useful way to design your API sketches. The archive provides a series of concepts that can be used in the design of sketches. An excellent file can be likened to a box and a line, through which you create various sketches of the system diagram. These elements are something that both designers and evaluators can understand, making it easier to develop sketches quickly.

In fact, a good way to get started with the API sketch design process is to define the most obvious list of words in the interface. What are the words that the user must know? Which words best represent the purpose and task of your target audience? By answering these questions and creating a glossary of interfaces, you will be helped to form an early sketch of the interface.

The beauty of the archive is that it provides us with a formalized way to share and reuse this type of information. For example, we might start by extracting words from an XML structure document, getting a glossary from schema.org, or getting information from an Alps or RDF document, depending on our needs.

The goal of the design phase is not to create a comprehensive glossary, rather, the early glossary is just a starting point, and we can begin to draw other types of detail from this point. We may find that a list of 20 or so words can capture the nature of the interface, and this list will serve as our starting point.

This glossary provides us with a foundation from which we can design sketches of resources and associations in the API, which can include URIs, resource names, associations between resources, linked text, and other structured and navigational elements. Again, please note that it is not necessary to draw all the details of the sketch, our goal is to express the most important part of the API.

The most important point is that the initial sketch does not need to be too deep. For example, try to avoid modeling the error stream at this stage, or respond to the design of the message element. These sections can be added later, or they can be specially designed for sketching.

A separate sketch does not need to reflect the entire interface, in fact, it may be more practical to design sketches specifically for some detail parts. For example, we can design a sketch of a basic error stream that is relevant to the entire API, or a sketch that responds to a message format that can be applied to all responses. Then, during the prototyping phase, we can apply these ideas to a working model.

　　Prototype design

During the prototyping phase, we will have the opportunity to design a model with a higher fidelity for the interface and validate some of the assumptions generated during the sketch design phase. A good API prototype should be callable, it should be able to handle the real request message, and provide a response if necessary. Developers should even be able to create a simple application by using this prototype API.

However, the cost of creating a prototype should be less than a complete implementation. There is a way to keep the cost low, that is, to simulate the response message instead of outputting the real response message by the backend system. This is sometimes referred to as an interface fiction (mocking), which is a great way to build a fast prototype.

Regardless of which method is used to build the prototype, the point is to find a suitable scope for the inputs that can support subsequent iterations. We should be able to create two to three different prototypes based on sketches and continue to learn in the process. Based on what we learned during the prototyping phase, we might even go back to the sketch design phase and try a new direction.

By prototyping, your team will have the opportunity to get early user feedback on the design and be able to observe real-world usage. If the fidelity of the interface has reached a certain level, you can allow potential users to create applications and observe the challenges they face in the implementation phase.

The members responsible for implementation should also be included in the prototype evaluation process. A well-designed API should not only be easy to use, but also sustainable, reliable, high-performance, and long-lasting. Although the interface itself should not expose the internal details of the data model to the architecture of the server, it is the responsibility of the implementation to advise the design team on the decisions they make, such as the limitations of the operating environment and the cost of implementation.

The design cycle is like a scientific process, and you should seize this opportunity in the prototype phase to validate the assumptions made when the change is not too late.

　　Realize

The task of the implementation is to turn a prototype interface into a product that can be used with confidence in the actual application. Delivering a secure, reliable, and scalable implementation is a big challenge, and the process itself needs to go through a specific design process.

The final prototypes and supporting sketches describe what the interfaces should look like, they reflect all the design decisions, and form a specification that explains exactly what products need to be created. In fact, a formal Interface Description language (or IDL) can be used to naturally transition from the prototype phase to the implementation phase.

For example, if you are satisfied with the prototype API, you can choose to describe it in an API Blueprint document (or swagger, RAML, WADL, or any other format that best suits your work environment).

Although the goal of this phase is to achieve, it should not stop the pace of design. This phase is a good opportunity for you to further validate the assumptions made throughout the design process through real-world usage data. Just as the prototype API allows us to observe the usage situation, the implemented API allows us to analyze usage at a macro level.

For example, you might want to validate the design assumptions you have made before. Are the application developers really using the handy actions you created for them? Are you attracted to the type of user you expect? Is the new user having trouble using some parts of the interface?

After analysis, you may restart the sketch design process to prepare for further improvements to the interface.

　　Automate the process with tools

The use of tools and technologies can greatly improve the overall design process. Tools that reduce the cost of sketching and prototyping can allow the design team to create more detail in less time, making design decisions better.

For most design processes, the introduction of tools and automation is an important part. In the world of architectural design, shop, a New York-based architect, has been successful through innovation, collaboration, and tooling design. The prototype tool was introduced into their process, allowing the designer to reflect the physical properties of the material used. This approach allows them to create thousands of design iterations that demonstrate easy-to-evaluate implementation details in each iteration.

In the world of API design, this tool-based optimization has a good performance opportunity. In fact, in the area of service description, there have been some excellent Web API design tools.

The interface Description Language can also provide a supportive tool to simplify the task of writing a description, which is now common. These editor tools can shorten the creation time of the IDL-based design, making it easier to create more descriptions in a shorter period of time. Swagger, Raml and blueprint all offer excellent editing tools to support their respective languages. Even IDL, like Wadl, is only published as a specification, and can benefit from tools such as SOAPUI.

Apiary is highly competitive with the editor provided by the Blueprint language because it provides a complete set of workflow tools to support the design process. As long as a simple API description is written in blueprint, the designer is able to evaluate the document, invoke the prototype, and even analyze the invocation process.

However, most of these existing tools are limited to the description languages that they support. The designer must understand the syntax of IDL and design the interface in this language. While this style of design attracts users familiar with programming languages, it also limits the value of abstract and experimental thinking in the early stages of sketch design.

Because of these characteristics of IDL and its corresponding tools, they are suitable for the prototyping process, but they are not practical for early experimental activities of sketch design.

　　Sketching with visual tools

There is a growing interest in using visual tools to help them design their APIs. These tools do not directly support the behavior of editing IDL, but rather allow the designer to manipulate a visual representation of the interface at will.

The Visual modeling tool provides an interface description language, which is mostly about painting, or graphics-based. While this perspective limits the accuracy of interface presentation, it also allows designers to see the full picture of the interface at a higher level. This leads to an opportunity for improvement, which is often not apparent in handwritten forms.

The easy-to-use visual editor is also a good choice for automating sketch design, which combines features such as low fidelity, abstract presentation, and deprecation, which is exactly what we need.

I was involved in the development of a visual modeling tool called Rápido!, which is designed to assist with the sketch design of the API. Rápido restricts the user to a low-fidelity detail, which is not a side effect, but is designed in itself. Users can use it to model files, navigation elements, and response data, but they cannot be used to design logical processes or dynamic responses.

When the designer starts to create a new Rápido project, they need to design a glossary for the API. After getting an initial list of words (or importing an Alps glossary from the outside), designers can start designing conceptual models for the API, creating resources, attempting URI names, and even linking states in a hypermedia canvas.

Ultimately, designers can implement static response messages for each resource or state in the sketch to increase fidelity. Finally, when the sketch design phase is finished, you can export the entire design to IDL format, ready to import high fidelity tools in the prototype phase.

Rápido's goal is to provide a quick-draw "cocktail napkin" sketch experience in the field of Web API design. If you choose the right fidelity and don't impose too strong a limit, it can be an important part of the API design toolchain.

　　Success in the iterative process

If you are designing an iterative style as described in this article, you will have an opportunity to design an efficient API for your team. Create multiple low-fidelity designs at the start of the process and evaluate them to nurture experimental and ideation capabilities. Then create high fidelity prototypes and virtual implementations to evaluate early design ideas. Finally, the entire design is implemented for real users, and data is obtained to analyze usage in real-world applications.

The specific details of the iterative design process depend on your environment and project, how much detail you need, how many iterations you have, and what assessment techniques are needed, which will be left to the designer to answer. But as a general rule of thumb, as your design process progresses, the number of iterations should be reduced gradually, and more effort will be devoted to the assessment.

The excellent API design process gives you the opportunity to create the best interface. But the secret to creating a good API is not the guidance of an expert or the arcane knowledge, but the application of an iterative process optimized through excellent tools, languages, and archives. Using the API delivered with this formula will help your organization succeed.

http://kb.cnblogs.com/page/527814/

From graffiti to publishing-understand the design process of the API (GO)