Design – API – How to handle scope based functionality

aspect-orienteddesigndesign-patternsseparation-of-concerns

TLDR;

Where and possibly how should I implement scope based logic in the
example code?

I have got a ASP.NET Web Api.

The Api uses OData (on top off REST) for data endpoints and OAuth 2.0 authentication.
Now I want to add functionality to handle an Access Token in several different scopes.

Some of the scopes are:

User
Organization
Customer

The result set the API returns should be based on this scope.
The same applies if someone wants to add, update or delete an entity.

Now take for example the following endpoint:

http://myapi/Employees

Someone with a Token in the Organization scope does a GET and should only get the employees that are in the Organization that is defined within the Token. An user in the Customer scope should get the employees for all organizations within the customer defined in the Token. This functionality however is not available for someone with a Token in the User scope.

The same applies to a POST. Someone within the organization scope should only be allowed to add a new employee to his own organization.

The functionality for the different scopes will usually only differ a little bit.
In the case of getting the employees the difference is only a where on organization or otherwise on customer. In the case of a post their should be a check to see if for example the organization is part of the customer that is bound to the customer Token.

Current implementation:

Currently we have a base ApiController which is generic typed.
The base controller calls an Query or CommandHandler with the entity type and all the implementation details are inside this handlers.

ApiController

public abstract class ApiController<TEntity> : EntitySetController<TEntity, Guid>
    where TEntity : class, IApiEntity
{
    protected readonly IQueryProcessor QueryProcessor;
    protected readonly ICommandProcessor CommandProcessor;

    protected ApiController(IQueryProcessor queryProcessor, ICommandProcessor commandProcessor)
    {
        this.QueryProcessor = queryProcessor;
        this.CommandProcessor = commandProcessor;
    }

    [HttpGet]      
    public override IQueryable<TEntity> Get()
    {
        var command = new GetEntityCommand<TEntity>();
        return this.QueryProcessor.Process(command);
    }
}

EmployeeController

public class EmployeeController : ApiController<Employee>
{ }

GetEmployeeHandler

public class GetEmployeeCommandHandler : IQueryHandler<GetEntityCommand<Employee>, IQueryable<Employee>>
{
    public IQueryable<Employee> Handle(GetEntityCommand<Employee> command)
    {    
         // Code that knows how to get a collection of employees.
         // This collection contains all employees
    }
}

PostEmployeeHandler

public class PostEmployeeCommandHandler : ICommandHandler<PostEntityCommand<Employee>, Employee>
{
   public Employee Handle(PostEntityCommand<Employee> command)
    {    
         // Code that knows how to add an employee to the database.
    }
}

The question

Where and possibly how should I implement the scope based logic?
I know there has to be a smart way to do this and a good place to implement this scope based logic, I just don't see it (yet).

Best Answer

I strongly suggest that you put this scope logic inside your data schema design (SQL tables for example). Don't do filtering. The reason is mainly scalability.

When there are so many data items, you don't want to ask the DB to load them all, and then you apply scoping on these items in memory. You overload the DB with extra work, and memory too.
Database can query items with scoping parameters (query optimizers work very well for SQL) much better. You will have better speed.
Using the DB will also help you avoid lot of problems with transaction and concurrency.

Related Solutions

Injection Framework – What is Required for a Scope in an Injection Framework?

Limit the use of scopes or more concretely Use scopes for wiring only.

Used properly, scopes can reduce a lot of factory boiler plate. I use scopes to wire together sub-processes that may need access to its name and arguments. This is similar to the RequestScopes provided by Guice and Spring.

But scopes are effectively a thread-local map of string to object. This is practically a Global Variable Depot. This is why I limit my scope usage.

This leads to the corollary:

Hide the scopes or more generally Hide your DI Framework

Because scopes (and DI frameworks) are essentially Global Variable Depots, I prefer to encapsulate the DIF such that the only thing that knows there is a DIF is the main method.

To do this, I define my own scope interface and my own ProcessFactory that I define within a Guice module.

Because of this, my process manager is free of references to Guice. In fact, it is little more than this method:

void run(final ProcessContext context) {
    try {
        this.scope.enter(context.processArgs());
        this.factory.create(args.processName());
    } finally {
        this.scope.exit();
    }
}

Here's the complete Guice module that binds and hides my use of a Guice. It implements my own ProcessScope and ProcessFactory interfaces. It binds @ProcessParameters so they can be injected and a few convienience objects as well (@ProcessName String and ProcessConfig).

public class ProcessRunnerModule extends AbstractModule {
    private static final String PROCESS_RUN_SCOPE = "ProcessRunScope";

    /**
     * Objects of type Map<String, Object> parameterized by @ProcessParameters
     * are injected in the ProcessRunScope
     */
    static final Key<Map<String, Object>> PROCESS_PARAMETERS_KEY;
    static {
        final TypeLiteral<Map<String, Object>> MAP_TYPE = new TypeLiteral<Map<String, Object>>() {
        };
        PROCESS_PARAMETERS_KEY = Key.get(MAP_TYPE, ProcessParameters.class);
    }


    /**
     * Wraps Guice scope to ProcessScope. Injects the @ProcessParameters into guice
     */
    private static class GuiceScopeAdapter implements ProcessScope {

        private final SimpleScope scope;

        @Inject @SuppressWarnings("unused")
        public GuiceScopeAdapter(@Named(PROCESS_RUN_SCOPE) SimpleScope scope) {
            this.scope = scope;
        }

        @Override
        public void enterScope(Map<String, Object> parameters) {
            scope.enter();
            scope.seed(PROCESS_PARAMETERS_KEY, parameters);
        }

        @Override
        public void exitScope() {
            scope.exit();
        }
    }

    /**
     * Processes are run and bound in @ProcessRunScope.
     */
    protected void configure() {
        final SimpleScope processRunScope = new SimpleScope();
        bindScope(ProcessRunScope.class, processRunScope);
        bind(SimpleScope.class)
            .annotatedWith(Names.named(PROCESS_RUN_SCOPE))
            .to(processRunScope);
    }

    /**
     * This wraps Processes bound via MapBinder to a ProcessFactory
     */
    @Provides @Singleton
    ProcessFactory createProcessFactory(final Map<String, Provider<Process>> processFactories) {
        log.info("Instantiating process factory", "known-processes", processFactories.keySet());
        return new ProcessFactory() {
            @Override
            public Process create(final String name) {
                return processFactories.get(name).get();
            }
        };
    }

    /**
     * ProcessRunner does not know about Guice
     */
    @Provides @Singleton
    ProcessRunner createProcessRunner(
            final ProcessScope processScope,
            final ProcessFactory processFactory) {

        return new ProcessRunner(processScope, processFactory);
    }


    /**
     * Convienience: bind a @ProcessName extracted from the @ProcessParameters
     */
    @Provides @ProcessName @ProcessRunScope
    String bindProcessName(final @ProcessParameters Map<String, Object> params) {
        return params.get(ProcessRunner.PROCESS_NAME_KEY).toString();
    }

    /**
     * Convienience: bind a ProcessConfig wrapping the @ProcessParameters
     */
    @Provides @ProcessRunScope
    ProcessConfig createParamHelper(final @ProcessParameters Map<String, Object> params) {
        return new ProcessConfig(params);
    }
}

Class Design – Structuring an Online Web Store

Your company has products it sells to customers. It does this through line-item records on invoices which associate a product and a quantity to the invoice. A typical schema might look something like this:

enter image description here

Best Answer

Related Solutions

Injection Framework – What is Required for a Scope in an Injection Framework?

Class Design – Structuring an Online Web Store

Related Topic