2

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.

  • 1
    "I want to have one class and one static method that I push every command through in my application, then that class will sort out what I'm asking and take care of it!". That's insane. – jleach Sep 28 '16 at 12:44
4

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).

  • Btw, we use NHibernate as ORM. We do lazy loading and initialize properties with /api/data?entity=entity_name&properties=prop1,prop2. It is working but I have my own worries with this approach, like readability, maintainability and debugging, and the API will be a little bit "chatty". If the most acceptable answer is all about principle or pattern, then I won't be able to convince them not to use this. – dandansoysauce Sep 24 '16 at 16:11
  • Unfortunately, a lot of code that has maintainability problems will "work", in the sense that it will function. The problems usually come later down the road. I'll also mention that I've had bad experiences with turning loose an API that amounts to an open window into the ORM. There are often unexpected performance issues because the inputs to the database couldn't be tested. – Michael Sep 24 '16 at 19:10
  • Yes, that was my point I gave them, but they needed concrete reasons why it will fail in the future, and I couldn't give an answer. I probably won't be able to convince them to shift the approach, since they want it all "generic". Anyway, thanks for the input. – dandansoysauce Sep 24 '16 at 19:51
  • That is a sad part of our profession sometimes. Sometimes the best you can do when you are in the minority is argue for piloting both approaches and seeing which works better in the end. – Michael Sep 24 '16 at 21:17
  • @dandansoysauce, rather than readability and maintainability you should start asking questions about security. How are you going to specify which properties are "public" and which shouldn't be searchable / editable? – Peter Taylor Sep 28 '16 at 14:41
1

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.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.