REST APIs work great for get-one, get-a-list etc.
But our frontend has a dashboard, and one part of the dashboard is a more complicated. It requires a query that aggregates/joins several different resources.
Returning the data is not a problem. But what of the taxonomy of the endpoint that returns this data? Since the data is not a resource, what should the URL look like?
For REST principles it does not matter much if data returned 'aggregates/joins several different resources'. It is implementation detail of underlying data store. The dashboard should not care how exactly that store is implemented, if it uses joins, multiple queries.
Whatever is displayed on dashboard (single item or list of items) still may be treated as resource.
Example: Imagine use case when dashboard shows aggregated user profile from multiple portals (Facebook, Linkedin, etc). You may still have REST resource /user/id for that, even if obtaining that single resource would require many complex operations.
Related
Use case
I am building a webshop where people can register/sign in and can purchase (and afterwards manage) their SaaS licenses. For this purpose I created (among others) the following REST endpoints:
// Lists all licenses which are linked to this user
r.Get("/users/{userID}/licenses", api.LicenseSvc.HandleGetLicenses())
// List details (such as purchase date, seat information, ...) for a given licenseID
r.Get("/users/{userID}/licenses/{licenseID}", api.LicenseSvc.HandleGetLicense())
// Creates a new license for the signed in user
r.Post("/users/{userID}/licenses", api.LicenseSvc.HandleCreateLicense())
// Each license has a limited number of seats. The license manager can free up seats to make room for others
r.Delete("/users/{userID}/licenses/{licenseID}/seats/{seatID}", api.LicenseSvc.HandleDeleteSeat())
The above endpoints are only supposed to be used in the webshop/license management panel. At the same time the same service has to serve endpoints for the SaaS products which actually use the license(s) a user has created/purchased before. This SaaS product needs different endpoints such as:
An endpoint to check at startup whether a given license is valid at all
An endpoint which also gets the license by ID (see above), but it should only return a subset of the license resource (e. g. it shouldn't return the date when the license was purchased)
My question
Due to the fact that I am building one REST API which is consumed by two different "audiences" (on the one hand the license manager/customer and on the other hand the SaaS software) I feel like I am running into conflicts.
The authentication of both audiences is different, both audiences want to access the same kind of resource (e. g. a license) but the resource "format" (no customer sensitive data for the SaaS requester) should be different depending on the audience.
Should this be reflected via different REST URLs or should I handle all that logic inside of my route handlers?
Should I even create two different services serving these different audiences? Like one API for the userpanel/license management and one for the SaaS products!?
REST is not very well prepared for these multi-client scenarios. i have seen many REST apis where certain attributes of resources will only be filled under certain circumstances where i find that perfectly fine. however i have also seen many examples of multiple use cases bunched into single resource models where the swagger documentation with its limiting structure terribly fails to communicate the purpose of each field.
so: as long as the use cases do not differ too much, i would try to keep the count of endpoints low.
tip: have a look at GraphQL, it is much better equipped for handling such cases with querying only for certain sets or even only asking for certain fields, putting the client in control. however using GraphQL as the primary interface is still somewhat exotic and comes with quite substantial initial cost compared to the plentiful REST infrastructure available. still worth it.
I'm having a bunch of apis which return several types of data.
All users can query all data by using a GET rest api.
A few users can also change data. What is a common approach when designing REST API, to query only the data that can be changed by the current user but still allow the api to return all data (for display mode).
To explain it further:
The software manages projects. All projects are accessible for all users (also anonymous) via an api (let's call it GET api/projects).
A user has the ability to see a list of all projects he is involved in and which he can edit.
The api should return exactly the same data but limited to the projects he is involed in.
Should I create an additonal parameter, or maybe pass an http header, or what else?
There's no one-size-fits-all answer to this, so I will give you one recommendation that works for some people.
I don't really like creating resources that have 'complex access control'. Instead, I would prefer to create distinct resources for different access levels.
If you want to return limit results for people that have partial access, it might be better to create new resources that reflect this.
I think this might also help a bit thinking about the abstract role of a person who is not allowed to do everything. The abstraction probably doesn't exist per-property, but it exists somewhere as a business rule.
I am trying to shift towards serverless architecture when it comes to building REST API. I came from Ruby on Rails background.
I have successfully understood and adapted services such as Api Gateway, Cognito, RDS and Lambda functions, however I am struggling with putting it all together in optimal way.
My case is the following. I have a simple user based platform when there are multiple resources related to application members say blog application.
I have used Cognito for the sake of authentication and Aurora as the database service for keeping thing like articles and likes..
Since the database and Cognito user pool are decoupled, it is hard for me to do things like:
Fetching users that liked particular article
Fetching users comments
It seems problematic for me because I need to pass some unique Cognito user identifier (retrieved during authorization phase in API gateway) to lambda function which will then save the database record with an external reference to this user. On the other hand, If I were to fetch particular users, firstly I must fetch their identifiers from my relation database and then request users details from Cognito user pool..I lack some standard ways of accessing current user in my lambda functions as well as mechanisms for easily associating databse record with that user..
I have not found some convincing recommended patterns for designing such applications even though it seems like a very common problem and I am having hard time struggling if my approach is correct..
I would appreciate some comments on what are some patterns to consider when designing simple user based platform and what are the pitfalls of my solution. Any articles and examples will also be very helpfull.
Thanks in advance.
These sound like standard problems associated with distributed, indpependent, databases. You can no longer delegate all relationships to the database and get a result aggregating them in some way. You have to do the work yourself by calling one database, then the other.
For a case like this:
Fetching users that liked particular article
You would look up the "likes" database to determine user IDs of those who liked it, then look up the "users" database to determine user details such as name and avatar.
Most patterns follow standard database advice, e.g. in the above example, you could follow the performance-oriented pattern of de-normalising - store user data such as name and avatar against each "like", as long as you feel the extra storage and burden of keeping it consistent is justified by the reduction in queries (probably too many Likes to justify this).
Another important practice is using bulk queries to avoid N+1 queries. This is what Rails does with the includes syntax, but you may have to do it yourself here. In my example, it should only take two queries because the second query should get all required user data in one go, by querying for users matching the list of user IDs.
Finally, I'd suggest you try to abstract things. This kind of code gets messy fast, so be sure to build a well-encapsulated data layer that isolates application code from dealing with the mess of multiple databases.
User context:
An school administrator logs into a dashboard. The page displays a block of data at the top of the page:
Number of students who used the service over the past week
The aggregate feedback (positive, negative, neutral) left by the students over the past week in percentages.
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
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.
What are the options in a web api to indicate that the returned data is paged and there is further data available.
ASP.Net Web API with OData uses a syntax similar to the following:
{
"odata.metadata":"http://myapi.com/api/$metadata#MyResource","value":[
{
"ID":1,"Name":"foo"
},
...
{
"ID":100,"Name":"bar"
}
],"odata.nextLink":"http://myapi.com/api/MyResource?$skip=20"
}
Are there any other ways to indicate the link to the next/previous 'page' of data without using a metadata wrapper around the results. Can this be achieved by using custom response headers instead?
Let's take a step back and think about WebAPI. WebAPI in essence is a raw data delivery mechanism. It's great for making an API and it elevates separation of concerns to a pretty good height (specifically eliminating UI concerns).
Using Web API, however, doesn't really change core of the issue you are facing. You're asking "how do I want to query my data store in an performant manner and return the data to the client efficiently?" Your decisions here really parallel the same question when building a more traditional web app.
As you noted, oData is one method to return this information. The benefit here is it's well known and well defined. The body of questions/blogs/articles on the topic is growing rapidly. The wrapper doesn't add any meaningful overhead.
Yet, oData is by no means the only way you can do this. We've had to cope with this since software has been displaying search results. It's tough to give you specific advice without really understanding your scenario. Here are some questions that bubbled up as I read your question :
Are your results sets huge but users only see the first one or two
pages?
Or do user tend to page through all of the results?
Are pages of results limited (like 20 or 50 per page) or 100's/ 1000's ?
Does the data set shift rapidly, so records are added as the user is
paging?
Are your result sets short and adding columns that repeat tolerable?
Do you have enough control over the client do do something out of band -- like custom HTTP headers, or a separate HTTP request that just asks for a query summary?
There really are hundreds of options depending on your needs. I don't know what you're using as a data store, but I wrote a post on getting row count efficiently. The issues there are very germane here, albeit from the DB perspective. It might help you get some perspective.