Refactorings by Stakeholder Concerns

Click on the table entries for quick access. We also have a Refactorings by Smells index.

This index lists refactorings by the stakeholder concerns they address (Show / Hide all details):

Agility 

  • Segregate Commands from Queries  (Show Details ) (Hide Details )

    Read operations and write operations may evolve at different speeds. For example, data analytics queries may often change, driven by client demand and insights just gained, while commands to modify master data might only change with major releases, if at all.

Auditability 

  • Encapsulate Context Representation  (Show Details ) (Hide Details )

    In multiprotocol scenarios, end-to-end security guarantees can only be given and enforced when the information in protocol headers is aggregated and correlated somehow. System and process assurance auditors appreciate if all relevant compliance information can be found in a single place (that is adequately protected) [@Julisch:2011].

Client Information Needs 

  • Add Wish List  (Show Details ) (Hide Details )

    APIs are often used by multiple clients with different information needs, which makes it difficult for their providers to offer one-size-fits-all solutions.
  • Add Wish Template  (Show Details ) (Hide Details )

    As motivated in Add Wish List, APIs are often used by multiple clients with differing information needs, which makes it difficult for providers to offer one-size-fits-all solutions. Some clients may require overviews of information elements, for instance list of identifiers, others may require a few or all of the data fields/attributes of these elements that the API is able to provide.

Cohesion 

  • Introduce Data Transfer Object  (Show Details ) (Hide Details )

    API providers strive for low coupling and high cohesion in their endpoint, operation, and message designs.
  • Merge Endpoints  (Show Details ) (Hide Details )

    See Wikipedia entry and SEBoK v. 2.4 for explanation of this general term.
  • Merge Operations  (Show Details ) (Hide Details )

    Cohesive design elements (here: API operations in an endpoint) belong together naturally because they share certain properties. In an API design context, the security rules that apply are an example of such a property. Cohesion is desirable because it makes the system easier to understand and maintain. ISO/IEC/IEEE 24765 [@ISO24765:2017] defines cohesion as “manner and degree to which the tasks performed by a single software module are related to one another.”

Compatibility 

  • Introduce Version Identifier  (Show Details ) (Hide Details )

    Explicit versions, possibly introducing breaking changes, might appear costly and anti-agile or not RESTful at first glance. However, fixing bugs caused by not knowing about versioning mismatches is often expensive.

Cost 

  • Relax Evolution Strategy  (Show Details ) (Hide Details )

    Less code to be maintained over time means less maintenance costs. Sometimes, a planned (or managed) obsolescence approach is followed. Tighten Evolution Strategy also discusses this concern.
  • Tighten Evolution Strategy  (Show Details ) (Hide Details )

    Effort comes with cost. Operational and capital expenditure, including budget for training, evolution (including documentation), and operations increase as lifetime guarantees are extended.

Coupling 

  • Extract Information Holder  (Show Details ) (Hide Details )

    Systems and components evolve at different speeds. Hence, they should not depend on each other unless this is justified in the business requirements. Data dependencies often introduce unwanted coupling that is difficult to detect and resolve.
  • Introduce Data Transfer Object  (Show Details ) (Hide Details )

    API providers strive for low coupling and high cohesion in their endpoint, operation, and message designs.
  • Merge Endpoints  (Show Details ) (Hide Details )

    See Wikipedia entry and pattern summary of Loose Coupling.
  • Merge Operations  (Show Details ) (Hide Details )

    In our context, coupling is a measure of how closely connected and dependent on each other endpoints and their operations are. The coupling may concern the data exchanged and/or the operation call sequencing. See Wikipedia entry for Coupling and Loose Coupling pattern for general explanations.

Data Access Characteristics 

  • Introduce Pagination  (Show Details ) (Hide Details )

    In principle, the client wants to access all data elements, but not all have to be received at once or every time. For example, older posts to a social media site might be less relevant than recent ones and can be retrieved separately.
  • Make Request Conditional  (Show Details ) (Hide Details )

    API clients might use caching and do not want to retrieve data they already have.

Data Currentness 

  • Extract Information Holder  (Show Details ) (Hide Details )

    Data returned by an API might age at different rates. In the e-commerce shop scenario, for instance, the master data of customers (e.g., names, shipping addresses) will change less frequently than transactional data (such as orders). API clients might want to cache some of the data retrieved, which is harder if faster-changing data is embedded in slower-changing data.

Data Parsimony 

  • Add Wish List  (Show Details ) (Hide Details )

    Overall response time, throughput, client-side and server-side processing time are qualities that concern API clients and their providers. Unused data that is prepared, transported, and processed wastes resources and ought to be avoided.

Data Privacy 

Developer Experience 

  • Bundle Requests  (Show Details ) (Hide Details )

    Bulk/batch uploads might be prepared by iterating through a data set and then sending API operation calls for each entry in the set. It might be easier to prepare a single technical request message (for instance, a JSON array) that contains several business-, domain-, or application-level requests instead of having to manage the state (running, succeeded, failed) of all individual requests on the client side.
  • Encapsulate Context Representation  (Show Details ) (Hide Details )

    Accessing protocol headers is different from accessing message payload; different local APIs and/or platform-specific libraries have to be used. Consolidating information in the payload reduces the learning and implementation effort.
  • Inline Information Holder  (Show Details ) (Hide Details )

    An API that provides clients all the required data with as few requests as possible may be easier to use than an API where the client has to issue many requests and requires complex state management on the client side to keep track of multiple API calls. See the blog post API Design Review Checklist: Questions Concerning the Developer Experience (DX) for hints on improving the developer experience.
  • Introduce Data Transfer Object  (Show Details ) (Hide Details )

    API clients want to navigate the required data with minimum effort, taking as few coding steps (expressed as statements and expressions) as possible.
  • Introduce Version Identifier  (Show Details ) (Hide Details )

    Since Version Identifiers can be placed in protocol headers (in most protocols) or in the message payload, additional learning and decision making is required. Accessing protocol headers differs from accessing payload in terms of code to be written, tool and library support, and portability.
  • Introduce Version Mediator  (Show Details ) (Hide Details )

    Breaking changes in APIs and pressure to upgrade may frustrate client developers, especially if they must migrate to a newer version on short notice. For instance, cloud application developers sometimes have to react rather quickly to changes introduced by their public providers.
  • Make Request Conditional  (Show Details ) (Hide Details )

    Knowing when and how long to cache which data might be challenging for API clients and providers. Permanent or temporary storage is required. These valid concerns have to be balanced with the desire for performance.

Development Velocity 

  • Segregate Commands from Queries  (Show Details ) (Hide Details )

    Read operations and write operations may evolve at different speeds. For example, data analytics queries may often change, driven by client demand and insights just gained, while commands to modify master data might only change with major releases, if at all.

Evolvability 

  • Add Wish List  (Show Details ) (Hide Details )

    The information needs of clients and users vary over time, and an API and its provider-side implementation should not have to be adjusted every time something changes in its clients. Maintaining several variations of the same operation for different clients is possible but increases the maintenance effort and coordination needs, which in turn might constrain the flexibility of the API provider.
  • Extract Information Holder  (Show Details ) (Hide Details )

    Systems and components evolve at different speeds. Hence, they should not depend on each other unless this is justified in the business requirements. Data dependencies often introduce unwanted coupling that is difficult to detect and resolve.
  • Introduce Data Transfer Object  (Show Details ) (Hide Details )

    API providers want the freedom to change the API implementation without revealing such changes to clients. Such information hiding [@Parnas:1972] is crucial for the independent evolvability of API providers and clients.
  • Introduce Version Mediator  (Show Details ) (Hide Details )

    To evolve an API, providers must have the flexibility to refactor, redesign, and adapt an API over time. Ideally, this happens without breaking compatibility, but this is not always realistic.
  • Split Operation  (Show Details ) (Hide Details )

    Operations that follow the single responsibility principle are easier to maintain and evolve, for instance, because their API provider only has a single reason to change their request and response message structure and content when evolving the API. Changing an operation that does many things is unnecessarily complex if the change only affects certain aspects of the operation; unexpected side effects may occur. For example, deprecating the operation is more complicated if it has multiple stakeholders.

Explainability 

  • Merge Endpoints  (Show Details ) (Hide Details )

    Fewer endpoints might be easier to understand and maintain — if they are cohesive and do not contain too many operations. The refactorings Move Operation and Rename Operation explain the quality attributes maintainability and understandability further.
  • Merge Operations  (Show Details ) (Hide Details )

    There are many reasons to change an API (not just refactorings) [@StockerZimmermann2021]. APIs should be changed as much as required and as little as possible, and ripple effects be avoided. One of the first steps in related maintenance tasks is to determine which parts of the system should be changed. An API whose endpoints have clearly identified roles helps developers to quickly understand the API.
  • Rename Endpoint  (Show Details ) (Hide Details )

    A good name expresses what an endpoint has to offer, which helps clients decide whether and how to use it. Rename Operation has more explanations of this quality.
  • Rename Operation  (Show Details ) (Hide Details )

    All stakeholders involved in development and operations should be able to grasp what an API is supposed to do (and actually does) with ease; it should be straightforward to teach API usage. On the contrary, educated guesses and implicit assumptions are likely to cause misunderstandings that lead to technical risk and defects later on.
  • Rename Representation Element  (Show Details ) (Hide Details )

    A well-chosen name expresses what a representation element (such as a JSON object with its properties) has to offer, which helps clients decide whether and how to use it. The named element has a single meaning and purpose.

Flexibility 

  • Add Wish List  (Show Details ) (Hide Details )

    The information needs of clients and users vary over time, and an API and its provider-side implementation should not have to be adjusted every time something changes in its clients. Maintaining several variations of the same operation for different clients is possible but increases the maintenance effort and coordination needs, which in turn might constrain the flexibility of the API provider.
  • Add Wish Template  (Show Details ) (Hide Details )

    Client information needs change over time, but an API and its implementation should not have to be updated every time a client does. Maintaining multiple variants of the same operation for different clients is possible, but increases maintenance cost and coordination effort, which in turn can limit the flexibility of the API provider.
  • Introduce Version Mediator  (Show Details ) (Hide Details )

    To evolve an API, providers must have the flexibility to refactor, redesign, and adapt an API over time. Ideally, this happens without breaking compatibility, but this is not always realistic.
  • Relax Evolution Strategy  (Show Details ) (Hide Details )

    Not having to maintain different versions in parallel makes the provider team more flexible, but limits the options client developers have. Again, Tighten Evolution Strategy features this quality as well.
  • Segregate Commands from Queries  (Show Details ) (Hide Details )

    Keeping the read and write operations of an endpoint together is easy to understand and brings functional endpoint cohesion. A separation of these types of operations increases the ability to change them independently from each other; this can then happen more flexibly and more frequently.
  • Tighten Evolution Strategy  (Show Details ) (Hide Details )

    The more lifetime guarantees are given and the longer the committed time spans are, the less freedom remains with respect to changing product vision and corresponding API designs (for instance, the role of an API in the organization).

Green Software 

  • Add Wish List  (Show Details ) (Hide Details )

    Overall response time, throughput, client-side and server-side processing time are qualities that concern API clients and their providers. Unused data that is prepared, transported, and processed wastes resources and ought to be avoided.
  • Extract Information Holder  (Show Details ) (Hide Details )

    Assembling, transferring, and processing a response utilizes resources both on the provider and client side. These resources should not be wasted but handled with care and respect for the environment and the energy consumed. Bandwidth and computing power are examples of valuable and costly resources.
  • Inline Information Holder  (Show Details ) (Hide Details )

    Both API clients as well as providers are interested in keeping the latency and bandwidth usage low and using as few resources as possible.
  • Make Request Conditional  (Show Details ) (Hide Details )

    Response, throughput, and processing times concern API clients and providers. Unused data that is prepared, transported, and processed wastes resources, which should be avoided.

Independent Deployability 

  • Extract Operation  (Show Details ) (Hide Details )

    Endpoints can be deployed and then scaled separately, which is one of the defining tenets of microservices-based systems [@Zimmermann:2017]. The fewer operations an endpoint exposes, the easier it is to optimize the scaling for those operations.
  • Move Operation  (Show Details ) (Hide Details )

    Architectural principles such as single responsibility and independent deployability can guide the selection of refactoring. Some are affected positively, others negatively. The POINT principles for API design (purposeful, style-oriented, isolated, channel-neutral, and T-shaped) belong to this category; moving an operation to another endpoint can improve P, O, and I (but might harm T when looking at a single endpoint and not an entire API). Some principles might be style-defining (for instance, statelessness of interactions in REST), which makes it even more important to adhere and stick to them during design and evolution.

Information Hiding 

  • Introduce Data Transfer Object  (Show Details ) (Hide Details )

    API providers want the freedom to change the API implementation without revealing such changes to clients. Such information hiding [@Parnas:1972] is crucial for the independent evolvability of API providers and clients.

Interoperability 

  • Encapsulate Context Representation  (Show Details ) (Hide Details )

    Less protocol-specific functionality means fewer changes are required when one protocol is replaced by another.

Learnability 

  • Encapsulate Context Representation  (Show Details ) (Hide Details )

    Accessing protocol headers is different from accessing message payload; different local APIs and/or platform-specific libraries have to be used. Consolidating information in the payload reduces the learning and implementation effort.
  • Merge Operations  (Show Details ) (Hide Details )

    There are many reasons to change an API (not just refactorings) [@StockerZimmermann2021]. APIs should be changed as much as required and as little as possible, and ripple effects be avoided. One of the first steps in related maintenance tasks is to determine which parts of the system should be changed. An API whose endpoints have clearly identified roles helps developers to quickly understand the API.
  • Rename Endpoint  (Show Details ) (Hide Details )

    The more expressive and meaningful a name is, the easier it is to navigate through the code base, for instance when searching for them while fixing bugs and adding features. Move Operation has more explanations of this quality.
  • Rename Operation  (Show Details ) (Hide Details )

    All stakeholders involved in development and operations should be able to grasp what an API is supposed to do (and actually does) with ease; it should be straightforward to teach API usage. On the contrary, educated guesses and implicit assumptions are likely to cause misunderstandings that lead to technical risk and defects later on.
  • Rename Representation Element  (Show Details ) (Hide Details )

    A well-chosen name expresses what a representation element (such as a JSON object with its properties) has to offer, which helps clients decide whether and how to use it. The named element has a single meaning and purpose.

Maintainability 

  • Add Wish Template  (Show Details ) (Hide Details )

    Client information needs change over time, but an API and its implementation should not have to be updated every time a client does. Maintaining multiple variants of the same operation for different clients is possible, but increases maintenance cost and coordination effort, which in turn can limit the flexibility of the API provider.
  • Introduce Version Identifier  (Show Details ) (Hide Details )

    There are many reasons to change an API (besides quality refactorings [@StockerZimmermann2021]). It should be changed as much as required and as little as possible, and ripple effects be avoided. One of the first steps in related maintenance tasks is determining which system parts should be changed. The impact of the major and minor changes on other parts should be kept at a minimum, but it is worth communicating when such changes occur.
  • Introduce Version Mediator  (Show Details ) (Hide Details )

    Fewer components and/or code paths that handle deprecated behavior make an API and its implementation easier to maintain for the provider.
  • Move Operation  (Show Details ) (Hide Details )

    There are many reasons to change an API (not just refactorings) [@StockerZimmermann2021]. APIs should be changed as much as required and as little as possible, and ripple effects be avoided. One of the first steps in related maintenance tasks is to determine which parts of the system should be changed. An API whose endpoints have clearly separated concerns and distinguished roles helps developers to quickly understand the API.
  • Relax Evolution Strategy  (Show Details ) (Hide Details )

    Reducing the number of versions that run in production and reducing their lifetime guarantees reduces the maintenance effort. See Tighten Evolution Strategy for more explanations.
  • Rename Operation  (Show Details ) (Hide Details )

    APIs should be changed as much as required and as little as possible, and ripple effects be avoided; source code and documentation on client and provider side using a particular name have to be updated if this name changes. Expressive operation names help with orientation during API evolution. Debugging and trouble shooting is also easier if logs and error reports contain meaninfgul names.
  • Rename Representation Element  (Show Details ) (Hide Details )

    The more expressive and meaningful a name (for instance, the key in a key-value pair) is, the easier it is to search and navigate the code base, for instance, when fixing bugs and adding features during API evolution. Split Operation covers this quality in more detail.
  • Split Operation  (Show Details ) (Hide Details )

    Operations that follow the single responsibility principle are easier to maintain and evolve, for instance, because their API provider only has a single reason to change their request and response message structure and content when evolving the API. Changing an operation that does many things is unnecessarily complex if the change only affects certain aspects of the operation; unexpected side effects may occur. For example, deprecating the operation is more complicated if it has multiple stakeholders.
  • Tighten Evolution Strategy  (Show Details ) (Hide Details )

    During their lifetimes, API versions have to be supported and evolved. Security patches are applied, bugs are fixed, and so on. The effort for such activities might not be proportional to the guaranteed lifetime but certainly is related and somewhat coupled to it. Related (sub-)concerns are compatibility and extensibility.

Modifiability 

  • Encapsulate Context Representation  (Show Details ) (Hide Details )

    Less protocol-specific functionality means fewer changes are required when one protocol is replaced by another.
  • Introduce Data Transfer Object  (Show Details ) (Hide Details )

    API providers want the freedom to change the API implementation without revealing such changes to clients. Such information hiding [@Parnas:1972] is crucial for the independent evolvability of API providers and clients.

Offline Support 

  • Inline Information Holder  (Show Details ) (Hide Details )

    When the connection is unstable or if one wants to build offline functionality into an app, one large request is often better than many small ones.

Performance 

  • Add Wish List  (Show Details ) (Hide Details )

    Overall response time, throughput, client-side and server-side processing time are qualities that concern API clients and their providers. Unused data that is prepared, transported, and processed wastes resources and ought to be avoided.
  • Add Wish Template  (Show Details ) (Hide Details )

    Response time and throughput are qualities that concern both API clients serving end users and API providers (also explained in Add Wish List). Preparing, transporting, and processing data but not using it on the client side wastes resources and ought to be avoided.
  • Bundle Requests  (Show Details ) (Hide Details )

    Transferring many small requests may stress network and communication endpoints preparing requests and consuming them (for instance, on HTTP or TCP/IP level).
  • Extract Information Holder  (Show Details ) (Hide Details )

    Assembling, transferring, and processing a response utilizes resources both on the provider and client side. These resources should not be wasted but handled with care and respect for the environment and the energy consumed. Bandwidth and computing power are examples of valuable and costly resources.
  • Inline Information Holder  (Show Details ) (Hide Details )

    Both API clients as well as providers are interested in keeping the latency and bandwidth usage low and using as few resources as possible.
  • Introduce Pagination  (Show Details ) (Hide Details )

    Transferring all Data Elements at once can lead to huge response messages that burden receiving clients and the underlying infrastructure (i.e., network and application frameworks as well as databases) with a high workload. For instance, single-page applications that receive several megabytes of JSON might freeze until all contained JSON objects have been decoded.
  • Make Request Conditional  (Show Details ) (Hide Details )

    Response, throughput, and processing times concern API clients and providers. Unused data that is prepared, transported, and processed wastes resources, which should be avoided.
  • Segregate Commands from Queries  (Show Details ) (Hide Details )

    Computationally expensive workloads such as loading data from data stores, filtering, and formatting it, and high data volumes may make certain operations expensive. Such complex query operations should not slow down cheaper operations exposed by the same endpoint (for example, atomic updates of single attribute values).

Reliability 

  • Extract Operation  (Show Details ) (Hide Details )

    Independent endpoints that do not share the same execution context and resources can be deployed independently; operations co-located in a single endpoint, however, share their deployment characteristics. For instance, if a long-running operation causes an API provider-internal error, its sibling operations might suffer from quality-of-service degradations as well. [@Nygard:2018] uses the term stability: “A robust system keeps processing transactions, even when transient impulses, persistent stresses, or component failures disrupt normal processing.”
  • Move Operation  (Show Details ) (Hide Details )

    When co-located in a single endpoint and deployed jointly, operations might influence each other. For instance, if one of these operations is long-running or causes a provider-internal error, its siblings might suffer from quality-of-service degradation too.

Resource Utilization 

  • Introduce Pagination  (Show Details ) (Hide Details )

    Transferring all Data Elements at once can lead to huge response messages that burden receiving clients and the underlying infrastructure (i.e., network and application frameworks as well as databases) with a high workload. For instance, single-page applications that receive several megabytes of JSON might freeze until all contained JSON objects have been decoded.

Scalability 

  • Extract Operation  (Show Details ) (Hide Details )

    Endpoints can be deployed and then scaled separately, which is one of the defining tenets of microservices-based systems [@Zimmermann:2017]. The fewer operations an endpoint exposes, the easier it is to optimize the scaling for those operations.
  • Move Operation  (Show Details ) (Hide Details )

    When co-located in a single endpoint and deployed jointly, operations might influence each other. For instance, if one of these operations is long-running or causes a provider-internal error, its siblings might suffer from quality-of-service degradation too.
  • Segregate Commands from Queries  (Show Details ) (Hide Details )

    Computationally expensive workloads such as loading data from data stores, filtering, and formatting it, and high data volumes may make certain operations expensive. Such complex query operations should not slow down cheaper operations exposed by the same endpoint (for example, atomic updates of single attribute values).

Security 

  • Encapsulate Context Representation  (Show Details ) (Hide Details )

    In multiprotocol scenarios, end-to-end security guarantees can only be given and enforced when the information in protocol headers is aggregated and correlated somehow. System and process assurance auditors appreciate if all relevant compliance information can be found in a single place (that is adequately protected) [@Julisch:2011].
  • Extract Information Holder  (Show Details ) (Hide Details )

    Not all API clients have the same access privileges. More fine-grained data Retrieval Operations make it easier to enforce related controls and rules, avoiding the risk that restricted data “slips through” accidentally. To revisit the e-commerce scenario, what if the shop software also includes public ratings of products that show the name and picture of the rating customer? Here, only limited and carefully selected information about the customer should be returned.
  • Extract Operation  (Show Details ) (Hide Details )

    With multiple operations co-located within a single endpoint, it can be challenging to enforce fine-grained access control policies. Refactoring this endpoint into multiple specialized ones allows for more granular control over access permissions and authorization rules. The security requirements for the data an API endpoint exposes may also differ; hence, separating operations can make it easier to apply data protection measures that ensure confidentiality.
  • Segregate Commands from Queries  (Show Details ) (Hide Details )

    Read and write operations might have different protection needs. Few user roles, for instance, are usually authorized to update master data; many or all user roles may read it. If there are two separate endpoints for read and write access, it might be easier to fine-tune the Confidentiality, Integrity, and Availability (CIA) rules and related compliance controls. See the OWASP API Security Top 10 for risks and related advice on API security.
  • Split Operation  (Show Details ) (Hide Details )

    Access restrictions of an API can be implemented on different levels: whole API, per endpoint, individual operations, or even depending on the executed control flow paths in the implementation of operations or the data accessed. Securing an operation that does many things is complex. The access control list must include the superset of all involved participants; changing it has a significant impact.

Simplicity 

  • Make Request Conditional  (Show Details ) (Hide Details )

    Knowing when and how long to cache which data might be challenging for API clients and providers. Permanent or temporary storage is required. These valid concerns have to be balanced with the desire for performance.
  • Segregate Commands from Queries  (Show Details ) (Hide Details )

    Keeping the read and write operations of an endpoint together is easy to understand and brings functional endpoint cohesion. A separation of these types of operations increases the ability to change them independently from each other; this can then happen more flexibly and more frequently.

Single Responsibility Principle 

  • Extract Operation  (Show Details ) (Hide Details )

    Architectural principles are affected positively or negatively when APIs are refectored. Here, the Purposeful, style-Oriented, Isolated, channel-Neutral, and T-shaped (POINT) principles for API design apply; extracting an endpoint can improve P, O, and I (but might harm T when looking at a single endpoint and not an entire API).
  • Move Operation  (Show Details ) (Hide Details )

    Architectural principles such as single responsibility and independent deployability can guide the selection of refactoring. Some are affected positively, others negatively. The POINT principles for API design (purposeful, style-oriented, isolated, channel-neutral, and T-shaped) belong to this category; moving an operation to another endpoint can improve P, O, and I (but might harm T when looking at a single endpoint and not an entire API). Some principles might be style-defining (for instance, statelessness of interactions in REST), which makes it even more important to adhere and stick to them during design and evolution.
  • Split Operation  (Show Details ) (Hide Details )

    An API that offers endpoints with operations that follow the single responsibility principle is easier to understand for clients because operations are focused and do not offer extra capabilities that not all clients use. The API provider team also benefits from a lower complexity of the implementation.

Stability 

  • Extract Operation  (Show Details ) (Hide Details )

    Independent endpoints that do not share the same execution context and resources can be deployed independently; operations co-located in a single endpoint, however, share their deployment characteristics. For instance, if a long-running operation causes an API provider-internal error, its sibling operations might suffer from quality-of-service degradations as well. [@Nygard:2018] uses the term stability: “A robust system keeps processing transactions, even when transient impulses, persistent stresses, or component failures disrupt normal processing.”

Testability 

  • Split Operation  (Show Details ) (Hide Details )

    Test cases have to cover all, and all combinations of, the many things the operation is in charge of. Testing such an operation is more complex than testing a single-responsibility operation.

Understandability 

  • Merge Endpoints  (Show Details ) (Hide Details )

    Fewer endpoints might be easier to understand and maintain — if they are cohesive and do not contain too many operations. The refactorings Move Operation and Rename Operation explain the quality attributes maintainability and understandability further.
  • Merge Operations  (Show Details ) (Hide Details )

    There are many reasons to change an API (not just refactorings) [@StockerZimmermann2021]. APIs should be changed as much as required and as little as possible, and ripple effects be avoided. One of the first steps in related maintenance tasks is to determine which parts of the system should be changed. An API whose endpoints have clearly identified roles helps developers to quickly understand the API.
  • Move Operation  (Show Details ) (Hide Details )

    There are many reasons to change an API (not just refactorings) [@StockerZimmermann2021]. APIs should be changed as much as required and as little as possible, and ripple effects be avoided. One of the first steps in related maintenance tasks is to determine which parts of the system should be changed. An API whose endpoints have clearly separated concerns and distinguished roles helps developers to quickly understand the API.
  • Rename Endpoint  (Show Details ) (Hide Details )

    A good name expresses what an endpoint has to offer, which helps clients decide whether and how to use it. Rename Operation has more explanations of this quality.
  • Rename Operation  (Show Details ) (Hide Details )

    All stakeholders involved in development and operations should be able to grasp what an API is supposed to do (and actually does) with ease; it should be straightforward to teach API usage. On the contrary, educated guesses and implicit assumptions are likely to cause misunderstandings that lead to technical risk and defects later on.
  • Rename Representation Element  (Show Details ) (Hide Details )

    A well-chosen name expresses what a representation element (such as a JSON object with its properties) has to offer, which helps clients decide whether and how to use it. The named element has a single meaning and purpose.
  • Split Operation  (Show Details ) (Hide Details )

    An API that offers endpoints with operations that follow the single responsibility principle is easier to understand for clients because operations are focused and do not offer extra capabilities that not all clients use. The API provider team also benefits from a lower complexity of the implementation.

Usability