A REST API must not define fixed resource names or hierarchies (an obvious coupling of client and server). Servers must have the freedom to control their own namespace. Instead, allow servers to instruct clients on how to construct appropriate URIs, such as is done in HTML forms and URI templates, by defining those instructions within media types and link relations. [Failure here implies that clients are assuming a resource structure due to out-of band information, such as a domain-specific standard, which is the data-oriented equivalent to RPC's functional coupling].
A REST API should be entered with no prior knowledge beyond the initial URI (bookmark) and set of standardized media types that are appropriate for the intended audience (i.e., expected to be understood by any client that might use the API). From that point on, all application state transitions must be driven by client selection of server-provided choices that are present in the received representations or implied by the user’s manipulation of those representations. The transitions may be determined (or limited by) the client’s knowledge of media types and resource communication mechanisms, both of which may be improved on-the-fly (e.g., code-on-demand). [Failure here implies that out-of-band information is driving interaction instead of hypertext.]
Joshua Bloch mentions the immutability of Public APIs in his excellent talk),
--
You received this message because you are subscribed to the Google Groups "API Craft" group.
To unsubscribe from this group and stop receiving emails from it, send an email to api-craft+...@googlegroups.com.
Visit this group at http://groups.google.com/group/api-craft.
For more options, visit https://groups.google.com/groups/opt_out.
--
Hypermedia defines How (method, data) and Where (URI). I think you are right about changing the How, but I think one of the beauties of hypermedia is being able to change the Where without breaking the API.
Suppose you have a small collection of Books, and your Book resource has an "open", "read", and "close" action, and your client is designed to let a user look at all of the books, open a book, read it, and then close it. Now suppose you decide to include the notions of searching for Books in a Library, and that you must "check out" a Book from a Library in order to open, read, or close it. The only way to deal with this change is to a) rewrite the client to use these new notions or b) have the interface to the resources be directly generated from the API responses - this is the case of HTML/Web Browsers, but it's just not how APIs are consumed.
3. Simple client logic
A client that simply follows URLs instead of constructing them itself, should be easier to implement and maintain. It won't need logic to figure out which values to substitute into what URL templates. All it has to do is to identify links in the payload and extract the hypermedia reference URL.
The use of hypermedia removes the client's hard coded knowledge of the URL structures used by the server. This means the server is free to change its URL structures over time when the API evolves without any need to upgrade the clients.
Why is that a cost? Why is "the way you use it explorable as well" an additional cost? Sorry I don't get that?
Allow me to disagree with this. The contract is either in a domain specific media type or a generic one plus some sort of "profile" document (like my issue tracker description). That contract (the media type/profile) can/should specify which link relations a client can expect to find in the various responses.
I think Josh Bloch's argument about unchanging API's is about unchanging expectations. If as an axiom you accept that the capability of change is *part* of an API design, then suddenly all "change" forseeen by the API design is not really change per-se (i.e. a violation of expectations put forth by the API), it's just the API being what it is (i.e. effectively staying the same).
If however the client doesn't understand the concept of "checking out" and has no capability to learn new concepts, then no amount of design can help it. The new concept and workflow change is effectively changing the clients expectations and thus introducing a breaking API change (for clients that are not capable of learning new concepts or don't understand the new concept).
First off, it's more than possible that you're facing problems in
which the full-blown REST style is not applicable.
--
You received this message because you are subscribed to a topic in the Google Groups "API Craft" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/api-craft/7c1tyHv2VQ4/unsubscribe.
To unsubscribe from this group and all its topics, send an email to api-craft+...@googlegroups.com.
Visit this group at http://groups.google.com/group/api-craft.
For more options, visit https://groups.google.com/groups/opt_out.
1. An important, maybe the most important, feature of a good API is that it does not change (especially while you are using it).2. REST/Hypermedia intentionally address the problems of a changing interfaceAnd that therefore they are in some ways "spiritually at odds" with one another.
you present an excellent catalog of the difficulties of versioning any API, but these are not particular to REST, or even Web, work.
Let A be a consumer of the client. How can A deal with a changing client?- If resources are created, or only added to, A could be made to still function as normal.- If state transitions are created, A could be made to still function as normal.
(If A relies on any of the deleted information)</snip>Is the above true for "web browsers"? No. Why? Because web browsers (which ARE clients) are designed as state machines. They DO NOT follow a per-determined path through a set of memorized resources with static relationships between each resource. They are built on a very different assumption. That the resource responses will always contain useful information and that information has the potential to lead to another (as yet never known before) resource.
One of the reasons that hypermedia responses seem unhelpful to client-app builders may be that these app-builders are not interested in building apps that operate on this different assumption. Instead they want to build one-off, bespoke clients that have memorized all the possible paths from A-Z and are not at all interested in discovering as yet never known before resources.
Essentially, when you want to start "talking" to machines, you need to stop using "human languages" and need to start "talking on the machines' level." This is not at all complex, but it does take more work.
REST (hypermedia in particular) seems to be fundamentally at odds with API Design
"entirely dynamic" == "web browser" for versions of "entirely" of what? and "web" browser? so you assume work on only HTTP?
but neither of these are very helpful POVs, IMO. these statements will always be true not matter what you are attempting or using in the attempt.
is that what you really want to settle on? that you are only interested in talking about "entirely dynamic", "web browser", and "anything less than completely responsive to changes"?
is that what you think I was talking about? in fact, I am not attempting nor even interested in those extremes
"however you want" - sure. but again, why add these extreme phrases to your assertion?
do you think that is what I am advocating ("however you want")? because that is not what i said, nor what i mean.
As for "remove the ability to program against" this assertion is not true in my experience -- unless your definition of "program against" is diff than mine.- I can certainly conjure up scenarios where i can change the server in such a way as to ensure client failure.- I can also come up with ways to code a client app such that the slightest change in a server response will cause the client to crash.But these are pathological POVs. I would never _plan_ to design fragile cases like this, would you?
Evan, I've been reading this thread with interest.
I don't see how the idyllic "local api" actually solves any of the problems you mention. A local api's safety relies on everything else in its vicinity remaining stable as well.
For instance, upgrading the OS can break a local api without the developer expecting it. Many of us have gotten panicked calls from OPS when they "performed a simple upgrade that shouldn't have caused a problem with the application".
I don't see how the idyllic "local api" actually solves any of the problems you mention. A local api's safety relies on everything else in its vicinity remaining stable as well.
I think a lot of the discussion circles around “control”, especially “control over change”.In my experience, that is something you automatically loose once whatever you use is behind a network card.
M