I'm developing a project to be used by both a smartphone app and a single page app website. I'm using Backbone.js for my data binding.
I've got a bit of an architectural question: How do I make my API restful, yet enrich the data coming back in my models.
An example:
I would like to change the roles of a user in a group.
In the restful case, I'd load a collection of the roles for a particular user in the group. I'd check and uncheck the roles I'd like to apply to the user in the context of that group, then save. I'm therefore doing a GET for the array of roles and a PUT to save the altered list. The issue I am facing is that I need to enrich my model with more meta data such as the Group's name, the User's name etc so the user has some context when editing the data.
I can quite easily do this but then I'm not really restful anymore with my model.
Does anyone have any resources they can point me to that can help me to architect my solution to achieve the best of both RESTfulness and usability using Backbone.js?
Backbone model does not make your application more or less restful.
For the most part, rest is about the interactions between the HTTP client and server.
Like in REST API URI Design Approach question, mostly the focus is on the URI design.
The more practical way of thinking or applying REST as the starting point (at least it works for me) is to think in the following ways:
1) Use only HTTP ‘GET/POST/PUT/DELETE’ as the way to model your domain ‘actions’ . Just like when you dealing with database, all your actions are mapped to CURD.
2) URI/URL is to identify resources only. Should never have any ‘actions’ in your URI.
3) The data exchanged should be in the body of the HTTP messages.
Just to simplify the discussions, not getting into how to model the data itself
Two great books on rest.
REST in Practice
Restful Web Services
You can create a Restful web service which can be consumed in both smartphone app and a single page app website.
Please have a look at
http://blogs.msdn.com/b/hongyes/archive/2012/08/30/single-page-application-with-backbone-js-and-asp-net-web-api.aspx
Here they are creating SPA with backbone.js and ASP.NET Web API ( to create Restful web service).
Other great resource can be found here:
http://www.asp.net/single-page-application/overview/templates/backbonejs-template
Thanks.
Related
When using routing in a SPA web app (angular, react, etc), the user doesn't have to start at the entry point of the application. They can use a URL in the browser to drill down into any part of the application.
When implementing HATEOAS in a RESTful backend API, we assume that the front-end only knows the URL to the entry point of the API, and then the API provides links to other parts of the application from there.
So this begs the question, if a user enters a URL in the browser that loads a specific part of the SPA (not the entry point), how does the SPA get the appropriate API link needed for just that part of the SPA?
Does the SPA just make a bunch of API calls all at once, starting at the entry point of the API and following links until it gets the link it needs for the state it needs to load? And what happens when the API does not include the link needed because it's not a valid link based on the current state of the application?
HATEOAS doesn't seem to be very compatible with a modern SPA where you can load the application at very specific sections/states.
This has been asked on SO before, but I'm having trouble finding these past questions and answers. I've answered at least two, but I'll summarize how this usually gets answered.
Camp 1: Don't do SPA's, it doesn't make sense. Your HATEOAS service should serve the entire state in a way that the client can interpret and SPA's are basically a hack.
Camp 2 (the camp I'm in): You'll need some way to map SPA links to links on your backend.
You're kind of describing this by talking about 'all the steps needed' to get to the right resource, but if your goal it ultimately map this to an API uri, why not embed just that
https://spa.example/http://api.example/some/resource
Having bookmarkable urls that contain the full path to your backend, means you don't need to jump through complex hoops, and your SPA is a true client for the API you are building.
Another nice benefit is that you can also easily point your client to multiple live/dev environments.
Lastly, you could allow for relative urls and automatically resolve them to the API url, shortening:
https://spa.example/http://api.example/some/resource
to
https://spa.example/some/resource
Given the following scenario:
a RESTful API
that RESTful API has permissions/authorizations that can be granted to entire entity collections, and/or to particular entities, i.e. complex role based permission rules.
The API is (according to RESTful principles) HATEOS-driven (resource url's are revealed through the API. Once you login and get back the "user" resource, you are able to drive the entire API through links given in responses.
A front-end client (web app) that needs to use this API
Imagine now the front-end wants to build a menu. That menu is based on access to particular entities and/or entity collections. For example an "Administration" menu will be shown if the user has access to one of a number of different entities and/or collections.
How do I build the menu? I need to know the permissions the user has in order to build the menu propertly. I don't know all the permissions the user has because it would require walking the url's of the REST API to see all the objects the user has permissions on.
This seems like a tough thing to overcome, but maybe I am missing some obvious technique. How can this impedance mismatch overcome?
Your REST API can expose a resource (or it can be a part of the user resource returned after a user has been successfully signed in) which will contain information what resources the user can access and therefore what menu items should be available for this user.
So I have a dilema here. Trying to build out a RESTful API. Which means I'd like to have resources defined and also require that consumers reference those resources by id.
For example, the typical {resourceName}/{id}?{querystring}
But the way of course a web UI works, for a ecommerce site is that naturally you have SEO-friendly urls.
So there is a mismatch in terms of application specific URLs where we have application context based urls, context here being an ecommerce site using SEO-friendly URLs. They wouldn't have stuff like /id in it 100% of the time. And actually our site doesn't have any ids whatsoever in the web UI's urls.
So when users go from page to page, we might have urls like www.ourdomain.com/cars/local/usa/ca/sunnyvale-cars. And sometimes we're talking about stripping the '-' or other characters out of the more seo friendly urls, after the UI devs send a request to lets say like above a state resource. I'd strip the city name out of 'sunnyvale-cars' if lets say I wanted info on that city so the UI team might send me '/cities?name=sunnyvale-cars' where our API would need to strip out the city name in order to do the query in the backend which to me just doesn't sound like something our API should be doing. It's also coupling our REST API to the web and web conventions...our REST API should be ignorant of any type of delivery mechanism so that our API can be reused for other apps or other APIs in our Business domain.
There might be times where the UI Engineering team, in fact a lot of times they'll only have URLs like this. There is no user action or lets say dropdown list where they can just grab an id. So they can't always request stuff for the next page by sending me a RESTful URI request every time as they may not have ids all the time. In other words, sometimes they'll have to instead request stuff like this: /states?name="ca" to get something related to that state just as a hypothetical example.
So how in the world do you even build a REST API if your UI team is telling you they won't have ids for everything?
From a REST purist's point of view no URI is inherently more RESTful than another as long as both use identify the resources. At least, I could not find anything about that in the original thesis.
However, if you find some structure fitting the purposes of your API better, you can create a second endpoint exclusively for the needs of your UI team. That endpoint would serve as a proxy and simply map the SEO-friendly structure to your API in possibly generic way.
Or, applications from the outside are just expected to do the rewriting or any app specific mapping-to-REST API "stuff" since it's really app specific in what that mapping looks like anyway, thus keeping the API ignorant of application specific details, domain logic, or even web conventions which the API should not care about or even know about.
I have created a quite simple RESTful web service. It only supports the GET (=read) method, e.g.:
http://localhost/application/id/xyz
The corresponding information for this ID is queried from a data source and returned as JSON.
Now my question: (How) should I implement HATEOAS in this case? Does it even make sense? I understand that HATEOAS is reasonable when having a more complex structure. But in this case, there are no other resources I could link to. The client calls the web service with a certain ID and the server returns information.
Thank you!
As you've said "The client calls the web service with a certain ID" it sounds like you've written your client to visit a specific URL in your service which has the URL to visit generated by the client, i.e. your client application already knows it can visit http://localhost/application/id/xyz for the xyz ID.
If you'd like to leverage some of the power of HATEOAS and decouple yourself from this (slight) dependency, you could instead be querying http://localhost/application/id?query=xyz which could return a list of valid links (if any exist). That way you could change the format or structure of the linked URL without issues for your client (of course, you'd still be dependent on the query URL in some way).
However, as your usage is so simple, this sounds like overkill and unnecessary work so I'd suggest you don't need to worry about HATEOAS until you have a more complex system or clients :)
In HATEOS your return value is not an ID but a URL. Invoking that URL links you to the next resource in the web. Just like a web page containing links to other web pages.
We have 2 developers who have conflicts in the way to design the RESTful API Endpoint. Basically, let say that we have Facebook product in hand, one table for the posts.
First developer give the opinions that
We should seperate Endpoint by product, not by the technical storage. To be like that, we will have endpoint for user facebook post and other facebook post.
/v1/wall/mypost
/v1/wall/other
To be like that, we be able to configure each products that may return difference results
Second developer disagree, give the opinions that
If be like that, it will make infinite endpoint. it will have /wall/someone, /wall/sometwo.
We should have single endpoint, and just let that be a part of query. ex. /wall?user=someone, /wall?user=sometwo
The endpoint should be look like technical schema, it return the same result, why it have to seperated to make it more jobs on maintenance the code.
What is the good practice to design our endpoint? Is it should be endpoint by the product? or is it should be by schema?
It should depend on what 'resource' that the service is suppose to manage from the API user perspective and not from the internal implementation.
With that, if the service is to manage say, a resource that can be identified by 'someone', 'sometwo' and, then the correct way to model it is
/wall/someone/
/wall/sometwo/
In this case, 'someone' and 'sometwo' are two different resources and you could have infinite # of them; but that has nothing to do with the internal storage or implementation.
On the backend, there should be some url pattern to extract 'someone' and 'sometwo' as resource and map them into internal implementation details.
What are these "endpoints" you speak of? That's SOAP terminology! RESTful web services are defined in terms of "resources" that are uniquely identified by URL.
A resource typically represents an entity in your domain model (e.g., a user). The ID of the entity is typically used as a path element ("path parameter" in the lingo of most REST libraries, such as JAX-RS) in the URL. Query parameters should only be used to sort/filter results on the server side.
Your first developer is closer to being correct.