When should one develop HATEOAS server RESTful API instead of using HTML (resource links, forms, etc.)?
Isn't HTML and a browser good enough as hypermedia engine?
Isn't HTML and a browser good enough as hypermedia engine?
HTML + HTTP + URI + Browser === The world wide web. So it's pretty good, no joke.
It's not without fault.
HTML's understanding of links is disappointingly limited. No support for idempotent writes. Uri Template support for GET only. I'm not super keen on how many different spellings there are for "link".
It's kind of verbose for a hypermedia format; don't get me wrong - built in text markup is brilliant when you are trying to document what is going on for a human being. But my impression thus far is that same structure starts to get in the way when as a human being you want to quickly review the semantic content that your automated agent is consuming.
I call your attention to this quote from RFC-4287
The primary use case that Atom addresses is the syndication of Web content such as weblogs and news headlines to Web sites as well as directly to user agents.
So a bunch of really smart guys, specifically trying to address use cases directly related to the web, decided to invest a bunch of effort into standardizing a new hypermedia format rather than using the one that was already ubiquitous in their problem domain.
And over the past 10+ years, that format has been widely adopted.
Without adoption, I'm not sure that HATEOAS has much benefit. You don't need a hypermedia api if you are controlling both sides of the conversation (example: javascript on the web -- hypermedia with code on demand capability downloading a client that has learned the protocol of a web api via some out of band channel).
Evidence would seem to suggest that HTML is not nearly as convenient a format as, for example, any of the JSON based hypermedia formats.
In conclusion: no, it's not good enough. It might be an acceptable place holder for the moment; but the JSON hypermedia tool sets are soon going to be sufficiently mature that HTML will be seen as a giant step in the wrong direction.
Related
APIs are getting more and more popular and are used by developers to ease the process of developing applications to multiple platforms AND allow them to give other developers the ability to integrate their application's functionality into their own applications.
I've used APIs countless times before, but I'm now at the stage of developing my own applications. And as a developer who strives to create multi-platform applications - I need to use an API.
I'm going to use the RESTful approach as it's recommended the most.
After reading and looking for some background information, I came across: REST API Tutorial (which is really good site!), I learned that APIs basically receive HTTP requests, and return data in JSON/XML format.
However, there were 2 questions left unanswered to me:
In what form do APIs come in? Are APIs actually files? a set of commands......?
How do I actually write APIs? I'm talking about the server-side, data-handling code, and not the application/language-specific code (for sending out HTTP requests etc...)
It'd be great if someone could help me and answer the questions above as I have zero experience with APIs.
Any help is appreciated - much thanks!!
Just a quick from-the-gut answer: They are whatever you want them to be!
Off the top of my head, I would define an API as requiring two main elements:
Some documentation which makes it quite clear how to use the logic your systems prvides
Some way to call those systems. That may be as simple as a web-site that accepts POST-messages, and checks them for certain variables and values in order to perform specific tasks.
In short, it should be entirely up to you. Just make sure you provide simple, clear and acurate documentation.
UPDATE, as an asnwer to the comment below:
That is how I interpret it, and it would seem that Wikipedia is more or less in agreement with me. PHP would be a perfect example: You could for instance create a PHP-file which processes a POST, and instead of outputting html, outputs XML with the resulting data needed. Then a third party app could POST to your PHP application, and receive and process the resulting XML.
Apis come as a response to a http request. It is a plain text response that u can use encoded via json or xml as you described.
There are a plenty of frameworks to help you develop and API.
In Ruby u can use grape or rais-api or even rails itself.
There is a lot more available, but this are the ones im most used to use.
In most tutorials, documentation, articles etc. about RESTful I come across a few of the same points, but yet I rarely ever see these 'What makes it RESTful' points implemented.
For example, I've read this many times:
Content type
Using HTTP headers
Accept: application/json, text/plain
Extension in the URL
Not RESTful, URLs are not the place for Content-Type
I have never come across an API where I have seen this implemented. Every API I have ever used has always required me to append XML or JSON to the end of the URL. Are they doing it wrong?
Versioning
Version media types
application/vnd.something.v1+json
Custom header
X-API-Version: 1
Version in URL
/v1/resouce
Not RESTful, by putting the version in the URL you create separate resources
If you need to introduce non-backwards-compatible functionality surely creating a seperate resource is the correct thing to do?
Once again, in all versions of APIs I've used, they use v1, v2 in the URL (such as google, imgur etc.)
By not implementing these points, would my API not be considered RESTful?
To clarify these points would be much appreciated.
1) Using accept header or using format specific URLs are both valid in a RESTful system. The article you are citing is wrong.
2) Saying v1/resource is not RESTful is also incorrect. You cannot look at a URI and make a conclusion about its RESTfulness. Adding a v1 at the root of your URL is probably not a great thing to do if you are trying to incremental evolve your system. In effect it declares a whole new URL space and obsoletes the old one. That's pretty drastic. RESTFul systems try and enable incremental and evolutionary change to a system. So doing /resource/v2 is actually much more compatible with that goal.
The unfortunate phenomena at work here is that many developers who are learning about REST discover that the vast majority of systems out there that claim to be doing REST are not actually conforming to the constraints of REST. So they quickly develop a zeal for telling everyone what is and is not RESTful. Many of these people have not yet fully understood the constraints and end up making up new ones that don't exist. The "RESTFul URL" fallacy is a classic. "POST must create a resource" is another common one.
My guidance to anyone learning REST is, if someone tells you that something is not RESTful, you ask them what constraint it is violating and what is the practical impact of ignoring that constraint. If they can't answer that, then politely ignore them.
The true definition of REST is obviously in the doctoral dissertation written by Roy Fielding in 2002. Do all of the API's out there that call themselves RESTful follow the guidelines specified by Fielding? The answer is no. The definition of REST has been watered down by some to just mean anything that does not use SOAP. I would worry less about what is RESTful and more about what is good practices. It is a good practice to specify the content type in the header of the request. It is also a good practice to version your API's. A good resource for information on API best practices is from the guys at Apigee as they have a lot of experience in this area. Check out their webinar on RESTful API Design where they ask if you are a pragmatist or a RESTafarian.
Hi Guys : It seems like the SOAP/WSDL world was very high on generating objects from data models, but I cannot tell wether the REST approach to web services favors the same approach. In my opinion, it seems as though JSON is emerging as the new common, native object format for most languages, thus obviating any need for language specific APIs. However, I'm new to the web services game.
Thus my question is : Are there tools which can autogenerate REST client side objects for us? And secondarily, is it customary in the web-services world, to provide client side objects for dealing with REST data (as is neccessary for dealing with SOAP data) ?
What the "REST world" doesn't quite have in the same way as the "SOAP world" is a service description language like WSDL. At least, it's not quite as uniform.
There is of course HTML. Behind REST is the Web, and it would be unfair to dismiss HTML, since it has precisely the purpose of describing what you can do with the service. The downside is that it's not very computer-friendly in its most common form. Hence, there is no html2java that will turn your forms into objects. In addition, the programming model would be quite different to remote objects, which tools like wsdl2java tend to incur.
There is WADL, but it's not necessarily wide-spread. There is a wadl2java tool (see this question too perhaps).
It also depends on what you call a "REST" web service: does it really make proper use of the hypermedia, or is it just sending XML/JSON to a nice-looking URL.
I am currently developing a very simple web service and thought I could write an API for that so when I decide to expand it on new platforms I would only have to code the parser application. That said, the API isn't meant for other developers but me, but I won't restrict access to it so anyone can build on that.
Then I thought I could even run the website itself through this API for various reasons like lower bandwidth consumption (HTML generated in browser) and client-side caching. Being AJAX heavy seemed like an even bigger reason to.
The layout looks like this:
Server (database, programming logic)
|
API (handles user reads/writes)
|
Client application (the website, browser extensions, desktop app, mobile apps)
|
Client cache (further reduces server reads)
After the introduction here are my questions:
Is this good use of API
Is it a good idea to run the whole website through the API
What choices for safe authentication do I have, using the API (and for some reason I prefer not to use HTTPS)
EDIT
Additional questions:
Any alternative approaches I haven't considered
What are some potential issues I haven't accounted for that may arise using this approach
First things first.
Asking if a design (or in fact anything) is "good" depends on how you define "goodness". Typical criteria are performance, maintainability, scalability, testability, reusability etc. It would help if you could add some of that context.
Having said that...
Is this good use of API
It's usually a good idea to separate out your business logic from your presentation logic and your data persistence logic. Your design does that, and therefore I'd be happy to call it "good". You might look at a formal design pattern to do this - Model View Controller is probably the current default, esp. for web applications.
Is it a good idea to run the whole website through the API
Well, that depends on the application. It's totally possible to write an application entirely in Javascript/Ajax, but there are browser compatibility issues (esp. for older browsers), and you have to build support for things users commonly expect from web applications, like deep links and search engine friendliness. If you have a well-factored API, you can do some of the page generation on the server, if that makes it easier.
What choices for safe authentication do I have, using the API (and for some reason I prefer not to use HTTPS)
Tricky one - with this kind of app, you have to distinguish between authenticating the user, and authenticating the application. For the former, OpenID or OAuth are probably the dominant solutions; for the latter, have a look at how Google requires you to sign up to use their Maps API.
In most web applications, HTTPS is not used for authentication (proving the current user is who they say they are), but for encryption. The two are related, but by no means equivalent...
Any alternative approaches I haven't considered
Maybe this fits more under question 5 - but in my experience, API design is a rather esoteric skill - it's hard for an API designer to be able to predict exactly what the client of the API is going to need. I would seriously consider writing the application without an API for your first client platform, and factor out the API later - that way, you build only what you need in the first release.
What are some potential issues I haven't accounted for that may arise using this approach
Versioning is a big deal with APIs - once you've created an interface, you can almost never change it, especially with multiple clients that you don't control. I'd build versioning in as a first class concept - with RESTful APIs, you can do this as part of the URL.
Is this good use of API
Depends on what you will do with that application.
Is it a good idea to run the whole website through the API
no, so your site will be accessible only through your application. this way This implementation prevents compatibility with other browsers
What choices for safe authentication do I have, using the API (and for some reason I prefer not to use HTTPS)
You can use omniauth
Any alternative approaches I haven't considered
create both frontends, one in your application and other in common browsers
What are some potential issues I haven't accounted for that may arise using this approach
I don't now your idea, but I can't see major danger.
This spec http://www.w3.org/TR/webdatabase/ says:
This document was on the W3C Recommendation track but specification work has stopped. The specification reached an impasse: all interested implementors have used the same SQL backend (Sqlite), but we need multiple independent implementations to proceed along a standardisation path.
Does this mean that HTML5 database is going away, and for some time we will have a de-facto standard using SQLite, possibly with browser differences? Or has the W3C published a plan of attack for finishing the standard?
According to this article:
[...] we think it is worth explaining our design choices, and why we think IndexedDB is a better solution for the web than Web SQL Database.
In another article, we compare IndexedDB with Web SQL Database, and note that the former provides much syntactic simplicity over the latter. IndexedDB leaves room for a third-party JavaScript library to straddle the underlying primitives with a BTree API, and we look forward to seeing initiatives like BrowserCouch built on top of IndexedDB. Intrepid web developers can even build a SQL API on top of IndexedDB. We’d particularly welcome an implementation of the Web SQL Database API on top of IndexedDB, since we think that this is technically feasible. Starting with a SQL-based API for use with browser primitives wasn’t the right first step, but certainly there’s room for SQL-based APIs on top of IndexedDB.
I'm not personally swayed by the arguments put forth in the article, but it seems clear that (for the time being) Mozilla has decided that Web SQL Database is dead.
Further interesting comments about this article may be found on Hacker News.
My understanding is that this is now called "IndexedDB"
http://www.w3.org/TR/IndexedDB/
Apparently the Firefox team has started implementing this:
http://hacks.mozilla.org/2011/01/indexeddb-in-firefox-4/
I don't know if anyone knows the answer. Mozilla doesn't like the dependence upon SQLite and has decided to go a different way. However, all WebKit based browsers already have it implemented and I don't see them removing it as any websites built to take advantage of the spec would be broken.
This means that at least in certain contexts, mostly within the mobile sphere where most browsers have a webkit implementation, it can still makes sense to use the HTML5 Web SQL spec. I see this as especially true for developers who are looking to create mobile applications using a framework like phonegap.
There are some times where as an application developer you want to provide users with access to data even if they aren't connected to the internet or if the connection is slow and some types of data is just more efficiently stored in a database than in a cookie or JSON cashe. For example, if you have data that has relationships it is much easier and quicker to do a join query to pull the data you need than it is to search a json map.
I don't think the spec is dead, and I actually hope that Mozilla will reverse their stance so that developers can use it to solve problems outside of the mobile webkit world.