- The Elements of Web API Design
- API Design Is Communication
- Reviewing the Principles of Software Design
- Resource-Based API Design
- Resources Are Not Object or Domain Models
- Resource-Based APIs Exchange Messages
- The Principles of Web API Design
- Summary
This chapter is from the book
This chapter is from the book
This chapter is from the book
Reviewing the Principles of Software Design
Software design focuses on the organization and communication of software components within a codebase. Techniques such as code comments, sequence diagrams, and the judicious use of design patterns help improve the communication effort among team members.
Web API design builds on these principles of software design, but with a broader audience that extends beyond the team or organization. The scope of communication expands beyond a single team or organization to developers all over the world. Yet, the same principles of software design apply to Web-based API design: modularization, encapsulation, loose coupling, and high cohesion. While these may be subjects familiar to most developers, they are fundamental to API design and need review before approaching any API design process.
Modularization
Modules are the smallest atomic unit within a software program. They are composed of one or more source files that contain classes, methods, or functions. Modules have a local, public API to expose the functionality and business capabilities that they offer to other modules within the same codebase. Modules are sometimes referred to as components or code libraries.
Most programming languages support modules through the use of namespaces or packages that group code together. Grouping related code that collaborates into the same namespace encourages high cohesion. Internal details of a module are protected through access modifiers provided by the programming language. For example, the Java programming language has keywords such as public, protected, package, and private that help to encourage loose coupling through limited exposure of a module.
As more and more modules are combined, a software system is created. A subsystem combines modules into a larger module in more complex solutions, as shown in Figure 1.1.
)
Figure 1.1 Modules combine into ever-larger units, resulting in a software system.
Applying the same concepts of modularization to Web-based API design helps to reveal the boundaries and responsibilities of every API. This ensures clear responsibilities across complementary APIs that focus on externalizing digital capabilities while hiding the internal implementation details. Consuming developers benefit by understanding the API quickly and effectively.
Encapsulation
Encapsulation seeks to hide the internal details of a component. Scope modifiers are used to limit access to a module’s code. A module exposes a set of public methods or functions while hiding the internal details of the module. Internal changes may occur without impacting other modules that depend on its public methods. Sometimes encapsulation is referred to as information hiding, a concept applied to software development since the 1970s by David Parnas.
Web APIs extend this concept a bit further. They hide the internal details of programming language, choice of Web framework, the classes and objects of a system, and database design behind an HTTP-based API. Internal details, encapsulated behind the API design, encourage a loosely coupled API design that depends on messages rather than underlying database design and models for communication. No longer do organizations need to understand all the internal implementations details, such as for a payment gateway. Instead, they only need to understand the operations that the API offers and how to use them to achieve the desired outcomes.
High Cohesion and Loose Coupling
High cohesion is a term used when the code within a module is all closely related to the same functionality. A highly cohesive module results in less “spaghetti code,” as method calls aren’t jumping all over the codebase. When code is scattered across the entire codebase, calls frequently jump across modules and back again. This style of code is considered to exhibit low cohesion.
Coupling is the degree of interdependence between two or more components. Tightly coupled components indicates that the components are very constrained by the implementation details of the other. Loosely coupled components hide the components’ internal details away from others, restricting the knowledge between modules to a public interface, or programming language API, that other areas of the code can invoke.
Figure 1.2 demonstrates the concepts of high cohesion and loose coupling within and across modules.
)
Figure 1.2 Loose coupling and high cohesion are fundamentals of modular API design.
Web APIs extend these concepts by grouping related API operations for high cohesion while ensuring that the internal details are encapsulated to encourage a loosely coupled API design.