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

121–130 of 192 posts

Re: API Design Guide

#121

Post by tofflos »

veesahni wrote: post #32
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.

I wrote about API design (with a similar rejection of HATEOAS): http://www.vinaysahni.com/best-practices-for-a-pragmatic-res... In short: humans can follow links, even as a website goes through significant changes. Code can follow links, but can't make clear independent decisions when significant changes happen to the API. [Updated for clarity]

Thank you for your write-up on API design. It's well-written, concise and to the point. I spent quite some time reading it while learning best practices about REST API design last year.

Re: API Design Guide

#122

Post by [deleted] »

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…

[deleted]

Re: API Design Guide

#123

Post by paulddraper »

dragonwriter wrote: post #114
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…

> It's just never been clear to me what HATEOAS is really supposed to be good for. Have you ever used a web browser? You know how the browser uses media-type to determine how to handle content referenced by a URI? That's what HATEOAS is supposed to be useful for: links identify and locate resources, resource type information tells you what kind of resource it is. The only out-of-band information you should need for a…

Yes, but most people aren't making web browsers or similar.

Web browsers are extremely generalized: they display arbitrary HTML, submit arbitrary forms, download arbitrary images, download and run arbitrary JS/CSS.

Most APIs are intended for more specific uses than "all of HTML". Hypermedia is very useful for browsers, but I wouldn't extend that to say, my Imgur clone API.

Re: API Design Guide

#124

Post by combatentropy »

theptip wrote: post #115

An interesting design question arrises around nested resources. Google in this doc buys into deep nested structures, e.g. `//calendar.googleapis.com/users/john smith/events/123` (from [1]). I think this pattern is unambiguously sensible when the child objects are strictly scoped under the parent. But it's less clear how to represent resources that are shared between multiple parents; for example, what if event 123 ca…

Here's one way to tackle it, if behind your REST API is an SQL database:

  /schema/table/key
So:

  //www.example.com/calendar/events/123
To address many records, like all that belong to Bob, use the query string instead of purely the path:

  //www.example.com/calendar/events/?user=bob

Re: API Design Guide

#125

Post by paulddraper »

mcherm wrote: post #87
daliwali wrote: post #40

What they describe is not REST. Nowhere in this document mentions hyperlinks, a strict requirement of the REST architectural style. The best analogy would be a simple web page, which usually contains hyperlinks that a client can follow to discover new information. Unfortunately, web developers' understanding of REST ends with HTML, and they re-invent the wheel, badly, every time they create an ad hoc JSON-over-HTTP s…

> 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…

Well you sure confused the heck outta me.

---

It is really so hard to say "HTTP" instead of "REST"? "Regardless" instead of "irregardless"?

Re: API Design Guide

#126

Post by paulddraper »

programd wrote: post #24
RubenSandwich wrote: post #2

Seems pretty good. Specifically this part of the guide is pretty well written: https://cloud.google.com/apis/design/resources . One thing that is surprising to me however is that their is no mention of using HTTP Status Codes in responses.

Using HTTP status codes in your responses is a trap. It conflates the API transport with the actual semantics of the API. The goal of HTTP error responses is to say that something went wrong in the transport layer. The goal of API error responses is to say that something went wrong in your service. For example, your HTTP REST server may be perfectly fine, but your back end DB may be misbehaving. Having separate API l…

> The goal of HTTP error responses is to say that something went wrong in the transport layer.

Huh? What networking model are you working on?

HTTP is application layer.

TCP is transport layer.

IP is internet layer.

Ethernet is network layer.

Re: API Design Guide

#127

Post by mateo411 »

johnjuuljensen wrote: post #79
mateo411 wrote: post #58

Earlier quoted context omitted.

Why do you think versioning through mimetypes is a bad idea?

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.

Re: API Design Guide

#128

Post by dragonwriter »

paulddraper wrote: post #123
dragonwriter wrote: post #114

Earlier quoted context omitted.

> It's just never been clear to me what HATEOAS is really supposed to be good for. Have you ever used a web browser? You know how the browser uses media-type to determine how to handle content referenced by a URI? That's what HATEOAS is supposed to be useful for: links identify and locate resources, resource type information tells you what kind of resource it is. The only out-of-band information you should need for a…

Yes, but most people aren't making web browsers or similar. Web browsers are extremely generalized: they display arbitrary HTML, submit arbitrary forms, download arbitrary images, download and run arbitrary JS/CSS. Most APIs are intended for more specific uses than "all of HTML". Hypermedia is very useful for browsers, but I wouldn't extend that to say, my Imgur clone API.

> Yes, but most people aren't making web browsers or similar.

The question is whether people are making APIs to be consumed by general purpose tools, not whether they are making general purpose tools.

But, yes, there's a quite valid argument that REST isn't always the right architectural style for an API.

Which isn't an excuse to use the term "REST" for things that aren't REST, which just confused the issue.

Re: API Design Guide

#129

Post by paulddraper »

dragonwriter wrote: post #128
paulddraper wrote: post #123

Earlier quoted context omitted.

Yes, but most people aren't making web browsers or similar. Web browsers are extremely generalized: they display arbitrary HTML, submit arbitrary forms, download arbitrary images, download and run arbitrary JS/CSS. Most APIs are intended for more specific uses than "all of HTML". Hypermedia is very useful for browsers, but I wouldn't extend that to say, my Imgur clone API.

> Yes, but most people aren't making web browsers or similar. The question is whether people are making APIs to be consumed by general purpose tools, not whether they are making general purpose tools. But, yes, there's a quite valid argument that REST isn't always the right architectural style for an API. Which isn't an excuse to use the term "REST" for things that aren't REST, which just confused the issue.

Okay, either way. There aren't a lot of hypermedia-based clients.

Re: API Design Guide

#130

Post by e1g »

netghost wrote: post #117
e1g wrote: post #29

Earlier quoted context omitted.

We've been using GraphQL for everything since late 2015. All recent code is GraphQL-first, and all old code is proxied by a GraphQL layer in front of it. Our application helps BigCos to understand if they pay people fairly and to run smart pay reviews. It's a relatively small codebase, ~100k LOC, but it's essential complexity is in managing and connecting dispersed data about employees and markets. GraphQL allows us…

Do you expose your GraphQL endpoint to customers, or just use it internally?

We expose GraphQL to two high value customers, but the pains of having a stable public API are so great that I wouldn't recommend it to any startup without a damn good reason.
Post reply on HN