带有管理视图的 REST API 设计

Question

I have API application with endpoints:

/api/v1/accounts
/api/v1/accounts/id

API have authorization with roles (user, admin). Users can mark accounts as visible or hidden. If account is hidden then it's not visible in search ( /api/v1/accounts ) but want to allow search for admin in "user mode" (where hidden are hidden) and "admin mode" (where hidden are visible too). User can see their account even if its marked as hidden

What is the best way to achieve it? Add a parameter to detect if it's admin to every endpoint or create separated endpoints? (eg. /api/v1/accounts and /admin/api/v1/accounts ). If I'm using mediator pattern shoud make separate queries/commands for admin (single principle responsibility) or keep in one? I'm searching best solution form my problem

Answer 1

This is very opinionated question so no answer will be complete or single point of truth. I'm writing this, because the information is too much to fit into the comment section and I think I could provide you with some good guidelines in order to make the best decision for you.

I will also express my own opinion so you should have this in mind as well.

That being said, first of all I see that you are using .NET-Core and C# which kind of outlines one of the options that you have. Since at least ASP.NET MVC 3 we have the option to use areas which I feel will give you the behavior you want using the .NET way sort of speak. You can read about areas in .NET Core here and here is a short quote:

Consider using Areas in a project when:

• The app is made of multiple high-level functional components that can be logically separated.
• You want to partition the app so that each functional area can be worked on independently.

So the pros are that:

• You get out of the box routing in the form of /admin/accounts/...
• In the future if you need to add additional admin functionalities you can easily keep them separated which will make your code cleaner and easier to maintain

However I personally am not big fan of this approach. First it seems a little bit artificial to me. Usually you end up with 95% duplicated code and some small adjustments and at the end it's very questionable if the extra code that you need to maintain is worth the benefits that you get from this extra separation.

Maybe areas are viable options after all, but only if you have quite a lot of functionality that you can encapsulate inside it so that you get some real benefit.

Conclusion : You are able, and if you decide to resort to /admin/accounts/... solution I advice you to consider the area usage but I personally would not go there.

Second option You may not complicate the project that much and just provide some extra routes to handle your specific needs. The problems with that are several I will outline those:

• Very often the exception became the norm. Now you need some extra functionality for the admins, after some time you will need something for the managers..
• Your resource identifiers will become very inconsistent, and even though it's not very professional I think it would be somewhat ugly to have such routes in your app.

Event though you are not obliged to make your services RESTful it would help if you follow some of the constraint that REST apply.

First, request should be stateless:

Each request from client to server must contain all of the information necessary to understand the request

In other words all that logic, that you are describing in your question, the request should contain the data that the server will need to return the correct response. In more practical terms I'm speaking about something like JWT where you can the Claims to pass that additional information about the user so the server can fetch you the correct data.

Second, Uniform interface :

REST is defined by four interface constraints: identification of resources; manipulation of resources through representations; self-descriptive messages; and, hypermedia as the engine of application state.

In your case, I think this is the most important constraint identification of resources To get the desired resource you don't actually need the admin part, it's part of the business logic of your application who can see what and all the information that the server need to fetch the correct data should be inside the request and not the URI.

Conclusion : I think that you should extend your request with some additional data in order to let the server perform the business logic and keep the routes as they are now.

HOWEVER As you can see, things like areas exist and the people in Microsoft are much better API designers than me and you so there is no black/white answer here.

Hope at least I managed to give you some food for thought.