How to manage endpoints for CRUD APIs?

Resources and Attributes in a Backend API Structure

• Resource: A resource represents a primary entity or object in the system that typically requires management using CRUD operations (Create, Read, Update, Delete). Examples of resources include Leave, Employee, and Leave-Type. These entities represent business objects that hold meaningful data and often require dedicated endpoints for their lifecycle management.

• Attribute: An attribute, on the other hand, represents specific data points or calculations related to a resource. These are not managed through CRUD operations but are often retrieved through read-only endpoints. Attributes can be things like EmployeeStats, LeaveStats, or OrgLeaveStats, which provide insights or metrics related to a resource but don't have their own lifecycle.

API Structure for a Resource and its Attributes

Below is an example of how both resource APIs and attribute APIs could be structured for a Leave resource.

Resource API Structure: Leave

1. Retrieve all leave for an organization
   
   GET
   
   /leave?orgId=S4F0AXqBCj

2. Retrieve details of a specific leave by ID
   
   GET
   
   /leave/37

3. Create a new leave
   
   POST
   
   /leave
   

   {
     "omId": "S4F0AXqBCj",
     "name": "Sick Leave",
     ...
   }

1. Update an existing leave PUT /leave/37

   {
     "omId": "S4F0AXqBCj",
     "name": "Updated Leave Name"
   }

1. Delete a leave DELETE /leave/37

Resource API Structure: Vote

1. Retrieve all votes for feed of an organization
   
   GET
   
   /voteleave?orgId=S4F0AXqBCj

2. Retrieve details of a specific vote by ID
   
   GET
   
   /vote/37

3. Retrieve details of a specific voter's vote by ID
   
   GET
   
   /vote?fromId=usr123

4. Create a new vote
   
   POST
   
   /vote
   

   {
     "fromId": "S4F0AXqBCj",
     "toId": "S4F0AXqBCj",
     "comment": "Sick Leave",
     ...
   }

1. Undo/ Delete a vote DELETE /vote/voteId123

Attribute API Structure: Leave Attributes

1. Retrieve leave statistics related to leave
   
   GET
   
   /leave?stats=true&orgId=S4F0AXqBCj

2. Retrieve leave statistics related to leave for a particular user
   
   GET
   
   /leave?stats=true&orgId=S4F0AXqBCj&employeeId=123

In this structure:

• Resources like /leave support CRUD operations, allowing you to manage the lifecycle of the resource.
• Attributes like agg or stats provide detailed information or calculations about a resource but don’t allow modifications. These are typically read-only endpoints used to derive insights.

Attributes can be thought of as parameters or calculated values related to a resource. For example, you can retrieve data or perform calculations like statistics through query parameters rather than treating them as separate resources. For instance, querying leave data:

GET /leave?from=X&agg=true

This kind of query allows you to filter or aggregate leave data without needing separate dedicated endpoints like /leave-stats.

The distinction between resources and attributes helps in organizing APIs more efficiently and reducing the need for unnecessary endpoints, ensuring the system remains scalable and flexible.Here’s a refined version of your content for the wiki:

Why Separate Resources from Attributes?

In a well-designed backend API, resources are primary objects that reflect important entities, while attributes are supplemental or derived data points. This separation is important for several reasons:

1. Maintainability and Scalability: By treating resources as core entities and attributes as derived or supplemental, your API becomes more flexible to adapt over time. Resources, which often map to physical entities (like employees or leave types), require full lifecycle management (CRUD). Attributes are lighter and more dynamic, allowing you to add, modify, or remove derived data points (like statistics) without disrupting core functionality.

2. Separation of Concerns: Resources represent entities with clear, independent lifecycles, while attributes, such as statistics, are not entities but calculations or data points derived from resources. For instance, employee-stats or org-leave-stats don't represent standalone entities; they provide insights based on the data of core resources like Leave or Employee. This prevents API bloat, where every tiny piece of data gets its own resource.

3. Efficient Querying: Consider an attribute like leave-stats. Rather than creating a separate resource endpoint for statistics, incorporating it as a query parameter (e.g., leave?stats=true) makes your API more intuitive and prevents over-segmentation. Since the stats are derived from existing resources, it simplifies API navigation while offering flexible options for users to fetch additional data points without needing extra endpoints.

Why employee-stats and org-leave-stats Shouldn't Be Resources

These statistics are derived attributes, not standalone entities. Elevating them to a resource level would clutter the API with unnecessary endpoints that aren't truly representative of core objects. Instead, these attributes should live within their respective resource endpoints.

For example:

• Employee-stats are essentially calculations on employee data. Fetching stats directly from the Employee resource (e.g., employee?stats=true) makes it clear that this is data about employees rather than a separate entity.
• Similarly, Org-leave-stats combines data from the Leave and Organization resources. By querying the Leave resource with specific filters (e.g., leave?orgId=123&stats=true), you extract insights without needing to introduce an unclear hybrid resource like org-leave-stats.

The key takeaway is that resources should represent meaningful, tangible objects in your system, while attributes add flexibility without inflating your API with unnecessary entities.