CODEWITHSUNDEEP
restapiapi-design
Frank L
Frank L

Reputation: 207

How to design endpoints for data not considered as a resource in a REST API

User context:

An school administrator logs into a dashboard. The page displays a block of data at the top of the page:

  1. Number of students who used the service over the past week
  2. The aggregate feedback (positive, negative, neutral) left by the students over the past week in percentages.
  3. Other aggregate data

Underneath is a bunch of charts and graphs representing usage of the service broken down by month, daily usage broken down by hour, etc.

My problem:

I'm trying to build an API following REST principals where endpoints should define a resource and HTTP verbs as the action to take on those resources. My problem is going about building endpoints for this more 'analytical' and aggregate data that doesn't really seem to fit anywhere in my resources. Ideally, each graph or chart could be one request to an endpoint, and the block of aggregate data at the top would also be its own request, rather than 3 requests (1 for each piece of data). Can someone guide me in the right direction on how to go about building the endpoints for these specific scenarios?

Thanks

Upvotes: 0

Views: 269

Answers (1)

VoiceOfUnreason
VoiceOfUnreason

Reputation: 57249

Can someone guide me in the right direction on how to go about building the endpoints for these specific scenarios?

TL;DR: How would you build a web site to support those scenarios? Do that.

If you were using something like a document store, then you would take the URI, say /feedbackReports/lastWeek, and use that as a key, and pull from the document store a representation of that report, and return it to the client (along with various bits of metadata).

If you were using something like a file system, then you would take the URI, and construct some reference to a file, like /www_root/feedbackReports/lastWeek, and read the representation of that report from disk, and return it to the client (along with various bits of metadata).

Is you were using something like a relational database, then you would take the URI, and see that the "last week" report was being asked for, and from that you would inject a bunch of "-7 days" parameters into prepared statements, and run them, then reshape the data in memory into some representation of that report, and return it to the client (along with various bits of metadata).

I'm trying to build an API following REST principals where endpoints should define a resource and HTTP verbs as the action to take on those resources

The REST principle in question is that the API isolates the clients (and intermediary components) from all of the implementation details. The API is the mask that your application wears so that web integrations just work.

My problem is going about building endpoints for this more 'analytical' and aggregate data that doesn't really seem to fit anywhere in my resources.

So create more resources.

Note: these are integration resources; which is to say that they produce the representations that web clients need to interact with your domain.

Jim Webber, in 2008

URIs do NOT map onto domain objects - that violates encapsulation.  
Work (ex: issuing commands to the domain model) is a side effect of 
managing resources.  In other words, the resources are part of the
anti-corruption layer.  You should expect to have many many more 
resources in your integration domain than you do business objects 
in your business domain.

Upvotes: 2

Related Questions