DEV Community: Aung Kyaw Minn

API Resource Management and Access Control

Aung Kyaw Minn — Sat, 04 Jan 2025 08:04:31 +0000

In modern API development, resource management and access control are two key pillars for building efficient, secure, and scalable systems. APIs allow users to interact with various resources, and it is crucial to control what actions a user can perform on these resources. This is where the concepts of API Resource Management and Access Control come into play.

In this article, we will explore these concepts by breaking them down into two key areas:

API Resource Management using ICRUD
Access Control with Ability (Action and Subject)

1. API Resource Management with ICRUD

API resource management refers to the fundamental operations that allow users to interact with resources via an API. The ICRUD framework represents the basic actions that can be performed on resources: Index, Create, Read, Update, and Delete. These actions define how data is handled within an API.

In the context of API development, a Resource is typically an entity that users interact with (e.g., User, Article, Product). Below, we break down each action in the ICRUD framework, using User as the example resource.

1.1 Index (Listing Resources)

The Index action is used to retrieve a list of resources. It is often implemented with filtering, sorting, and pagination to optimize the retrieval of large data sets.

Example Use Case:

Action: Index
Subject: User

An Index action would allow an admin or a user to retrieve a list of users.

Example Request:
GET /users?page=2&limit=10

This request would return a paginated list of Users (e.g., 10 users per page, starting at page 2).

1.2 Create (Add Resources)

The Create action is used to add a new resource to the system. For example, a user can be created in the system by an administrator or another authorized party.

Example Use Case:

Action: Create
Subject: User

An admin might create a new User account.

Example Request:
POST /users

The request body would contain details such as name, email, and role for the new user.

1.3 Read (Retrieve a Resource)

The Read action allows retrieving a specific resource by its unique identifier. For example, an admin or authorized user can view the details of a specific User.

Example Use Case:

Action: Read
Subject: User

An admin might retrieve the details of a specific user.

Example Request:
GET /users/123

This request would retrieve the details of the User with ID 123, such as their name, email, and account status.

1.4 Update (Modify Resources)

The Update action allows modifying the data of an existing resource. For example, a user might update their email or profile information, or an admin might update a user’s role.

Example Use Case:

Action: Update
Subject: User

An admin might update the role of a User or modify their profile details.

Example Request:
PUT /users/123

The request body would contain the new details for the User with ID 123, such as a new email address or role.

1.5 Delete (Remove Resources)

The Delete action removes a resource from the system. For example, an admin might delete a User account.

Example Use Case:

Action: Delete
Subject: User

An admin might delete a User from the system.

Example Request:
DELETE /users/123

This request would delete the User with ID 123 from the system.

2. Access Control with Ability (Action and Subject)

While ICRUD defines the basic operations that can be performed on resources, Access Control is concerned with ensuring that users can only perform certain actions on specific resources based on their permissions.

In the context of Access Control, we use the following concepts:

Action: The operation a user wants to perform (e.g., Read, Write, Delete).
Subject: The resource upon which the action is performed (e.g., User, Article, Product).
Ability: The combination of Action and Subject that defines what a user is allowed to do.

2.1 Action

Action refers to the operations that users can perform on resources. Common actions include:

Read: Viewing or retrieving data.
Create: Adding new data.
Update: Modifying existing data.
Delete: Removing data.

In the case of the User resource, actions might include Read User, Create User, Update User, and Delete User.

2.2 Subject

Subject refers to the resource or entity that a user interacts with. Common subjects include:

User
Article
Product
Order

For example, in a User Management System, User is the subject upon which actions like Create User, Update User, and Delete User are performed.

2.3 Ability

Ability defines what a user is allowed to do on a particular subject. A user's Ability is a combination of an Action and a Subject. For example, a user might have the ability to Read User (view user details) but not the ability to Delete User.

2.4 Example of Abilities in Practice

Let’s imagine a system with Admin, Editor, and Viewer roles. Each role has a different set of abilities related to User management.

Admin Abilities:

Read User: View user details.
Create User: Add new users.
Update User: Modify user information.
Delete User: Remove users from the system.

Editor Abilities:

Read User: View user details.
Update User: Modify user information (but not delete users).

Viewer Abilities:

Read User: View user details (but no other permissions).

In this system:

An Admin has full control over users (can Read, Create, Update, and Delete users).
An Editor can Read and Update user information but cannot Delete.
A Viewer can only Read user details.

2.5 Simple Implementing Access Control in Code

In a role-based access control system, we can define these abilities for each user role and check if a user is authorized to perform an action on a resource.

// Define roles and their corresponding abilities
const rolesAbilities = {
  admin: [
    { action: 'read', subject: 'User' },
    { action: 'create', subject: 'User' },
    { action: 'update', subject: 'User' },
    { action: 'delete', subject: 'User' },
  ],
  manager: [
    { action: 'read', subject: 'User' },
    { action: 'update', subject: 'User' },
  ],
  user: [
    { action: 'read', subject: 'User' },
  ],
};

// Function to create a user with specific roles
function createUser(username, roles = []) {
  const abilities = roles.flatMap(role => rolesAbilities[role] || []);
  return { username, abilities };
}

// Function to check if a user has a specific ability
function can(user, action, subject) {
  return user.abilities.some(ability => 
    ability.action === action && ability.subject === subject
  );
}

// Function to add an ability to a user
function addAbilityToUser(user, action, subject) {
  if (!user.abilities.some(ability => ability.action === action && ability.subject === subject)) {
    user.abilities.push({ action, subject });
  }
}

// Example usage:
const adminUser = createUser('adminUser', ['admin']);
console.log(can(adminUser, 'create', 'User'));  // true
console.log(can(adminUser, 'delete', 'User'));  // true

const managerUser = createUser('managerUser', ['manager']);
console.log(can(managerUser, 'create', 'User'));  // false
console.log(can(managerUser, 'update', 'User'));  // true

// Add new ability to a manager
addAbilityToUser(managerUser, 'create', 'User');
console.log(can(managerUser, 'create', 'User'));  // true

In this example, the Admin user has the ability to read, create, update, and delete User resources.

Remarks: Extending Actions and Subjects

The Action and Subject concepts described above—Index, Create, Read, Update, and Delete—are fundamental operations and work well in many common API scenarios. However, in more complex systems, you may encounter situations that go beyond these basic actions.

Here are some extended examples that show how actions and subjects can be tailored to specific operations:

Extended Actions:

Send Email:
- Action: Send
- Subject: Email
- Example: Sending a welcome email to a new user or a notification to a subscriber.
- Ability: A system admin or support agent may have the ability to Send Email to users.
Activate User:
- Action: Activate
- Subject: User
- Example: Activating a user account after registration or email verification.
- Ability: Admin users or support agents may have the ability to Activate User.
Deactivate User:
- Action: Deactivate
- Subject: User
- Example: Temporarily disabling a user’s account, e.g., for maintenance or review.
- Ability: Admins or system operators may have the ability to Deactivate User.
Assign Role:
- Action: Assign
- Subject: Role
- Example: Admins assigning roles (e.g., Admin, Editor, Viewer) to users in the system.
- Ability: An Admin might have the ability to Assign Role to User resources.
Generate Report:
- Action: Generate
- Subject: Report
- Example: Generating a sales report, user activity report, or system performance report.
- Ability: Managers or admins might have the ability to Generate Report.
Approve Order:
- Action: Approve
- Subject: Order
- Example: Approving or rejecting an order in an e-commerce system.
- Ability: A sales manager or order processing team might have the ability to Approve Order.

These extended actions provide additional control and granularity over what operations can be performed on resources. This enables more specific and flexible access control, especially as systems grow more complex.

Conclusion

Understanding API Resource Management and Access Control is crucial for building secure and efficient APIs. By leveraging ICRUD operations, you can manage resources effectively, while Action, Subject, and Ability help you define and enforce fine-grained access control.

ICRUD operations provide the basic actions that can be performed on resources such as User, Article, or Product.
Access Control ensures that users are only allowed to perform certain actions on specific resources based on their assigned abilities.
Extended Actions and Subjects allow for more complex interactions, such as Send Email, Activate User, and Approve Order, making your access control model more flexible.

By combining these concepts, you can create APIs that are both powerful and secure, with granular control over what users can do with each resource.

A Scalable and Maintainable Approach for Laravel Applications

Aung Kyaw Minn — Sun, 29 Dec 2024 15:41:03 +0000

Introducing Mojura Architecture

In the ever-evolving world of web development, maintaining a scalable and readable codebase is crucial. Enter Mojura Architecture, a set of principles designed to enhance your development workflow by promoting scalability, maintainability, and readability. Inspired by the Japanese word "モジュラ" (module), Mojura Architecture breaks down your application into manageable units, making it easier to scale, maintain, and understand.

Key Benefits

Scalability

By breaking down your application into smaller, manageable units, Mojura Architecture allows you to easily scale your project as it grows. This modular approach ensures that each part of your application can be developed and scaled independently.

Maintainability

With a clear separation of concerns, Mojura Architecture makes it easier to maintain and update your codebase. This reduces the risk of bugs and improves overall code quality, making your application more robust and reliable.

Readability

The structured approach of Mojura Architecture ensures that your code is organized and easy to understand. This makes it simpler for new developers to get up to speed and contributes to a more efficient development process.

Concept

Route
- Call Controller functions
Controller
- Serve the Features
- Return Response received from Feature to the Request
Feature
- Validate the Request
- Run the Job by passing the request parameters
- Collect Return Data from Job
- Prepare Response Data
- Return the HTTP Response to the Controller Method
Request
- Authorize the Request (Optional)
- Implement HTTP Request validating
Job
- Do the actual work by implementing the business logic

Principles

Feature Serves a Single Purpose: Keep features simple and focused.
Job Executes a Single Responsibility: Ensure each job handles one responsibility, even if it involves multiple related functions.
Modules Shouldn’t Cross: Each module should be self-contained and should not perform tasks that belong to other modules.
Apply Decoupling Techniques: Use shared helper classes to enhance code reusability and maintainability.
Features Shall Not Call Other Features: Maintain feature independence.
Jobs Shall Not Call Other Jobs: Keep business logic concise and organized.
Write Code That Humans Can Read: Prioritize readability for easier maintenance and collaboration.

Naming Conventions

Consistent naming for files and classes is encouraged for clarity and readability. Here are some examples:

Module: [Subject]Module (e.g., UserModule)
Controller: [Subject]Controller (e.g., UserController)
Feature: [Operation][Subject]Feature (e.g., CreateUserFeature)
Job: [Operation][Subject]Job (e.g., CreateUserJob)
Request: [Operation][Subject]Request (e.g., CreateUserRequest)

Directory Structure

Mojura Architecture promotes a clear and organized directory structure:

laravel-project/
├── app/
│   ├── Modules/
│   │   ├── YourModule1/
│   │   │   ├── Features/
│   │   │   ├── Http/
│   │   │   │   ├── Controllers/
│   │   │   │   └── Requests/
│   │   │   └── Jobs/
│   │   ├── YourModule2/
│   │   │   ├── Features/
│   │   │   ├── Http/
│   │   │   │   ├── Controllers/
│   │   │   │   └── Requests/
│   │   │   └── Jobs/
│   │   ├── YourModuleN/
│   │   │   ├── Features/
│   │   │   ├── Http/
│   │   │   │   ├── Controllers/
│   │   │   │   └── Requests/
│   │   │   └── Jobs/
├── routes/
│   ├── api/
│   └── web/
└── .env

Mojura Laravel Package

A lightweight Laravel Package that implements the Mojura Architecture principles.

Installation

To install the Mojura package into your Laravel 10+ application using Composer:

composer require innoaya/mojura

Configuration

Publish the configuration file:

php artisan vendor:publish --tag=mojura-config

Generating Components

Route: php artisan mojura:route [RouteFileName] [VersionDirectory] [--web] [--force]
Controller: php artisan mojura:controller [Controller] [Module] [Directory] [--force]
Request: php artisan mojura:request [Request] [Module] [Directory] [--force]
Feature: php artisan mojura:feature [Feature] [Module] [Directory] [--force]
Job: php artisan mojura:job [Job] [Module] [Directory] [--force]

Documentation

https://mojura.innoaya.org

Source Code

https://github.com/innoaya/mojura

Starter Kit

This starter kit provides a fully implemented backend solution based on the Mojura Architecture concepts, designed to speed up your development process. It includes robust features for authentication, authorization, user management, and security, making it a comprehensive starting point for building scalable applications.
https://github.com/innoaya/mojura-laravel-starter