3

Let's say our web application handles "orders". An order can be displayed in several different pages of our web app, on each one, in a very different way.

For example: in page A, it shows just very basic information about the order (like it's date and total value). In page B, it shows also information about the user requesting the order. In page C, it shows all that + a lot of other details.

Should I have 3 different API endpoints to provide an order, one for each page, providing only the information the page will need, or should I have just one, providing all the possible information about an order?

If I have just one endpoint, it will return a lot of unecessary information to some pages, and also will decrease performance (bigger queries, joins with other tables, etc.).

But I don't know if it is a bad practice to create one endpoint for each frontend "need".

6

How many other clients to this API will there be?

If this is the only client, why not. Its use case is tailored to just this usage, just this representation. Assuming your client isn't trying to be smart and load/cache the object across end points, this can be a very efficient way of writing an API. When your client changes its easy to cleanup old code paths without worrying that somewhere else is also using the end-point.

If you have more than one client, this strategy starts to become problematic. One size never really fits anyone, and a bespoke fit even less so.

You could possibly provide tailor made api-endpoints for both clients, but now you run into the fact that some end-points are duplicates (to keep the one to one mapping), and others have such small differences you might have to read the code very deeply to spot it. But this strategy quickly becomes more difficult the more clients are added, and the business will quite rightly ask what is the difference between supporting 1, 2, or 50 clients? <Insert Name of a Titan Software Company> does it!

Once you get to your second client you really should be looking at refactoring out the commonalities. There may still be some bespoke api end-points for just this or just that client and use case, but the API should be moving toward orthogonal and composable calls. This API will oversupply detail for some views, and other views need to combine data from several API end-points, but those API's will be generally useful to most clients, and much fewer in number simplifying support and maintenance.

Alternately give up on REST and transition to a stateful communication model using websockets - a complicated solution that has pay offs in some scenarios. I don't recommend it for you situation as it appears though.

1
  • 1
    Your alternative solution of giving up on REST has a lot of merit. GraphQL seeks to address the OP's problem (many different views or clients needing access to variant subsets of the same data). GraphQL allows the client to specify exactly what data they want to receive, opposed to the traditional REST way where the server defines what data is included with each endpoint. Thereby, reducing over/under serving content and not creating hard dependencies between API endpoints and client versions. – old greg Mar 3 at 13:25
3

The appropriate development depends on your needs. There are two main considerations here:

Development time vs bandwidth

Would you rather waste a bit of bandwidth in favor of speeding up development? Then only develop the full order details endpoint.

Do you want to save bandwidth no matter the cost to development time? Then create an endpoint for each specific subset of order data you need.

Do you want to find a happy balance? Then only develop a few of those endpoints, e.g. a "simple" and "detailed" endpoint. Any view that is "somewhat detailed" will then waste a bit of bandwidth but any view that only needs a simple listing won't. From experience, this usually covers most bases and finds a happy medium.

Backend-driven vs frontend-driven

Does the backend exist to serve the frontend? Or if the backend the main product, and the frontend consumes it? Depending on which is your main project, you make these kinds of decisions differently.

Personally, I consider a backend (especially a REST api) as being a project that defines its own exists, regardless of how a frontend may choose to consume it or not. This means that I don't write custom backend endpoints that serve one specific view from one specific frontend. The backend simply provides the information, and I don't add/change endpoints just because I decided to add/change a single field on a certain page.

But I am a backend developer and I work in companies that deliver a service (i.e. REST api), not a client app.

If your main project is the client app you're developing, and you need to squeeze for performance/bandwidth, then the added effort of altering your backend to suit the precise needs of your frontend may be desirable for you.


As always, precision takes effort, which takes time and money. Whether it's worth it or not very much depends on how necessary it is, and how much time and budget you have available.

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.