Designed the API is a complicated job, but good design can be artificially through planning and implementation, in this article, we will study what is a good design and how to implement it in the development process, also introduce API design three important stages: sketch drawing, prototype design and delivery of implementation, finally share some tool to make work more efficient.
Good API design happens in iterations
Before you start designing an API, understand its purpose. From before to why you need to build apis now. Knowing the purpose allows you to follow the direction of development without going off the rails. However, defining purpose is only the first step; the real trick is to make good design decisions along the way.
As API designers, every decision we make has an impact on the success of our product. Big decisions such as API transport protocols, information formats, etc. There are also minor decisions to make with plug-ins, names, interface order, and so on. When you put them together, all these decisions add up to a pattern of use. If you make the best decisions, this pattern will help you design the API you need.
To make good design decisions, you need to learn from bad design. In fact, you may have to get it wrong many times before you get it right. That’s the key to iteration. No one gets it right the first time, but given enough chances, you can get closer.
Iterating through our API design is the logical thing to do, but in the real world it’s hard to do that. Because it is difficult to change an API after it has been published, changing the API in use is both expensive and risky. One way to solve this problem is to avoid changing the interface drastically with each change. This is a good habit and a fundamental rule of good API design. However, sometimes radical change is inevitable. Ideally, all usability and design issues should be resolved before changes become costly.
Iterative design process
Each iteration allowed us to design the content of our project for its purpose. For example, can developers accomplish their goals with what we build? Is this interface really possible? And so on. We should be able to achieve optimal API design by designing and implementing many interfaces without actually publishing them. So viewing and simulating each interface will provide practical lessons on how to improve the product.
But in practice, this kind of macro iterative design is impossible. We don’t have time to repeatedly design and validate an API. It makes more sense to perform iterations early in the design process. These early designs should have enough detail to generate opportunities for improvement, and over time we can gradually increase the level of detail (or fidelity) until we finally get to the API design we want.
This gradual process is popular in the design community and is usually divided into three important stages:
1. The power of sketches
Sketching is one of the most common design behaviors. Architect Frank Gehry is famous for his sketches, and many of his architectural projects begin with a series of sketches drawn on paper. He made hundreds of sketches, coming close to the ideal design each time.
Interaction designer Bill Verplank describes sketching as an essential first step in the design process. Bill Buxton has written an entire book on the value of sketching in user experience design, outlining key features and importance of sketching.
Combining sketches early in the API design process allows us to form a conceptual model of the interface in our minds. A good sketch should be easy to make and easily revised, and spending too much time on it is not worth it.
We can experiment with different types of interface styles and capture the abstractions that come to mind. We can record every momentary thought in the form of a sketch so that we can review and discuss them. We can decide if we like sketching a particular concept, then build on it or start over.
For example, we might draw a basic error stream associated with the entire API or a response message format that applies to all responses. Later, during the prototyping phase, we can apply these ideas to a working model.
2. Prototyping
The prototyping phase is a process of building a higher-fidelity model of the interface and testing some of the assumptions we made during the sketching process. To invoke a good API prototype, it should process the actual request message and provide return results when needed, and even be able to create a simple application using the prototype API.
However, it should be cheaper to build a prototype than to fully implement it. One way to reduce costs is to simulate returning messages rather than providing the actual results from the back-end system. This is MOCK, and it’s a great way to quickly prototype.
We should be able to build two or three different prototypes based on the sketches, and while we’re building, we can even go back to the sketches and try new directions based on what we’ve learned from the prototyping phase.
Prototypes can also provide your team with early user feedback on the design and allow you to see how it is actually used. If the interface has high fidelity, you can ask potential users to build applications on top of it and observe the problems they face along the way.
A well-designed API should not only be easy to use, but also be sustainable, reliable, high-performance, and long-lived. The design cycle is like a scientific process, and the prototyping phase is your chance to test any hypothesis before making changes.
3. Implementation of delivery
The developer’s job is to make the prototype interface deliverable. The final prototype and supporting sketches form a description of what the interface should look like. They reflect collective design decisions to form specifications that need to be built. In fact, it is useful to use a formal interface description language to move from prototype to implementation.
For example, when you are happy with the prototype API, you can choose to describe it in some API management tool such as EOLNKER.
While implementation delivery is the final goal, design should not stop there. This is an opportunity to further test the assumptions you make throughout the design process with actual usage data. Just as the prototype API allows us to observe usage, the implemented API allows us to analyze usage in real-world situations.
For example, you might want to validate design assumptions that you have made. Do application developers really use the convenience actions you create for them? Are you getting the type of users you expected? Are new users experiencing problems with specific parts of the interface?
This analysis may cause you to start the sketching process again to support further improved interfaces.
Use tools to automate the process
Tools and techniques can radically improve the design process. Tools that reduce the cost of sketching and prototyping will improve design decisions by enabling design teams to produce more designs in less time.
Combining tool automation is an important part of most design processes. In the field of architectural design, SHoP (the New York-based Architects Consortium) has achieved success through innovation, collaboration and tool-based design. Their process includes prototyping tools that allow designers to combine the physical properties of the materials used. This approach allows them to create thousands of design iterations, each containing implementation details that can be easily evaluated.
There are tools for this kind of optimization in the API design world as well. In fact, some excellent Web API design tools already exist in the API services space worldwide.
Now, EOLINKER, RAML, Swagger, and others offer excellent editing tools to support their languages. EOLINKER, as a leading API interface management r & D tool in China, is surpassing traditional single service products such as RAML, Swagger and other foreign countries with more comprehensive functions and simple pages. These editors shorten the time it takes to create API designs, making it easier to create more descriptions in less time. Click to see EOLINKER’s API editor.
Successfully complete the iteration process
By following the iterative design style described in this article, you will create effective apis for your team. Create and evaluate many low-fidelity designs at the beginning of the process to facilitate experimentation and ideation. Build higher fidelity prototypes and simulation implementations to evaluate early design ideas. Finally, implement the design for real users and collect data to analyze actual usage.
A good API design process gives you the opportunity to generate the best interface possible. The secret to building a great API is not expert guidance or insider knowledge. Rather, it’s iteration through great tools, languages, and config file optimization that will help you build more and more great apis.
Resources: Ronnie Mitra, From Doodles to Delivery: An API Design Process the original address: www.infoq.com/articles/do…