Rename Endpoint

Context and Motivation

An API endpoint runs in production and is used by clients. Its build time name and runtime address do not match its domain semantics well.

As an API developer, I want to express the domain concepts exposed by an endpoint and the architectural role that it plays as accurately as possible in the published language and the API contract.

Stakeholder Concerns

#understandability (a.k.a. #explainability, #learnability)

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.

#learnability (readability in particular)

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.

Initial Position Sketch

Let’s assume that an endpoint type called OldCrypticName exists:

endpoint type OldCrypticName
exposes 
  operation operation1 
    expecting payload "SomeRequestMessage"

As the sketch shows, the refactoring targets a single endpoint that contains one or more operations.

Design Smells

REST principle(s) violated

Abstract API endpoints correspond to resources identified by URIs in RESTful HTTP APIs. Their names should convey the meaning and role of the resources. For instance, using verbs as relative paths might be considered an antipattern; resources should be named with nouns that can be traced back to domain entities (note that these entities and their resource representations can be represented as Processing Resources and/or data-oriented Information Holder Resources, both in REST and in APIs leveraging other integration styles).

Cryptic or misleading name

The chosen name is not straightforward to understand or is not part of the domain terminology. It raises wrong, unexpected or undesired associations.

Instructions

This refactoring is rather straightforward to apply.¹ The main task is to find a suited name that balances the desired qualities.

1. Discuss alternative new names and decide for one. Have this decision reviewed and agreed upon.
2. Apply code-level rename refactorings, for instance for the controller class realizing the endpoint.
3. For backward compatibility, a redirect can be implemented. Either at the protocol level (for instance with an HTTP redirect) or at the code level by keeping the old method and calling the new one from it.
4. Update security rules, tests and documentation as well as any address resolution services (gateways, portals, registries, repositories, service meshes).

Target Solution Sketch (Evolution Outline)

The endpoint type is called NewExpressiveName now:

endpoint type NewExpressiveName
exposes 
  operation operation1 
    expecting payload "SomeRequestMessage" 

Example(s)

In the publication management example, an application of the refactoring might go from:

Aggregate APIEndpoint {
    Service JabRefDatabaseFacade {
        Set<@PublicationEntryDTO>lookupPublicationsFromAuthor(String writer);
        ...
    }
}

to:

Aggregate PublicationManagementEndpoint {
    Service PublicationManagementFacade {
        Set<@PublicationEntryDTO>lookupPublicationsFromAuthor(String writer);
        ...
    }
}

The specific name of an open source tool, JabRef, was replaced by a more general, domain-specific name. This reduces the prerequisite knowledge that stakeholders of the name (such as API client developers, but also API implementation maintainers and API product managers and testers) have to have.

Hints and Pitfalls to Avoid

Here is some advice regarding naming:

• Organization-, unit-, or project-wide naming conventions should be considered.
• Strategic Domain-Driven Design might be able to contribute naming suggestions as well.
• Naming collisions with other endpoints should be avoided (even if they are technically possible, which depends on the chosen protocol technology).
• URI templates {id} in HTTP resource APIs also require consistent naming (and these names may appear in multiple places in API specifications and implementations).
• More hints can be found in the Rename Operation and Rename Representation Element refactorings.

Related Content

Rename Operation and Rename Representation Element also address readability, but have other targets.

Refactoring.Guru calls for Clean code and emphasizes that poor names make code difficult to grasp.

“The Art of Readable Code” [Dustin Boswell 2011] contains many helpful hints on naming program elements that also apply to APIs.

References

Dustin Boswell, Trevor Foucher. 2011. The Art of Readable Code. O’Reilly Media, Inc.

1. assuming that the used tools (including IDEs, API contract editors, and test tools) support consistent find-and-replace across files, and do so conveniently and reliably ↩