Welcome To Nirmalya!×
Feel Free to Contact us
Skip to main content

In today's digital world, business resources play a crucial role in enabling seamless interactions between systems and providing valuable insights into a business domain. Designing robust and efficient APIs for these resources is essential for creating a self-service real-time federated data platform. In this article, we will explore the design patterns that can be applied to develop business resource APIs that are scalable, composable, and developer-friendly.

  1. REST model serves as a blueprint for designing business resources and defining how client systems interact with them. It specifies the paths, methods, and response types for accessing and manipulating resources. By adopting the REST architectural style, businesses can enhance interoperability and support independent deployment of components. As Roy Fielding, the creator of REST, stated, "REST provides a set of architectural constraints that emphasizes scalability, generality of interfaces, and independent deployment of components."
  2. While business resource APIs should be developer-friendly and easy to integrate, it is important to remember that the system-of-record business service owns the model and the vocabulary. The upstream service is responsible for maintaining the integrity and coherence of the data. However, by embracing microservices architectures and REST, businesses can offload choreography responsibilities to the client system. This enables the creation of stable, genericized interfaces for business resources, allowing client systems to integrate seamlessly without tight coupling to external teams.
  3. Composability, cohesion, and stability are vital aspects of a REST model abstraction. These principles align closely with the Domain Driven Design process, which aims to distill the core domain and create a simple set of interfaces that align with the ubiquitous language. To strike a balance between composability and cohesion, it is crucial to refine the domain model and ensure that the object representing the business capability aggregate root is not overly complex. The REST model should provide granularity without being superfluous to the needs of client systems.
  4. Sub-resources are resources that are existentially dependent or subordinate to a parent resource. They can provide key insights into an existentially linked peer resource or contain additional information about the parent. By modeling sub-resources within the same API specification as the parent, businesses can benefit from improved readability, clarity, and context conveyed by the API path. Sub-resources also enable composability and allow for granular retrieval of data, reducing over-fetching and controlling the impact of changes.
  5. Sometimes, significant domain processes cannot be adequately represented by entities or value objects alone. In such cases, it makes sense to add standalone interfaces declared as services, known as affordances. These affordance operations capture important state-lifecycle transitions that may not naturally fall under the responsibility of a specific entity or value object. By incorporating affordances into the API model, businesses can ensure clarity and provide clear context for actions performed on a resource.
  6. Not every client system requires access to all the information provided by a business resource API. To avoid over-fetching and enhance composability, it is beneficial to implement a parameter-driven filtering model. This model allows clients to specify field and collection filters when retrieving data, ensuring they receive only the information they need. By using query parameters and field selection, businesses can provide greater control over the size and content of the response payload.

Designing APIs for business resource management is a complex task that requires careful consideration of composability, cohesion, and usability. By following the design patterns outlined in this article, businesses can create scalable and composable APIs that provide valuable insights into their business domain. Embracing REST, leveraging sub-resources, and incorporating affordances and filtering mechanisms can enhance the developer experience and enable seamless integration with client systems.

Integrate People, Process and Technology