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

141–150 of 192 posts

Re: API Design Guide

#141

Post by pbreit »

tyingq wrote: post #81
pbreit wrote: post #61

What is current consensus on client libraries? Braintree for example requires that you use their client libraries where as Stripe makes them optional. With Google's gRPC thing I can definitely understand using libraries for performance. Otherwise, isn't making simple REST calls without custom libraries sufficient for most uses? Or if you want a library, something generic like Unirest [1]? 1. http://unirest.io/

Might be helpful to see Braintree's rationale for why they don't publish docs for plain external REST: https://www.braintreepayments.com/blog/when-rest-isnt-good-e... I don't necessarily agree with all the points, but I can see why they made the decision they did.

I've read it several times and found it uncompelling.

Re: API Design Guide

#142

Post by absalyamov »

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…

As described in https://cloud.google.com/apis/design/design_patterns#get_uni...:

  //calendar.googleapis.com/users/-/events/123

Re: API Design Guide

#144

Post by theptip »

absalyamov wrote: post #142
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…

As described in https://cloud.google.com/apis/design/design_patterns#get_uni... : //calendar.googleapis.com/users/-/events/123

Hadn't spotted that, it's an interesting syntax and I quite like it.

But it doesn't cover the case I'm referring to; in their example you MUST return the fully-qualified URL:

> shelves/shelf713/books/book8141, not shelves/-/books/book8141

This precludes there being multiple shelves with the same book (sensible in their example, since a book has only one shelf, but not in the example above).

Re: API Design Guide

#145

Post by webmaven »

jauco wrote: post #88
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.

If I get it correctly HATEOS is about the following: Say you're building a standardised API (with many consumer implementations _and_ many provider implementations all talking to each other). In that case making stuff like the layout of a url or even the protocol over which the data is retrieved part of the specification is putting a needless strain on your API providers. If an API provider uses a shared webhost or a…

It even cooler than that: You only have to standardize the types and meanings of the links, the actual implementations can vary in the locations of the endpoints, but the structure of the documents can too, and the client(s) will be smart enough to figure out that on this server they need to retrieve /users/mike/products/, and on that server they need to get /userproducts/mike/all/, just through the fact that the representation of the user (also probably retrieved from different locations) on each server has a link labeled rel="all products" pointing to the right place, regardless of what else was included or omitted from the representation, so you can have interoperability on whatever is standardized even if implementations of both clients and servers have different capabilities they expose.

So, as long as you standardize the semantics and relations, the URL layouts and the document layouts can be quite different, in the same way that you know when looking at a page what the button or link labeled "Home" will do, regardless of the exact location on the page or the fact that on one server it takes you to /, on another to /index.html, and on yet another to /main/home/ .

Re: API Design Guide

#146

Post by webmaven »

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…

"Hypermedia APIs" seems to be the up-and-coming term.

Re: API Design Guide

#147

Post by johnjuuljensen »

JimDabell wrote: post #139
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…

> mostly I think it's bad because it makes the versioning aspect inaccessible from the lowest common denominator, the browser address bar. That also rules out using any HTTP method other than GET. The browser address bar doesn't seem relevant here, and if it were, then it would rule out the vast majority of APIs. Versioning through the URL breaks interoperability of clients using different protocol versions. If a cli…

I suspect that we are designing for different clientele.

I'm currently in charge of a pretty classic, GET things out, and POST things in API. If my API supports that some non-IT office guy can get his daily report through the browser, and the API at the same time has the power and flexibility needed for someone with IT skills to do more then I've won. Both me and my users gain by me taking extra steps to make it as accessible as possible.

I also fail to see how versioning through urls break anything, except if the newer client no longer has support for v1. In both versioning schemes you specify which version of a resource you're sending/wants to receive, in one scheme you do it through a header, in the other through the url.

>> If a client using v1 communicates with a client using v2, then they will see two separate sets of resources and they would never have the same identifiers for (what should be) the same resources.

Maybe we're defining versioning differently. I strive to make resource types backwards compatible, but if I can't then it's either a new version or a creating a new more specialized resource type for the specific problem.

Re: API Design Guide

#148

Post by webmaven »

andyfleming wrote: post #143

Do any of these API guides have good guidance around batch endpoints like handling a PATCH on multiple resources as a single request?

Not sure how common this pattern is, but one way I've seen this handled is to do a query to get a list of results, the document listing the results (or more commonly, the first page of results) has a link to a temporary resource representing the set of all results, which you can send a DELETE to remove all the members of the set. By analogy, you could send a PATCH to modify all the members instead.

Re: API Design Guide

#149

Post by lenkite »

e1g wrote: post #131
ako wrote: post #66

Earlier quoted context omitted.

Any idea how it compares to oData?

Sorry, no experience with oData so can't give a useful comparison. One obvious difference is that GraphQL requires a structured query, which will always guarantee the structure of the response data. It's like static typing for business data objects. oData seems to embrace REST, so when I request a resource /person/james I have no assurances about what the response will look like. What fields are present? Is "email" a…

OData requests and responses have schemas, so you definitely have assurances on the field types. You _do_ know that email is a string or array of strings. http://docs.oasis-open.org/odata/odata/v4.0/odata-v4.0-part3...

Re: API Design Guide

#150

Post by edblarney »

BigChiefSmokem wrote: post #63
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…

This is an API guideline, not a strict REST one. Also it has become very clear to me everyone has a different interpretation of what REST can or should be. We all are quick to forget that the actual acronym stands for "representational state transfer" which is an abstract concept and therefore can be implemented in many, many different ways.

It's heavy 'REST' oriented.

A Java guideline for API's would like completely different.

Post reply on HN