Single Web API endpoint for all entities, good or bad?

Question

Situation

We are currently developing a large web application (Web API 2) - several entities and thus require several endpoints for each. But suddenly, they changed to "one endpoint fits all" approach, something like:

/api/data?entity=entity_name

Then the usual controller for GET, POST, PUT, DELETE. We have something like this:

public class DataController : ApiController
{
    public HttpResponseMessage Get(string entity)
    {
        Type entityType = Type.GetType(entity);
        var query = HelperClass.GenerateGenericGetMethod<entityType>("GetAll").ToList();
        return Response(OK, query);
    }
}

As you can see, we created some Helper to generate a generic method for Get, GetById and same old same old queries, we will then apply another set of helpers for: stripping down properties to return to the client and other custom actions.

Question

Is this going to cause some overhead to the server? Will it be okay if we scale it all up in the future? (And I'm sure we will) Like add token authentication, user roles, mobile access and more. Would like some insights.

Thanks!

EDIT: I am fairly new to web development and would love to hear some suggestions on what approach would fit our situation best.

Answer 1

I sincerely doubt that Web API 2 would have any problem with a single endpoint. There may be considerations of which I am not aware, but it doesn't seem likely to be the limiting factor.

The real problem with this approach is what it does to the comprehensibility and maintainability of the code, as well as making it easier to trace and debug.

For the first problem is that /api/data?entity=widget is less expressive than, say, /api/widget.

The latter form as less noise and communicates the intent more clearly.

Another factor is the growth of your APIs. If you start with a single retrieval for each, the single entry point may not seem bad. But let's say you start needing to do a couple of queries: widget by ID and widget by name. Your URL string starts to look like /api/data?entity=widget&id=123 or /api/data?entity=widget&name=Frobnitz. Little by little, your Get method starts to accumulate more and more checks to figure out which query you mean, especially if we add a Foo entity that also can be looked up by ID.

In general, you would probably be well-served to read up a little on REST web services and applying some of the general principles (some of the heavier stuff is probably overkill for your situation).

Answer 2

In addition to the OP comment

Yes, that was my point I gave them, but they needed concrete reasons why it will fail in the future

Nobody knows the future. If your model and requirements do not change over the next 100 years, the solution purposed will be a successful one.

Whoever we all know that changes happen. Requirements changes, the business changes and (from my experience) these so generic and abstract collides with flexibility eventually.

For instance, back to your scenario, at some point, everything that does not fit into the query string will be forced to travel through the body and some GETS will turn into POST/ PUT and the grammar of your API will be a little bit convoluted and hard to read.

Will it be okay if we scale it all up in the future? (And I'm sure we will).

It's hard to predict how the approach will impact to the scalability. There're different ways to scale up and all of them depends on different needs and scenarios. So as I have read here many times start little and then scale based on real needs.

However, we can say that technically, the approach has some limitations like the one I have pointed out previously.

Like, add token authentication, user roles, mobile access and more. Would like some insights.

This sort of features can be implemented (and the often are) using the headers of the request and response. The approach exposed might no have an impact.

In addition to @Michael answer.

To use some API RESTful principles will bring some advantages:

• API (syntactically) will be more intuitive
• It will be more "devs-friendly*. These days developers are used to this kind of syntaxis and design. So it makes easier to them to implement clients.
• The way to scale up is predictable (because its scalability has been proved many times by projects that applied'em)
• The possible drawbacks of this approach have been already detected and the community has offered several solutions to every one of them. So no need to improvise solutions which result nobody knows.
• This one is the one that nobody things (or does rarely). The approach could be the result of someone's "brilliant idea* who may be and only may be, will be there during all the API's lifetime and its maintenance will be possible with a low cost. But as I use to say Do things like you were not going to be there to maintain them. Anybody that may come after you should be able to understand the solution minimising the learning curve.

Finally back to the OP comment

but they needed concrete reasons why it will fail in the future

Would be good for you and any other involved into the development, to know "they" reasons to implement a single endpoint. Which are their arguments? The against and for. Then you will be in the position to reply with arguments that they might understand.