Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

API Design Guide

cloud.google.com

Post reply on HN
Print view View original

161–170 of 192 posts

Re: API Design Guide

#161

Post by RyanZAG »

webmaven wrote: post #113
squeaky-clean wrote: post #47

Earlier quoted context omitted.

> Sure, a client can follow the links in an automated fashion, but how is it supposed to know what the resources actually are and which links it needs to follow, which resources it has to create or modify, to actually accomplish anything? I've never understood this either. My API client isn't smart enough to follow links and write logic for me, so when they say "the client" can "discover", they must be referring to m…

You can find smarter clients by Googling "hypermedia client". Also, O'Reilly just published a book on the topic: http://shop.oreilly.com/product/0636920037958.do

But would anybody really want to use a hypermedia client versus a regular client? Of course not. The regular client can be optimized properly at the level it needs to be to make the user's interaction smoother.

Re: API Design Guide

#162

Post by _pmf_ »

zerocrates wrote: post #44
camus2 wrote: post #12

Earlier quoted context omitted.

It's interesting that both of these guidelines kind of reject HATEOAS by mandating explicit versioning. It seems that HATEOAS was never really a thing. It's just too complicated to implement in practice. In that sense, REST in practice has always been just RPC without a clear spec for procedure call like XML or JSON RPC.

It's just never been clear to me what HATEOAS is really supposed to be good for. Sure, a client can follow the links in an automated fashion, but how is it supposed to know what the resources actually are and which links it needs to follow, which resources it has to create or modify, to actually accomplish anything? The general idea of returning links to related resources and/or actions is fine and good, but the rhet…

(Note: I'm not advocating this approach, I merely repeat what I think I know)

Instead of hard coding the subject hierarchy in templates (like "/topic/subtopic/"), you define a document type that exposes target elements as links (typically with a "rel" attribute identifying the type of element). The client can then navigate the logical hierarchy without requiring this to match the physical URLs (think: federation across departments; instead of having a template "/api/{department_id}/people/{employee_id}", the company can expose a directory document that aggregates links "link rel='employee' target='https://departmentX.company.com/arbitrary/hierarchy/employee... and "link rel='employee' target='https://othercompany.com/api/users/Doe+John'").

The type of linked resources must of course be aligned; there's no magic involved. Instead of the client having out-of-band knowledge about the hierarchy, the client must have out-of-band knowledge about the used document types containing the links.

Re: API Design Guide

#163

Post by johnjuuljensen »

JimDabell wrote: post #157
johnjuuljensen wrote: post #154

Earlier quoted context omitted.

>> I guess you're using something like HTTP digest auth with usernames and passwords? Basic auth (over https only) actually, I'm even advocating it. We support expirable tokens as well. >> requests without a specific version get the latest version, or requests without a specific version get version 1, or requests without a specific version get the latest stable version that changes from time to time The only way for…

> Any other choice and I'd have customers API integrations breaking, because many of them would not have specified their version mimetypes correctly and would therefore get the default version, which would at some point diverge from their expectations. "Some other people might write code that does things incorrectly and then their software might break" is something you can say about any API style, it's nothing specia…

I hope it's clear from my previous comments that I don't actually disagree with you on most things, I've just had to make compromises that makes things more accessible to my clientele.

>> "Some other people might write code that does things incorrectly and then their software might break

Welcome to my world :)

>> is something you can say about any API style, it's nothing special to media type versioning

True, but mimetype versioning still makes things more complicated for my average user.

>> If many of your customers are writing code that integrates with your API incorrectly, you don't have an API design problem, you have a poor communication problem, and that's going to hurt you in all kinds of ways.

Sorry, but no. We have full Swagger interface, examples for all major operations in 4 different languages, many pages of documentation and tutorials, and very clear and informative error messages for most situations. Still people will write and say it doesn't work, without having read any docs or even looked at the response.

>> This is not designing for maximum simplicity. Designing for maximum simplicity is to have an API that says "here's a link; follow it", not an API that says "here's an ID, generate a URI from it according to these rules we set out in our documentation, that are different for every type of resource". The latter is more work and more error prone.

I'll reiterate, we're probably designing for different clientele. I'd wager my old Amstrad that most of my users would strip any url'y parts of ids I'd return and just store, what they'd perceive to be, the "true" id in their database, because they only have 20 cloumns allocated in their weird mainframe system, named info1-10 and extra1-10, and the latter only allows 32 chars.

But also consider this: A user uploads a resource through the perfect HATEOAS api, he get's back a big object with a unique url id, and links to all the actions he can perform. It doesn't really makes sense for him to store anything other than the URI though, because I might add more actions later, so he'd have to requery the URI to get links to the latest actions anyway. So for any operation he wants to perform, he should GET URI, parse and follow link with appropriate parameters. Also, in that scenario my system gets hit twice for any operation. Compare that to: Replace parameters into https://example.com/people/{id}/poke and fire request. I'd argue that the latter is conceptually simple.

Very soon we'll start on a new api for our ui, and on that there will be no compromise :)

Re: API Design Guide

#164

Post by jalfresi »

squeaky-clean wrote: post #47
zerocrates wrote: post #44

Earlier quoted context omitted.

It's just never been clear to me what HATEOAS is really supposed to be good for. Sure, a client can follow the links in an automated fashion, but how is it supposed to know what the resources actually are and which links it needs to follow, which resources it has to create or modify, to actually accomplish anything? The general idea of returning links to related resources and/or actions is fine and good, but the rhet…

> Sure, a client can follow the links in an automated fashion, but how is it supposed to know what the resources actually are and which links it needs to follow, which resources it has to create or modify, to actually accomplish anything? I've never understood this either. My API client isn't smart enough to follow links and write logic for me, so when they say "the client" can "discover", they must be referring to m…

This is because the idea is that you would create a new media-type to represent your resource. It is this media-type definition that would determine what rel-types there are and how a client should interpret them.

for example, the spec for the HTML media-type that when a client sees a link with the rel-type "stylesheet" is should fetch the resource using HTTP GET.

As REST requires that media-types be registered the idea would be that we would eventually get a set of media-types that cover things like audio playlists, and how to interact with them.

So any "intelligence" required by a client would be baked into the implementation of the media-type processor. Instead of "client libs" for specific web services, you would have a general media-type parser/processor which could be re-used by clients of different web services to process common media-types.

But apparently individual client libs for each web service that overloads JSON is better.

Re: API Design Guide

#165

Post by tokenizerrr »

jalfresi wrote: post #164
squeaky-clean wrote: post #47

Earlier quoted context omitted.

> Sure, a client can follow the links in an automated fashion, but how is it supposed to know what the resources actually are and which links it needs to follow, which resources it has to create or modify, to actually accomplish anything? I've never understood this either. My API client isn't smart enough to follow links and write logic for me, so when they say "the client" can "discover", they must be referring to m…

This is because the idea is that you would create a new media-type to represent your resource. It is this media-type definition that would determine what rel-types there are and how a client should interpret them. for example, the spec for the HTML media-type that when a client sees a link with the rel-type "stylesheet" is should fetch the resource using HTTP GET. As REST requires that media-types be registered the i…

> But apparently individual client libs for each web service that overloads JSON is better.

I mean, there are so many different types of resources and every API I interact with definitely invent their own. How often do you come across an API offering a playlist of music?

Re: API Design Guide

#166

Post by notjack »

zerocrates wrote: post #44
camus2 wrote: post #12

Earlier quoted context omitted.

It's interesting that both of these guidelines kind of reject HATEOAS by mandating explicit versioning. It seems that HATEOAS was never really a thing. It's just too complicated to implement in practice. In that sense, REST in practice has always been just RPC without a clear spec for procedure call like XML or JSON RPC.

It's just never been clear to me what HATEOAS is really supposed to be good for. Sure, a client can follow the links in an automated fashion, but how is it supposed to know what the resources actually are and which links it needs to follow, which resources it has to create or modify, to actually accomplish anything? The general idea of returning links to related resources and/or actions is fine and good, but the rhet…

HATEOS, and REST in general, is a lot more useful when there are middlemen involved. If I have some link relation type named "api.myservice.com/rels/access-controlled-by" and some content type for authentication policies, then I can build a proxy between my API and clients that looks for links of this relation to resources of this type and automatically implements authentication checks. Instead of writing code to check auth rules in my API, I link to a resource that the auth proxy understands in a common format. This format can evolve over time without breaking the proxy due to content negotiation, and API services written in entirely different languages can still rely on a uniform implementation of authentication rules.

There's all kinds of other directions you can take this including quota enforcement, monitoring, auditing, and other resource-agnostic concerns. More radically, you can make these sorts of proxies reusable services that other people rely on to implement these behaviors. One of the primary motivations for REST in the first place was a standard interface that would allow for insertion of caches at arbitrary points in the Web without breaking everything (in the optimistic case at least). There's even HATEOS in the Cache-Control header, as the cache channels extension uses links to external resources to define the cache channels for resources

Re: API Design Guide

#167

Post by scaryclam »

mateo411 wrote: post #127
johnjuuljensen wrote: post #79

Earlier quoted context omitted.

I should probably have moderated that statement, but mostly I think it's bad because it makes the versioning aspect inaccessible from the lowest common denominator, the browser address bar. Versioning through the url and versioning through mimetypes requires the same amount of work from the user, but the former is a lot simpler. If you then also take into account, that many http clients have poor support for manipula…

I also prefer putting the version in URL. I find it to be practical and easy way to version your API. I've also been told that it's not the right way to do it.

There's no "right" or "wrong" way tp version APIs. There's only peoples opinions. I'd suggest that if someone is saying you're doing it wrong by putting it in the url, you should probably learn to ignore them as they can't tell the difference between their own preference and facts.

Re: API Design Guide

#168

Post by mcherm »

daliwali wrote: post #92
mcherm wrote: post #87

Earlier quoted context omitted.

> What they describe is not REST. [...] a strict requirement of the REST architectural style. [...] You have a word "REST" for which you are apparently granted access to Plato's "true" definitions, which enables you to tell me that REST requires hyperlinks, but not naming conventions or HTTP verbs. I reject your definition. Go ahead and use that word "REST" however you like. I will continue using it to describe what…

I am not the authority on what REST is. That would be Roy Fielding, who has explicitly stated that hypermedia is a requirement[1]. So go ahead and tell Mr. Fielding that his definition of REST is incorrect. I am well aware that REST no longer means what it originally described, which is why I think it should go by another term that is not burdened by being a marketing buzzword. [1]: http://roy.gbiv.com/untangled/2008…

> So go ahead and tell Mr. Fielding that his definition of REST is incorrect.

Not "incorrect", but I'd be happy to tell him that his term has been co-opted by the programming masses to means something vaguely related to the original meaning but less precise. I suspect Mr. Fielding already knows that.

> I am well aware that REST no longer means what it originally described, which is why I think it should go by another term that is not burdened by being a marketing buzzword.

I agree there. I think changing how the masses use the term is a lost cause. (Consider the incredibly hard-fought battle to reclaim the original definition of "hacker", which after decades did succeed in establishing it as a secondary definition. That's the most successful case I've ever seen.) So I think ryeguy has it right: call Fielding's definition "HATEOAS" "real REST" or "hypermedia REST" or something.

Re: API Design Guide

#169

Post by oaktowner »

somedumbguy22 wrote: post #56

I wonder if someone from the Apigee team wrote these, as Google recently acquired Apigee[1], and the guidelines are mostly inline with what Apigee recommends.[2] [1] https://techcrunch.com/2016/09/08/google-will-acquire-apigee... [2] https://apigee.com/about/resources/ebooks/web-api-design

And one more thing: Apigee's (awesome) e-book is designed to help customers write APIs.

The Google Style guide is a guide we use (and have been using for years) when designing our own APIs.

(I work on the API team at Google).

Re: API Design Guide

#170

Post by novaleaf »

on a related note, anyone know a good saas for api documentation? preferably one that could take jsdoc imports or other code based generated docs...
Post reply on HN