Let's suppose I was going to design a platform like Airbnb. They have a website as well as native apps on various mobile platforms.
I've been researching app design, and from what I've gathered, the most effective way to do this is to build an API for the back-end, like a REST API using something like node.js, and SQL or mongoDB. The font-end would then be developed natively on each platform which makes calls to the API endpoints to display and update data. This design sounds like it works great for mobile development, but what would be the best way to construct a website that uses the same API?
There are three approaches I can think of:
Use something completely client-side like AangularJS to create a single-page application front end which ties directly into the REST API back-end. This seems OK, but I don't really like the idea of a single-page application and would prefer a more traditional approach
Create a normal web application (in PHP, python, node.js, etc), but rather than tying the data to a typical back end like mySQL, it would basically act as an interface to the REST API. For example when you visit www.example.com/video/3 the server would then call the corresponding REST endpoint (ie api.example.com/video/3/show) and render the HTML for the user. This seems like kind of a messy approach, especially since most web frameworks are designed to work with a SQL backend.
Tie the web interface in directly in with the REST api. For example, The endpoint example.com/video/3/show can return both html or json depending on the HTTP headers. The advantage is that you can share most of your code, however the code would become more complex and you can't decouple your web interface from the API.
What is the best approach for this situation? Do you choose to completely decouple the web application from the REST API? If so, how do you elegantly interface between the two? Or do you choose to merge the REST API and web interface into one code base?
It's a usually a prefered way but one should have a good command of SPA.
Adds a redundant layer from performance perspective. You will basically make twice more requests all the time.
This might work with super simple UI, when it's just a matter of serializing your REST API result into different formats but I believe you want rich UI and going this way will be a nightmare from both implementation and maintainance perspective.
SUGGESTED SOLUTION:
Extract your core logic. Put it into a separate project/assembly and reuse it both in your REST API and UI. This way you will be able to reuse the business logic which is the same both for UI and REST API and keep the representation stuff separately which is different for UI and REST API.
Hope it helps!
Both the first and the second option seem reasonable to me, in the sense that there are certain advantages in decoupling the backend API from the clients (including your web site). For example, you could have dedicated teams per each project, if there's a bug on the web/api you'd only have to release that project, and not both.
Say you're going public with your API. If you're releasing a version that breaks backwards compatibility, with a decoupled web app you'd be able to detect that earlier (say staging environment, given you're developing both in-house). However, if they were tightly coupled they'd probably work just fine, and you'll find out you've broken the other clients only once you release in production.
I would say the first option is preferable one as a generic approach. SPA first load delay problem can be resolved with server side rendering technique.
For second option you will have to face scalability, cpu performance, user session(not on rest api of course because should be stateless), caching issues both on your rest api services and normal website node instances (maybe caching not in all the cases). In most of the cases this intermediate backend layer is just unnecessary, there is not any technical limitation for doing all the stuff in the recent versions of browsers.
The third option violates the separation of concerns, in your case presentational from data models/bussines logic.
Related
I've searched for this answer in many places, but I just can't seem to understand the purpose of these services.
What exactly are web APIs meant to do? I've used Spring Boot quite extensively over the past few months, though without touching its REST services portion. I was recommended to check out ASP, and specifically use its web-API items, but I have to say I'm just baffled.
How exactly is the returning of just plain data useful? In Spring, I've used models and views, which are great and useful for directing users around. But that doesn't seem to be the goal of REST APIs. So is the main idea to separate the API from the server? But why do that, when I can just as easily separate the model from the controller anyways, following the MVC pattern? As far as I can tell, there's no real way to return a view with the JSON (or whatever format the data is), so that would necessitate another server, just to deal with providing the views, no?
I'm assuming it's faulty, per-existing information that I have that's getting me stuck up here, but I just don't understand what's the point of a service that only spits out data, yet is far more removed than the model in MVC.
What exactly are web APIs meant to do?
The best summary that I know of comes from Roy Fielding
REST is intended for long-lived network-based applications that span multiple organizations.
The reference application for the REST architectural style is the World Wide Web.
The point being that, if your API is "of the web", then you get to take full advantage of the work that has already been done for you: browsers, caches, servers, well understood media-types, code-on-demand, and so on.
is the main idea to separate the API from the server?
Really, the main idea is to separate the implementation from the messaging. As far as the outside world is concerned, your service is just a web site.
Web Services are used to fetch the data from some other application, only data is fetched and view is prepared by consuming application.
Example if you pass the customer number to web service then only data is received and its your responsibly to display the data in proper asp/jsp or any other view technology
Scenario: We are creating/desiging a REST service to help us configure a system (and it's network, etc), but we run into some problems related to designing this API. We would like to configure the hostname of the system using a REST call/
Challenge: Because most APIs and design guidelines are related to lists of entities and not just a single one, I can't decide on how the rest API should look like.
Currently we are considering using something like:
GET /system/0
PUT /system/0 {....}
Problem: There is just one system entity so it doesn't feel good to identify this using 0 because there is only one of it.
Are there any REST guidlines about how this should be done?
Actually, REST does not enforce a particular format for the URL, you can even have an URL like /569284d7-1b59-4343-92d4-90e8753bcbd7 and it's OK. In REST the server guides the client through state changes, it's not about the client knowing what URLs to access.
Most web API's are created in a CRUD style, with hierarchies of resources like your example /system/0, /system/1 because it's easier to understand and implement (might not always be RESTful depending on how tight the coupling of the client is to the URLs, but it serves most needs so people chose to do it like that).
So my advice would be to keep it simple and not over-think it. Using /system/0 is just fine, even if now you have only one system.
Just my 2 cents!
For a SaaS startup I'm involved in, I am building both a RESTful web API and a couple of client apps on different platforms that consume it. I think I've got the API figured out, but now I'm turning to the clients. As I've been reading about REST, I see that a key part of REST is discovery, but there seems to be a lot of debate between two different interpretations of what discovery really means:
Developer discovery: The developer hard-codes copious amounts of API details into the client, such as resource URI's, query parameters, supported HTTP methods, and other details that they've discovered through browsing the docs and experimenting with the API's responses. This type of discovery IMHO necessitates cool linkage and the API versioning question, and leads to hard coupling of the client code to the API. Not much better than if using a well-documented collection of RPC's it seems.
Runtime discovery - The client app itself is able to figure out everything it needs with little or no out-of-band information (presumably, only a knowledge of the media types the API deals with.) Links can be hot. But to make the API very efficient, a lot of link templating for query parameters seems to be needed, which makes out-of-band info creep back in. There are possibly other difficulties I haven't thought of yet since I haven't gotten to that point in development. But I do like the idea of loose coupling.
Runtime discovery seems to be the holy grail of REST, but I'm seeing precious little discussion about how to implement such a client. Almost all REST sources I've found seem to assume Developer discovery. Anyone know of some Runtime discovery resources? Best practices? Examples or libraries with real code? I'm working in PHP (Zend Framework) for one client. Objective-C (iOS) for the other.
Is Runtime discovery a realistic goal, given the present set of tools and knowledge in the developer community? I can write my client to treat all of the URI's in an opaque manner, but how to do this most efficiently is a question, especially over low-bandwidth connections. Anyway, URI's are only part of the equation. What about link templating in the Runtime context? How about communicating what methods are supported, aside from making a lot of OPTIONS requests?
This is definitely a tough nut to crack. At Google, we've implemented our Discovery Service that all our new APIs are built against. The TL;DR version is we generate a JSON Schema-like spec that our clients can parse - many of them dynamically.
That results means easier SDK upgrades for the developer and easy/better maintenance for us.
By no means the perfect solution, but many of our devs seem to like.
See link for more details (and make sure to watch the vid.)
Fascinating. What you are describing is basically the HATEOAS principle. What is HATEOAS you ask? Read this: http://en.wikipedia.org/wiki/HATEOAS
In layman's terms, HATEOAS means link following. This approach decouples your client from specific URL's and gives you the flexibility to change your API without breaking anyone.
You did your home work and you got to the heart of it: runtime discovery is holy grail. Don't chase it.
UDDI tells a poignant story of runtime discovery: http://en.wikipedia.org/wiki/Universal_Description_Discovery_and_Integration
One of the requirements that should be satisfied before you can call an API 'RESTful' is that it should be possible to write a generic client application on top of that API. With the generic client, a user should be able to access all the API's functionality. A generic client is a client application that does not assume that any resource has a specific structure beyond the structure that is defined by the media type. For example, a web browser is a generic client that knows how to interpret HTML, including HTML forms etc.
Now, suppose we have a HTTP/JSON API for a web shop and we want to build a HTML/CSS/JavaScript client that gives our customers an excellent user experience. Would it be a realistic option to let that client be a generic client application? No. We want to provide a specific look-and-feel for every specific data element and every specific application state. We don't want to include all knowledge about these presentation-specifics in the API, on the contrary, the client should define the look and feel and the API should only carry the data. This implies that the client has hard-coded coupling of specific resource elements to specific layouts and user interactions.
Is this the end of HATEOAS and thus the end of REST? Yes and no.
Yes, because if we hard-code knowledge about the API into the client, we loose the benefit of HATEOAS: server-side changes may break the client.
No, for two reasons:
Being "RESTful" is a property of the API, not of the client. As long as it is possible, in theory, to build a generic client that offers all capabilities of the API, the API can be called RESTful. The fact that clients don't obey the rules, is not the API's fault. The fact that a generic client would have a lousy user experience is not an issue. Why is it important to know that it is possible to have a generic client, if we don't actually have that generic client? This brings me to the second reason:
A RESTful API offers clients the option to choose how generic they want to be, i.e. how resilient to server-side changes they want to be. Clients which need to provide a great user experience may still be resilient to URI changes, to changes in default values and more. Clients doing batch jobs without user interaction may be resilient to other kinds of changes.
If you are interested in practical examples, checkout my JAREST paper. The last section is about HATEOAS. You will see that with JAREST, even highly interactive and visually attractive clients can be quite resilient to server-side changes, though not 100%.
I think the important point about HATEOAS is not that it is some holy grail client-side, but that it isolates the client from URI changes - it is assumed you are using known (or developer discovered custom) Link Relations that will allow the system to know which link for an object is the editable form. The important point is to use a media type that is hypermedia aware (e.g. HTML, XHTML, etc).
You write:
To make the API very efficient, a lot of link templating for query parameters seems to be needed, which makes out-of-band info creep back in.
If that link template is supplied in the previous request, then there is no out-of-band information. For example a HTML search form uses link templating (/search?q=%#) to generate a URL (/search?q=hateoas), but nothing is known by the client (the web browser) other than how to use HTML forms and GET.
GUI based web applications could be build upon a GUI component, stateful framework like Wicket or they could build in a RESTful, stateless way with GUI status only on the client.
From a technical point of view REST looks like the right way since it leverages the full power of http and leads to highly scalable applications. But that comes at a price. Complex GUIs will require a JavaScript application on the client in many cases. You have to stay on the same page and reload only parts, if state should be maintained on the client. Or you have to use tricks with hidden iframes. Sometimes there are pseudo resource like shopping carts on the server, to enable a RESTful design. You have to maintain intermediate state of multi step dialogues and so on ...
If I look around there are very few RESTful GUI webapplications. Is this because of historical reasons or is a RESTful design unproductive in common scenarios?
If I look around there are very few
RESTful GUI webapplications. Is this
because of historical reasons or is a
RESTful design unproductive in common
scenarios?
My answer is subjective, but in my opinion, two major hurdles hinder RESTful development:
Change - it very different from the way sites are traditionally designed
Challenge - designing a pure RESTful server API and a corresponding rich, robust client UI isn't easy
Complex GUIs will require a JavaScript
application on the client in many
cases.
In my opinion, a complex, a rich client-side experience is going to require some in-depth JavaScript, regardless of the server-side implementation.
You have to stay on the same page and
reload only parts,
This is a very different design from the traditional request/response full-page-to-full-page design. Each design has its own trade offs. REST designs work particularly well with AJAX calls, but the client-side code requires careful design to be maintainable and robust.
A RESTful server with a thick-client:
scales well: session information for every user isn't stored in scarce server memory
less request/response data over the wire: not sending every page in full, not sending session IDs or ViewStates
clean reusable URLs: provide a clean, decoupled server API that can support multiple UIs
pure: strict adherence to the HTTP specification (GETs cause no side effects, etc.)
client experience: richer, more responsive with asynchronous transactions
However, as you mentioned thick-clients have drawbacks:
more vulnerable to XSS attacks, RESTful URLs really need careful security
complex JavaScript can be challenging to develop, maintain, and debug (using OO JavaScript can help mediate this)
there is a need to indicate to the user that asynchronous requests are processing in the background
more client-side failure-handling logic is required
frameworks and IDE tools have been traditionally weaker for client-side development, compared to server-side (this is slowly getting better)
RESTful GUI designs are very productive, IMHO. You can leverage a lot of functionality without extra work to support the corner cases, such as the user resubmitting information, browser history (back and forward) multiple tabs and windows. If I'm not mistaken this site uses a RESTful UI.
REST was defined by observing characteristic of successful web applications, both GUI and M2M. Therefore by definition it should be appropriate for these cases.
I also noticed you asked a question regarding desktop versus web applications. You may be interested to know that REST is an excellent architecture for building desktop client applications too. I have written a few desktop clients that get all of their data from a REST server.
I am working on a experimental website (which is accessible through web browser) that will act as a front-end to a restful interface (a sub-system). The website will serve as an interface between a user and the restful interface, as it will make http requests to the restful interface for almost all database operations. Authentication will probably be done using openid and authorization for the database operations will be done via oAuth.
Just out of curiousity, is this a feasible solution or I should develop two systems that accesses the database in parallel (i.e. the website has its own data access logic, and the restful interface has another data access logic)? And what are the pros/cons if I insist on doing it this way (it is just an experiment project for me to learn things like how OpenID and oAuth work in real life anyway) besides there will be more database queries and http requests generated for each transaction?
Your concept sounds quite feasible. I'd say that you'll get some fairly good wins out of this approach. For starters you'll get a large degree of code reuse since you'll be able to put other front ends on top of the RESTful service. Additionally, you'll be able to unit test this architecture with relative ease. Finally, you'll be able to give 3rd party developers access to the same API that you use (subject possibly to some restrictions) which will be a huge win when it comes to attracting customers and developers to your platform.
On the down side, depending on how you structure your back end you could run into the standard problem of granularity. Too much granularity and you'll end up making lots of connections for very little amounts of data. Too little and you'll get more data than you need in some cases. As for security, you should be able to lock down the back end so that requests can only be made under certain conditions: requests contain an authorization token, api key, etc.
Sounds good, but I'd recommend that you do this only if you plan to open up the restful API for other UI's to use, or simply to learn something cool. Support HTML XML and JSON for the interface.
Otherwise, use a great MVC framework instead (asp.net MVC, rails, cakephp). You'll end up with the same basic result but you'll be "strongerly" typed to the database.
with a modern javascript library your approach is quite straightforward.
ExtJS now has always had Ajax support, but it is now able to do this via a REST interface.
So, your ExtJS user interface components populate receive a URL. They populate themselves via a GET to the URL, and store update via POST to the URL.
This has worked really well on a project I'm currently working on. By applying RESTful principles there's an almost clinical separation between the front & backends - meaning it would be trivial undertaking to replace other. Plus, the API barely needs documenting, since it's an implementation of an existing mature standard.
Good luck,
Ian
woow! A question from 2009! And it's funny to read the answers. Many people seem to disagree with the web services approach and JS front end - which has nowadays become kind of standard, known as Single Page Applications..
I think the general approach you outline is quite feasible -- the main pro is flexibility, the main con is that it won't protect clueless users against their own ((expletive deleted)) abuses. As most users are likely to be clueless, this isn't feasible for mass consumption... but, it's fine for really leet users!-)
So to clarify, you want to have your web UI call into your web service, which in turn calls into the database?
This is exactly the path I took for a recent project and I think it was a mistake because you end up creating a lot of extra work. Here's why:
When you are coding your web service, you will create a library to wrap database calls, which is typical. No problem there.
But then when you code your web UI, you will end up creating another library to wrap calls into the REST interface... because otherwise it will get cumbersome making all the raw HTTP calls.
So you essentially created 2 data access libraries, one to wrap DB and the other to wrap the Web service calls. This basically doubles the amount of work you do, because for every operation on a resource, you will end up implementing in both libraries. This gets tiring real fast.
The simpler alternative is to create a single library that wraps access to the database, as before, then use that library from BOTH the web UI and web service.
This is assuming that your web UI and web service reside on the same network and both have direct access to the backend database server (which was the case for me). In this setup having both go directly to the database is also a lot more efficient then having the UI go through the web service.