A lot of work needs to be done to implement the API. Excessive planning can be a waste of energy, and its lack leads to disastrous consequences. In this book you will receive solutions that allow you to allocate the necessary resources and achieve the required level of efficiency in the optimal time. How to balance flexibility and performance while maintaining reliability and ease of configuration? Four experts from the API Academy explain to software developers, product and project managers how to maximize the value of their APIs by managing interfaces as continuous life-cycle products.
The material of the book is based on our collective knowledge (Mehdi Mejuy, Eric Wilde, Ronnie Mitra, Mike Amundsen) over many years of creating, developing and improving the API - both our own and others. It sets out all our experience. We identified two key factors for effective API development: the need for a product-oriented approach and the formation of the right team. We also identified three important factors for managing this work: leadership, product development, and API system development.
These five elements form the foundation on which to build a successful API management program. We introduce the reader to all of these topics and provide guidance on how to fit them into the context of your organization.
Excerpt. API Systems
With the growing functionality of the API, it is becoming increasingly important to manage developing programs so that the benefits and value of the entire set of organization APIs grow as much as possible. You need to remember this balance, because the best (or relatively good) way to provide an individual service using the API may not be so useful if you look at it from the point of view of ease of use of this service as part of a common system.
Modern API systems are constantly growing in terms of the total number of APIs, as well as the number of APIs used by new services. Given this increase in interdependencies, we understand that it would be useful if the developers of new services did not have to understand completely different API designs and apply them. The differences can be dramatic — for example, whether the API uses a REST or an event-oriented style (see the “Design” section of the “Getting to Know the Pillars” section of Chapter 4) —but even if the styles match, differences like the use of the JSON format can be detected or XML.
From an API user perspective, it would also be useful to have a common terminology. For example, if you use several APIs that provide user data in any form, it will be easier if they all have one main user model (even if it is presented slightly differently, nevertheless it is useful to have a common model for different services) .
The idea of the benefits of standardization clearly demonstrates that the more, the better. To some extent it is, but at the same time it’s known that standardization takes time and resources, it usually does not come down to “the only true and best model”, but simply creates a model with which everyone can somehow come to terms , and therefore, in general, this investment has both risks and advantages.
Perhaps the use of a unique format for each API will not be the best solution, it is more reasonable to choose from existing ones, for example, JSON or XML. In this case, the benefits of applying existing standards outweigh the likely benefits of unique formats. However, it can be very expensive to standardize some elements of different services, for example, the already mentioned user model. In this case, it is logical not to go to such unjustified expenses for the sake of searching for the only true user model and just dwell on the domain model.
Generally speaking, ideally for each service, we want not to reinvent the wheel when it is not necessary, but to reuse those design elements that reduce the cost of resources for creating a design, its understanding and implementation. If we can achieve such an ideal level of re-application, or at least get closer to it, this will allow service creators to focus on those aspects of design that need to be focused on, without being distracted by problems already solved.
We see that more and more organizations are doing just that. But the most important thing in this is to understand and make sure that the manuals for designers are constantly updated: new methods are evaluated and approved, old methods come out of circulation, and the main driving force behind these changes is the constantly evolving set of API methods in the organization.
It is important to understand that the API system is a mobile and constantly changing environment, and for it to continue to work, the architecture must follow the same path of continuous development. Then it becomes like a very large-scale system, for example, the Internet, which, on the one hand, works all the time, and on the other hand, is constantly changing and new standards and technologies are constantly appearing in it.
Archeology API
Although we now see a large number of organizations that are just starting to create programs with APIs, it is important to remember that in any organization that used information technology, there are almost certainly some APIs that have been used for a long time.
Based on the definition, an API is any interface that allows two software components to interact. If you narrow down the definition to a modern understanding of the network API, then this is any interface that allows two software components to interact through the network.
In many organizations, such interfaces are not called APIs, and they are not designed to be reused (remember the story about the famous API charter of Jeff Bezos, which we told in the Bezos Charter subsection of the Design Thinking section of Chapter 3). But most often, these interfaces exist even if they were created and used for integration only for a single use (undermining this one of the main useful properties of the API - the possibility of reuse).
Finding and applying such proto-APIs can be useful because it shows where the need for integration appeared (even if it was created using methods that did not meet the goals of the API). Not all of these proto-APIs should be replaced with conventional APIs, but just by understanding the history, you can get ideas about how the need for integration was observed, what was done in this area and where the need for additional integration may appear.
PROTO API
The need for the interaction of components exists in all complex systems consisting of separate parts. An API is one way of doing this, but there are many others. From the point of view of the API, any mechanism used for the interaction of components that is not an API can be considered a proto-API. In an ideal system, using the API, all component interactions are performed without exception. If you remember this ideal image, any interaction without the help of the API becomes a candidate for modernization - to be replaced with an API. Therefore, any mechanism for the interaction of components without the help of an API can be considered a proto-API.
In general, API archeology can help you better understand the API system, even if it now consists mainly of proto-APIs. It provides a starting point for understanding the need for integration that has arisen in the past, and for which API investments you can best unravel the problematic network of many user integrations. With experience and over time, replacing integrations created before the advent of the API with modern models is becoming ever easier.
API management on a large scale
Large-scale API management is the balancing act between introducing a common design at the system level and maximizing the freedom of design choices at the individual API level. Choosing between centralized integration for consistency and optimization and decentralization for flexibility and development is a common problem in a complex system.
- Centralized integration has brought us the typical enterprise IT architecture of the past. The main driving force was the standardization of the execution of functions in order to provide them optimally and with minimal cost. A high level of integration really simplifies optimization, but at the same time affects the ability to make changes and develop the final system.
- Decentralization is the opposite. The most accessible and large-scale example of it is the Internet. The main driving force here is the standardization of access to functions so that you can provide them in many different ways that are constantly evolving. At the same time, the functions remain available, since access is based on general agreements on the interaction of functions. The main goal of decentralization is to weaken the coherence ( http://bit.ly/2FpcUpf ), that is, to facilitate changes in individual parts of the overall system without the need to change other parts.
DECENTRALIZATION AND EXECUTION
If we learned something from the incompletely fulfilled promises of the time of a service-oriented architecture based on SOAP, then carefully managed execution is a key aspect of implementing service-oriented prospects. SOAP fulfilled the promise of providing access to functions, but did not cope with the equally important task of properly managing the execution of functions. Thus, although SOAP was useful (functions that were previously unavailable appeared as services), it did not meet the needs of a more flexible and evolving environment.
The complexity of managing the API system is to remember this problem and avoid the trap that SOAP has fallen into. SOAP said that only the availability of services is important. This was an important first step, but it did not allow to cope with the weak coherence of functions. The APIs and, if you focus specifically on implementation and deployment techniques, microservices allow us to rethink what is important for large service systems and how to create systems that do not fall into the SOAP trap.
Platform principle
Many talk about platforms, discussing APIs and main business goals. However, they may mean completely different things. It is important to remember: if at the business level it seems a good idea to create something as a platform, this does not mean that this is how it should be developed at a technical level.
At the business level, the platform provides something on which to build something, and we cannot go deeper than this rather vague wording. Often the attractiveness of the concept of “platform” is influenced by two main factors.
- What is the platform coverage? That is, how many users can be reached by creating something on this platform? This is usually determined by the number of users or subscribers. Often this is the most important parameter, calculated by the total number or by using qualitative factors that determine the right users, which can be covered using this platform.
- What features does this platform have? If you create something on it, how does it help you or limit you in terms of income? And is it also easy to change the platform to add new features, ideally without harming its users?
These parameters are very important for business, but there is a factor that is often forgotten: platforms always force users to adhere to certain restrictions, but they do it in different ways. Here are some examples.
- Web applications can be used by anyone and anything that meets basic network standards. In the simplest case, this is a modern browser with scripting support. Anyone can create them and open access to them, and anyone can use them. There is no central element that controls the operation of the web platform.
- Applications on Apple's App Store are similar in appearance to web applications, but are provided and used in completely different ways. They can only be downloaded from the App Store, so Apple has the exclusive right to decide what users can install. In addition, they can only be launched on iOS devices, that is, Apple has a monopoly on the sale of devices that are capable of using these applications. Applications in the App Store are created specifically for the iOS environment, that is, investments in their creation are limited only by this platform. To use the application on any other platform, including the Internet, it must be reproduced in a different development environment and even in a different programming language, which means: the client side of the application must be recreated from scratch.
You can apply this pattern to both API systems and the idea of creating an API platform for applications.
Sometimes, the API platform refers to a specific environment that provides access to the API. Soon, it begins to slightly resemble the traditional enterprise service bus, where a similar platform should provide the infrastructure, and the APIs become accessible due to the fact that they can use it.
In other cases, when talking about the API platform, they mean a common set of principles used and provided by services. In this case, if the service becomes part of the platform, it has nothing to do with where and how access is opened to it. If services adhere to the same principles, protocols, and templates, they provide APIs on this platform and thus become part of the API system.
The second type of platform is more abstract, but at the same time it has more features. Separating what functions perform and how they do it, it facilitates the contribution of users to the platform. It also opens up many paths for innovation, allowing applications to experiment with implementation methods without compromising their ability to contribute to the API system.
And again, take the Internet as an example. If you look only from the point of view of the API, it allows a lot to change over time. For example, a Content Delivery Network (CDN) is not integrated into the Internet itself. Its existence was made possible due to the complexity of the content of the Internet and the flexibility of the browser, which allows you to generate web pages based on several sources taken, possibly from different places. One might argue that the potential for creating a CDN already existed in the principles and protocols of the very first web pages, but the CDN template only appeared when it arose.
It is this ability to adapt to new tasks that is required in API systems. We design a system based on open and extensible principles and protocols, but we can and want to change it if necessary. We are also creating support templates that help applications more efficiently solve problems, and we want to develop these templates over time.
Principles, Protocols, and Templates
The main conclusion from the previous section: the platform should not require one specific way to do something (answer the question “How?”) Or one specific place (answer to the question “Where?”). A good platform is created for the continuous development of architecture, that is, the architecture of the platform (and not just the architecture of the product) is constantly evolving, and not all is developed at once, so that later it remains unchanged all the time of its existence.
CONTINUOUS ARCHITECTURE DEVELOPMENT
Continuous architecture development is a technique for the continuous development of the fundamentals of product architecture. Individual products are created using existing architecture frameworks, and reports on the application of these frameworks can improve product architecture, making it more efficient.
A flexible development methodology and DevOps are dedicated to improving the development of individual products. They do not talk about how to improve the basics of this process so that a more efficient system architecture is useful for the product architecture. Continuous development occurs when individual products are created in the working environment of an existing system. The system makes it easier to create new products, and they help the system find areas for improvement, thereby creating a feedback loop.
Continuous architecture development focuses on developing a framework that does not harm existing products and allows the creation of product combinations. Ideally, the basics of architecture are constantly evolving so as to be compatible with previous versions, so the operation of the system is almost not disrupted.
For continuous architecture development to be possible, the platform must be built on principles, protocols, and templates. We can illustrate this point with a web platform. It has long been known that the Internet is incredibly stable and flexible at the same time. Over the past 30 years, its basic architecture has not changed, but, of course, has evolved markedly. How did this clear contradiction become possible? After all, other systems encounter problems much faster, moving along less radical trajectories.
One of the main reasons is that nothing on the Internet shows how a particular service is implemented or activated. Services can be implemented in any language, and, of course, they change over the years, because programming languages also change. They are provided using any working environment - at first it was the servers located in the cellars, now located on the Internet itself, and recently, cloud storage has also appeared. Services can be used by any client program - they also have changed dramatically from simple command-line browsers to complex graphical browsers on modern mobile phones. Focusing solely on the interface, which determines how information is recognized, exchanged and demonstrated, the architecture of the Internet turned out to be better adapted to natural growth than any complex IT system we have seen. The reasons for this are surprisingly simple.
- Principles are fundamental concepts built on the very foundation of the platform. In the case of the Internet, one of these principles is that resources are recognized by uniform resource identifiers (URIs), and then the URI-recognizing protocol gives permission to interact with these resources. Thus, although we can (at least in theory) go to the Internet without HTTP (and in a sense we are already moving because the protocols everywhere are changing to HTTPS), it is difficult to imagine that it is possible to go to the Internet without resources. The principles are reflected in the styles of the API, because the styles are based on different fundamental concepts.
- Protocols define specific interaction mechanisms based on fundamental principles. Although most of the interactions on the Internet are now based on the Hypertext Transfer Protocol (HTTP), a small fraction of the traffic also relates to the file transfer protocol (FTP) and more specialized protocols such as WebSockets and WebRTC. An agreement on the protocol makes interoperability possible, and careful development of the platform allows the protocol system to also evolve, which we are now observing with HTTP / 2 as an example.
- Templates are constructions of a higher level. They explain how interactions across possibly several protocols are combined to achieve application goals. One example is the widespread Oauth mechanism, which is a complex HTTP-based template designed to achieve a specific goal - three-step authentication. Templates are ways to solve common problems. They can be protocols, like Oauth, or methods, like the CDN example above. But, like protocols, over time, templates evolve, new ones are added, and old ones are deactivated and go down in history. Templates are general methods for solving problems in the space of solutions established by principles and protocols.
Often, patterns evolve over time to meet changing requirements. For example, browser-based authentication was relatively widespread at the dawn of the Internet because it could be easily controlled using the server configuration and it worked well for relatively simple scenarios of the time. But with the growth of the Web, the limitations of this approach became apparent, authentication support became a standard feature in all popular web programming frameworks, and this more flexible approach replaced the previous authentication method through a browser.
It is important to remember that this feedback loop is responsible for the success of the Internet. Platform architecture begins with simple solutions. Applications appear, and some of them expand the boundaries of what the platform supports. If there is demand, new features and functions are added to the platform, and this facilitates the creation of new applications using these functions. It is the responsibility of the platform architects to observe exactly where the applications push the boundaries, help developers cross them and develop the platform to better meet the needs of developers.
In API systems, the same evolution of methods takes place. And it is not a problem that should be seen in it, but a feature, because as teams learn and new templates appear, and sometimes even protocols, methods can be tuned and improved. The secret to successful API programs is to approach them as continuously evolving, develop and manage them so that this evolution continues.
API systems as language systems
Each API is a special language. It consists in the interaction of those who provide the service and who use it when a certain function appears. But it is important to remember that in this section the term “language” refers to interactions with the API, that is, to its design, and not to the internal work of the API, that is, its implementation.
Some aspects of the language of a separate API are solved at a fundamental level.
- The API style defines the basic dialog templates (e.g., synchronous request / response or event-based asynchronous) and basic restrictions. For example, in the RPC-based API, the key abstract concept of dialogue is the request for a function, while in the REST-based API, dialogue is based on the concept of resources.
- Then the API protocol defines the basic mechanisms of the language. For example, in an HTTP-based API, when managing the basics of a conversation, HTTP header fields will definitely be important.
- Within the API protocol, there are often many technological sub-languages in the form of extensions to the underlying technology. For example, there are now about 200 HTTP header fields ( http://webconcepts.info/concepts/http-header/ ), although the basic standard defines only a small set of them. APIs can choose which of these sublanguages they will support based on the needs of their dialogue.
- Certain aspects of the API may belong to different areas, and they can be reused in several APIs (for more details, see the section called “Dictionary” on page 188). As an example: these reusable parts of the API can be called data types, then refer to them and use them in different APIs so as not to reinvent the wheel.
The main conclusion from the above is that language management is an important part of system management. As with all systems, managing languages is a difficult task. If they are too much unified, users of the system will feel constrained and will not be able to express themselves the way they want. If you do not try to encourage the emergence of common languages, many solutions to the same problem will appear in the systems and they will become very complex.
One of the most common API system management patterns is to promote language reuse with a stick rather than a stick.
- The whip method is characterized by a small team of leaders deciding which languages should be involved, and then announcing that other languages are prohibited. Usually this decision comes from above, and it becomes difficult to experiment with new solutions and apply new techniques.
- The gingerbread method allows you to offer any language for reuse if tools and libraries are associated with it that can make life easier for users. Thus, the language must prove its usefulness. It also means that you can add a language to the list, demonstrating its usefulness.
Using the gingerbread method, the set of proposed languages will and will develop over time. If new languages arise, new ways must also appear to prove their usefulness, and if that works out, they are also added to the list.
As a result, languages can “fall into disgrace” due to the emergence of more successful competitors or due to the fact that users simply started using a different method of work. This has long been happening in the field of XML / JSON. Although there are many XML services, now the default choice for the API is JSON (and in a few years, maybe we will see how it is gradually being replaced by another technology).
Express an API through an API
Scaling the API assumes that when the time comes to expand, you already have a plan to automate the growing number of tasks for individual APIs and for the system. Automation requires a precise definition of how access to information is opened and the ability to collect and use it is provided. If you think about it, then the task of opening access to information is the main purpose of the API! This leads us to the main mantra of expressing an API through an API: "Everything you want to say about an API needs to be expressed using this API."
Thus, we get acquainted with the idea that an important part of the scalable management of the API system revolves around the idea of using the so-called API for the infrastructure (or, more precisely, the infrastructure component in existing APIs). A very simple example of such an API for the infrastructure is a way to demonstrate API status information. If each API conforms to a standard template (more on this in the Dictionary section of the Eight Aspects of API Systems section below), automating the task of collecting information about the status of all APIs is very easy. To simplify, it looks something like this.
- Start by taking an inventory of currently active service instances, check each one every 10 minutes.
- Start from the start pages of services, follow the link with the word status to find information about their status.
- Collect status information from each service and process / visualize / archive it.
In this scenario, it is easy to write a script that regularly collects this information, and based on it, create tools and new ideas. This is made possible because the API component is the standard way to access certain aspects of the API.
Now we understand that the management of the API system and its development partly depends on the development of ways to use the API for such automation, when necessary. Using the principles of continuous architecture development, you can add this information over time and modify existing services if necessary.
In this example, the discovery of status information has become a new template and a technique has emerged for applying this information. A new technique can become experimentally feasible if the API uses such categories in design guidelines. In the future, it can go into a state of fading and outdated, when only old services will use it, if at some point the system switches to another way of demonstrating the state of the API.
In the last paragraph, we used the words “experimental,” “marketable,” “fade,” and “obsolete” as possible states of the leadership process. We do not offer you to use this particular set, but it is important to understand that any manual also develops over time. What used to be a good way to solve problems can be replaced by a faster and more sustainable method. Management should help teams decide how to deal with problems. If teams keep track of the state of the techniques, it will become easier for them to understand how they are developing, so it makes sense to keep track of which decisions are successful now, which may become successful in the future, and which were considered successful in the past. In the sections “Leadership Structuring in the API System” and “Leadership Life Cycle in the API System” in Chapter 9, we will discuss specific ways to structure and develop leadership in more detail.
Solving the problem with a method that becomes an API design element simplifies the management of large API systems because certain design elements are repeated among the APIs and can be used for automation.
Understanding of the system
API systems are no different from other systems of products or functions, the purpose of which is to develop easily and almost unhindered and serve as a solid foundation for creating new functions, internal or external. In all these cases, a compromise is reached between optimization for the sake of one known goal and optimization for the sake of facilitating change. Optimization for the sake of facilitating change always requires compromises with fixed goals. The key factors of variability are the openness of the system for evolution and its management in a way that allows you to introduce new ideas into the current state of the system and its dynamics over time.
An important place in this picture is occupied by the thought that we discussed in the previous section: everything that needs to be said about the API must be expressed using the API itself. This can be as simple as providing the state information mentioned earlier, or much more complicated, such as the requirement that all API documentation be part of the API itself, or managing the security of the API through the API itself. With this approach, the APIs switch to self-service, providing access to the information that is needed for their understanding and use.
. , API, , , . , -, .
API API, , , , -. , : , API , , , , .
, API , : API , . : , , API, , .
— API, OAuth.io APIDays — API, . API API, , , API - . API, «API : », 2015 API « ». , - HEC API.
, API . IETF W3C. , , EMC, Siemens CA Technologies.
. API UX , API .
, a renowned writer and lecturer, travels the world, gives advice and lectures on network architecture, web development, and the intersections between technology and society. As the lead developer of the API architecture at the API Academy, he works with companies to help them increase revenue by realizing the opportunities provided by the API to users and the enterprise.
»More details on the book can be found on the publisher’s website
» Contents
» Excerpt
La Habrozhitelami 25% discount on coupon - API
Upon payment of the paper version of the book, an electronic book is sent by e-mail.