31–40 of 53 posts
Maybe this particular cookbook isn't the place for it, but I'd really like to see something cover this. It's a problem that stumps me.
Having worked with hypermedia APIs recently I've come to appreciate how they feel more pragmatic and REST more pedantic. The hateos principle in particular lets you build thinner clients.
Isn't "hypermedia API" just a new name some people came up with for "REST API" because the misunderstood non-HATEOAS mangling of REST is so common and they wanted to distinguish between the two? Real REST APIs use HATEOAS.
Strictly speaking, you can use hypermedia without REST, too. But that's the lineage of the last few years of what people are talking about.
While some of the tips are useful, I'd much rather see them written with JSON rather than XML. JSON has long been an industry standard. XML is bloated, almost no one uses it anymore. http://restcookbook.com/Mediatypes/json/ says "There is no predefined way to deal with link discovery in JSON". I'm surprised it doesn't even mention JSON Schema ( http://json-schema.org/ ) or JSON API ( http://jsonapi.org/ ), which are…
It depends on what you mean by 'official standards.' We've registered JSON API with IANA, so it's a standard media type, but there hasn't been an RFC yet, as we're basically just finalizing the spec now. (We're in a week-long period of just textual review, conceptually and structurally, it's done.)
And given that AMS is going into Rails and Ember Data will default to JSON API out of the box, hopefully we'll have enough usage to actually justify an RFC in a year or so.
Earlier quoted context omitted.
Ok, so client requests "DELETE www.company.com/api/thing/1234" and gets a 404. Or even "GET www.company.com/api/thing/1234". Delete vs get doesn't matter. Did 1234 not exist, or is "/api/thing" the wrong path? 404 is overloaded. It can mean two very different things.
> Did 1234 not exist, or is "/api/thing" the wrong path? This doesn't matter. You shouldn't be trying to pull "1234" out of the URI. The identifier for the resource as far as the client is concerned is the URI, not some numeric component buried within it. Just treat the URI as an opaque piece of information – if you get a 404, it's the wrong URI. If you're trying to divine meaning from the constituent parts of the UR…
All server code for REST will be written in terms of /path/to/{ID}. We have a path, we have a instance ID, which each may be incorrect.
Earlier quoted context omitted.
> The examples are in XML because json is, (and I believe at this point), still not stricly an (accepted) hypermedia capable format, thus not adhering the HATEOAS constraint, and thus cannot be restful. But to be honest, I'd prefer JSON over XML anytime. What exactly is the criteria of being a "hypermedia capable format"? The linked website gives an example of how the response on a bank-account like API might include…
> What exactly is the criteria of being a "hypermedia capable format"? One document must be able to link to another. > Is there a predefined way to deal with it in XML? Yes, Xlink: http://www.w3.org/TR/xlink11/ > In the earlier example, I had assumed he did exactly what you would do in JSON: make up a field for the purpose. The problem with this is that it's non-standard and nothing understands it that isn't custom-w…
* JSON-LD http://www.w3.org/TR/json-ld/
* HAL https://tools.ietf.org/html/draft-kelly-json-hal-06
* Siren https://github.com/kevinswiber/siren
* Uber https://rawgit.com/uber-hypermedia/specification/master/uber-hypermedia.html
Earlier quoted context omitted.
> The examples are in XML because json is, (and I believe at this point), still not stricly an (accepted) hypermedia capable format, thus not adhering the HATEOAS constraint, and thus cannot be restful. But to be honest, I'd prefer JSON over XML anytime. What exactly is the criteria of being a "hypermedia capable format"? The linked website gives an example of how the response on a bank-account like API might include…
> What exactly is the criteria of being a "hypermedia capable format"? One document must be able to link to another. > Is there a predefined way to deal with it in XML? Yes, Xlink: http://www.w3.org/TR/xlink11/ > In the earlier example, I had assumed he did exactly what you would do in JSON: make up a field for the purpose. The problem with this is that it's non-standard and nothing understands it that isn't custom-w…
I'd like to request a "recipe" for handling authentication to my API. I want to know: what use is an API key? Should I be authenticating client apps separately from users? (That's users of the application into which the API reaches.) What are the tradeoffs of sending login credentials with every request versus using a token? Maybe this particular cookbook isn't the place for it, but I'd really like to see something c…
1. API keys and tokens can be more easily replaced / canceled than entire
accounts in the case of being breached
2. API keys & tokens can commonly have additional access restrictions applied,
while it's hard(er) to do that for a whole account
3. Likewise, it's easy to think of many-tokens-to-one-account systems,
where you encourage users to use different keys for different integrations,
which helps lower the surface area of the damage one leaked detail can do
4. Many authorization protocols, like OAuth 2, rely on temporary tokens,
which are even more helpful in that they guide application integrations towards
not hardcoding sensitive details
Earlier quoted context omitted.
Isn't "hypermedia API" just a new name some people came up with for "REST API" because the misunderstood non-HATEOAS mangling of REST is so common and they wanted to distinguish between the two? Real REST APIs use HATEOAS.
Yes. Strictly speaking, you can use hypermedia without REST, too. But that's the lineage of the last few years of what people are talking about.
As an example, an api for AirBnB's mobile website might expose a /srp endpoint that can be used by a thin client to render the results recursively. Again, the way I've internalized it, to be a REST api I'd expect a client to request results from a /listings endpoint of some kind.
I think there is a lot of confusion and misunderstanding and that precise language is better for everybody. What should we be calling these things? I'd love your thoughts on it.
Earlier quoted context omitted.
> Did 1234 not exist, or is "/api/thing" the wrong path? This doesn't matter. You shouldn't be trying to pull "1234" out of the URI. The identifier for the resource as far as the client is concerned is the URI, not some numeric component buried within it. Just treat the URI as an opaque piece of information – if you get a 404, it's the wrong URI. If you're trying to divine meaning from the constituent parts of the UR…
Yes, but is it the wrong URI because the path is wrong (and then I'll double check the docs and my code), or was the 404 because the code is correct but the specific item could not be found? All you are saying is "it doesn't matter", which is unhelpful and ignores the fact that these are completely different error conditions. All server code for REST will be written in terms of /path/to/{ID}. We have a path, we have…
This is the source of the problem. REST APIs are hypertext-driven. They use links, like the web. You access resources by following links, not by constructing URIs. If you are reading the specification to find out which paths to use, then hard-coding them in your client software, then you don't have a REST architecture, you have something very different (which, unfortunately, some people insist on calling "REST" anyway).
REST revolves around hypertext. You don't hard-code paths, the server provides resources that link to one another. The client accesses the resources by following the links, not by constructing URIs itself.
If you have a REST architecture, then you can't get the path wrong in your client code because the path isn't in your client code. It's in a resource the server gives you.
> All server code for REST will be written in terms of /path/to/{ID}.
Perhaps, but the client should not be aware of this. The ID that a REST client uses is the URI.
> We have a path, we have a instance ID, which each may be incorrect.
The only ID that the client has is a URI, and if you get a 404, it means that there's no resource available for you to access with that ID. The client does not have a path, and the client does not have an instance ID. It only has a URI.
Earlier quoted context omitted.
Yes. Strictly speaking, you can use hypermedia without REST, too. But that's the lineage of the last few years of what people are talking about.
So I'm a so-called "full stack engineer" and the definition I've internalized is that a REST api is essentially about modeling the entities in your application and defining what actions can be taken on each (with consistent use of verbs). And a "hypermedia api" approach is more about modeling behavior. As an example, an api for AirBnB's mobile website might expose a /srp endpoint that can be used by a thin client to…
I think that the true heart of the hypermedia approach is actually "how do I deal with change over long periods of time in a scalable fashion?" Everything else flows from this. Exposing behaviors instead of data is one facet of the approach.
> What should we be calling these things?
Which 'these' are you referring to?