- understand the design of the API from graffiti to release
English text:From Doodles to Delivery: An API Design Process
If you want to design a Web API can be normal operation, the basic understanding of Web based applications is a good foundation.But if your goal is to create excellent API, so this alone is not enough.Design excellent API is a difficult process, if it happens to be your current task, then you'll probably feel overwhelmed.
However, good design is absolutely can be achieved.This article described the process will help you be successful, we will study together what is good design, and an iterative process to help us achieve this goal.We will also describe the design of the three important stages: sketch design, prototype design, and implementation, and also introduce some can make your job easier.
A good API design from the iterative process
Before we begin to design the API, we must understand its purpose.Before you design manual, you should know why want to design the API, if in this areaNeed to behelp, there aremanyReadily availableThe informationYou can refer to.Define your motivation, however, is only the first step, until the real trick is to implement, and always maintain the correct design decisions.
Successful API design means to design a kind of interface, make its use in accordance with its purpose.As the API designers, what we do every decision will affect the success or failure of the product.Need to make some big decisions in design process, such as apis used by the transport protocol, or it supports message format.But beyond that, there are many relevant secondary decision, such as the control, the name of the interface, correlation and sequence.And when you will be all decisions together, they will drive the API usage patterns.If you can do every decision is correct, then this model will have a perfect on API, support and promote the role.
If you want to make a correct design decisions, is likely to make a wrong decision, and learn from.In fact, you are likely to be after many mistakes to close to the right decisions.The key to which is iterative, because no one has been able to achieve a successful, but as long as there's plenty of opportunity, you will be able to be close to perfect.
Through iterative manner API design, this is easier said than done, but in practice is not easy to do it.We face a common challenge, again after a certain API changes is very difficult.In fact, the use of an API in the cost of change is very big, and accompanied by great risk.Or borrow Joshua Bloch said:"The public API is like a diamond, it is eternal.”
A way to deal with this problem is in every time change don't damage the existing interface, this is a good habit, also is one of the main principles of good API design.But sometimes the disruptive change is inevitable, and the fundamental aspects of the design change is particularly aggressive.
Another way of thinking, we should make these changes before publishing interfaces.Ideally, before becoming expensive to change, should eliminate the usability and design problems.At that time, only do early iterations before first release, and maintain frequent iteration, to be able to find and fix the problem.
An iterative design process
In each iteration, we got a candidate for design according to its usage to evaluate opportunities.For example, developers can through the use of the product we create achieve his work?This interface can be achieved really?If we ask others to use the API, they will be, what kind of feeling?
Through the design and implementation of multiple interfaces and don't release them, should be able to achieve the best API design.Through the review of each interface and test, we will be on how to improve the final product with good insight.
But in practice, this spectacular iterative design is impossible.Few people can have enough time, money, or the patience to continuously design and implementation of each can run API.For any interface has certain complexity, this way of iterative design takes up too much of your time.
A more reasonable way early in the design process is iterative, these early design should have enough details, can show the best opportunity to improve, but without excessive design lead to the difficulty of implementation.As time goes on, we can gradually increase the degree of detail (or fidelity), and finally get a complete implementation.
The design process of the gradual in design has been very popular, it is often broken down into three important stages:
1. The sketch design
2. The prototype design
The powerful function of sketch design
Sketch design is to design a universal behavior.The famous architectFrank GehrySketch is famous all over the world, that gave birth to a specially described the sketchesThe movie.Many of his architectural projects from painting in a pile of paper began a series of sketches.Gehry always painted hundreds of such sketches, each time to design one step closer to the well.
Interaction designersBill VerplankDescribed as the sketch designThe first step in the design process is necessary。Bill BuxtonAlso wrote an entire book to introduce the sketch
design method of the value of user experience design, and that its key characteristic is that it can be abandoned, and in all the way to explore is one of the lowest cost.
The sketch design process is included in the API in the early stages of design process, let us have a chance to experience the conceptual model of the interface.It is not only a defined our mind has the idea of a good opportunity, also gives us the opportunity to explore new roads, and put forward the "what if...?"Such a question, and gradually to the real innovation.
Good sketch should be easy to create, and can be arbitrarily discarded.If you create these sketches spent a lot of time, or difficulty is too high, so you cannot discard them.This can abandon sex is very important, it gives us the opportunity to withstand risks.
We can through the sketch design to try different types of interface style, and catch the flash of abstract concept in our mind.Once these thoughts, we can review and discussion on them.Decision in the process we like it or not a particular concept, then after digesting this knowledge tostart the process again, and draw a new sketch.
For users outside of the design team, they rarely to evaluate sketches.Not only because of prematurely to verify this hypothesis is of no value, and it can take in the actual project of user testing times are limited.Through the real user testing each sketch the idea of the price too high, and harvest this way is very limited.
Use file to design sketch
To use API of sketch designarchives(profile) orYuan language(meta language) is a very practical way.File provides a series of concepts, can be used in the design of the sketch.A good archives can analogy for box and line, through it to create various sketch system diagram.These elements are designers and evaluators to be able to understand the content, it makes easier to quickly develop sketch.
In fact, working on the API sketch design process there is a good method, the most obvious is to define the interface list of words.What word is the user must know?Which words can best express the purpose of your target audience and mission?By answering these questions, and create a vocabulary interface, will help you form an early sketches of the interface.
File the beauty of, it provides us with a formal way to share and reuse of this type of information.For example, when westarted to design may be from oneXML structureExtract the word in the document, fromschema.orgTo obtain a glossary, or from
aALPSorRDFDocumentation for information, it depends on our demand.
Design stage, the goal is not to create a comprehensive vocabulary, on the contrary, the early vocabulary is only astarting point, we canstart with this map out other types of details.We may find a list of the 20 or so words can capture the essence of the interface, this list can be as ourstarting point.
This glossary provides a basis for us, we canstart from it for resources with the associated design sketches of API, content may include a URI, correlation between resource name, resource, link text, and other structured and navigation elements.Please note again, it is not necessary to draw sketches of all of the details, our goal is to express the most important part of the API.
The most important point is that the original sketches need not too deep.Please try to avoid, for example, at this stage will go deep into the modeling error stream, or response message elements of design.These parts can join it later, or can be specialized sketch design for them.
A separate sketch without having to reflect the whole interface, in fact, some specially designed for details sketch way may be more practical.For example, we can design a sketch basic error stream, it is associated with the entire API, or designing a draft of the response message format, this format can be applied to all the response.After the prototype design stage, we can apply these ideas into a working model.
The prototype design
In the prototype design stage, we will have the opportunity to interface design for a model with higher fidelity, and some assumptions of draft design stage for validation.A good API prototype should be can call, it should be able to deal with real request message, and provide response when necessary.Developers should be able to even through the use of the prototype API, create a simple application.
However, create a prototype should be lower than the cost of a complete
implementation.There is a way to keep a low cost, namely the simulation of the response message, rather than by the backend system output real response message.This way, sometimes referred to as the interface of fiction (mocking), it is a good way to establish a rapid prototyping.
No matter use which kinds of method to establish the prototype, the point is to find a suitable investment scope, able to support the subsequent iterations.We should be able to based on sketches to create two to three different prototype, and continuous learning in the process.According to the content we learned in the prototype design stage, we may even return the sketch design phase, and try a new direction.
Through prototype, your team will have the opportunity to get early for the design of user feedback, and to look at the real usage.If the interface of fidelity has reached certain level, you can make a potential users to create applications, and for them to look at the challenges in implementation phase.
Responsible for implementing members should also join the prototype evaluation process.A well-designed API should not only easy to use, as well as sustainable, reliable, high performance, and lasted for a long time.While the interface itself should not be exposed to internal details with the server architecture, data model but the implementer to tell the design team to provide some reference Suggestions, such as the limitation of operating environment, as well as the cost of implementation.
Design cycle is a scientific and technological process, and this chance, you should take the prototype stage in the change is not too late to do assumption for validation.
The implementer of the task is to a prototype interfaces into a can safely for the actual application of the product.To deliver a safe, reliable, and scalable implementation is a big challenge, the process itself also need to experience a kind of special design process.
The final prototype, and describes the interface should be supportive sketch show, they reflect the all design decisions, and formed a specification, illustrates the specific need to create what kind of products.In fact, you can use a formal interface description language (or saidIDL), the transition from prototype stage naturally to the implementation stage.
For example, if you are satisfied with the prototype of the API, you can choose to aAPI BlueprintDocument (orSwagger、RAML、WADL, or any other one of the most suitable for
your format) to describe the work environment.
Although this goal is to achieve a stage, but also should not stop design steps.This stage is a good opportunity, let you through the use of real data to the whole design process of hypothesis for further verification.As prototyping API allows us to observe the usage is same, after the implementation of the API allows us to use in a macro situation is analyzed.
For example, you might want to have done to you before design assumption for validation.Application developers really are using you created for them to operate convenient?Do you attract the type of user you expect?Whether the new user when using certain parts of the interface in trouble?
Through the analysis, you maystart a sketch design process, interface to prepare for further improvement.
Through the tools to implement process automation
The use of tools and techniques will greatly improve the entire design process.Those who can decrease the cost of sketches and prototype creation tools can make the design team in a shorter period of time to create more details, make a design decision making is improved.
For most of the design process, tools and the introduction of automation is an important part.In the world of architectural design,SHoP(a architects in New York) is through the innovation, cooperation, and based on the tool design a success.Their process is introduced in the prototype tool, can reflect the physical properties of materials used for designers.This approach allows them to create thousands of design iteration, in each iteration can reflect easy to assess the implementation details.
In the world of API design, this kind of optimization based on tool has very good performance.In fact, in the field of the service description, there are already some excellent Web API design tools.
Interface description language can also provide supporting tool, to simplify the writing tasks described, it is very common now.The editor tool can shorten the design based on IDL
creation time, so in a shorter period of time to create more description becomes easier.Swagger, RAML and Blueprint provides excellent editing tools to support their own language.Even if like WADL IDL issued only as a specification, also can fromSoapUISuch tools to benefit.
ApiaryProvide Blueprint language editor has very strong competitiveness, because it provides a complete set of workflow tools to support the design process.As long as the Blueprint to write a simple API descriptions, designers can evaluate the document and, calling the prototype, and analyze the calling process.
However, most of the existing tools are limited to the description language support.Designers must understand the grammar of the IDL, and design of interface in the language.Although this design style to attract users familiar with programming language, but also limit in the early days of the sketch design phase valuable abstraction and experimental way of thinking.
With IDL and its corresponding tools of these characteristics, they are very suitable for the prototype design process, but for the early sketches design experimental activities practicality is not high.
Use visual tools to design sketches
People tend to use visual tools to help them to interest in API design is heating up.These tools are not directly support edit IDL behavior, but for designers to fiddle with a visual display interface.
The visual modeling tool provides an interface description language, the language most about painting, or based on the graphic.Although this view limits the interface accuracy, but it can also let the designers at a high level view of the whole this interface.This brings opportunities to improve, and this opportunity is often not obvious in written form.
Easy-to-use visual editor is also a good alternative to automate sketch design, it combines lo-fi degrees, abstract and can abandon sexual characteristics, this is what we need.
I participated in the development of a namedRapido!Visual modeling tool, used for the sketch design of auxiliary API.Rapido limit users to the details of a low degree, this is not the side effects, but itself is such a design.Users can use it for files and navigation elements as well as the response data modeling, but cannot be used to design or dynamic response of the logical process.
When designersstarted to create a new Rapido project, they need to design a vocabulary for API.After getting an initial list of words (or import from outside a ALPS vocabulary), designers can in a hypermedia canvas began to design a conceptual model for API, create resource, try to URI name even link state.
In the end, the designer can implement for each resource of sketches or condition of static response message, to increase the fidelity.Finally, when the sketch design phase is complete, the design can be exported into IDL format, ready to import high fidelity tools in the prototype stage.
Rapido's goal is in the field of Web API design provides a fast drawing sketch of "cocktail napkin" type of experience.If you choose the proper fidelity, applying too strong and there is no limit, so it can become an important part of the API design tool chain.
Success in the iterative process
If you follow the way described in this article to iterate style design, then you will be for the team the opportunity to bring a design efficient API.In the beginning of the process of creating multiple lo-fi degrees of design and evaluation, to cultivate the experimental ability and design ability.Then create a high-fidelity prototype, and the realization of the virtual, to evaluate the design ideas of the early.Finally, for realizing the overall design of real users and get the data to analyze the use of practical application.
Iterative design process and project specific details depends on your environment, need how much detail, how many times of iteration, and what are the evaluation technology, will be left to the designer to answer these questions.But as a general rule of thumb, with the passage of your design process, the number of iterations should be reduced gradually, and need to put more effort in terms of evaluation.
Good API design process provides you with an opportunity to create the best interface.But the secret of creating excellent API is not that the guidance of experts or what mysterious knowledge, but rather a through good tools, language, and the application of files by optimizing iterative process.Using this formula the delivery of the API will help your organization achieve success.