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

81–90 of 192 posts

Re: API Design Guide

#81

Post by tyingq »

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.

Re: API Design Guide

#82

Post by chatmasta »

camus2 wrote: post #15
chatmasta wrote: post #9

Earlier quoted context omitted.

This is a marketing website. I'm sure they A/B tested the fixed header and it probably converts better than otherwise.

This isn't a marketing website this is the documentation website for google cloud. I'm logged in right now on google cloud and it's still displaying that header.

Yeah? Who's paying google the big bills? The people who are looking to "CONTACT SALES," which is conveniently a link in the fixed header.

Re: API Design Guide

#83

Post by daliwali »

zeveb wrote: post #73
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…

How is: { "@context": "http://json-ld.org/contexts/person.jsonld", "@id": "http://dbpedia.org/resource/John_Lennon", "name": "John Lennon", "born": "1940-10-09", "spouse": "http://dbpedia.org/resource/Cynthia_Lennon" } Better than: (http://json-ld.org/contexts/person (id http://dbpedia.org/resource/John_Lennon) (name "John Lennon") (born 1940-10-09) (spouse http://dbpedia.org/resource/Cynthia_Lennon)) Note that the l…

The answer to that is really simple: JSON is a widely supported standard in many platforms and languages. Whatever the latter is, is not.

What's better than writing a parser for the latter format, is not having to write anything and just using a library, which exists in practically every language for JSON.

Re: API Design Guide

#84

Post by arohner »

euyyn wrote: post #14
arohner wrote: post #3

Step 1) document the endpoints enough that outside developers can write their own clients. It took quite a bit of work for me to get a native Clojure client working to connect to the google cloud SDK. That was after wrestling with jar-hell around gRPC and calling the Java client from clojure, which is decidedly not pretty.

For future reference, here's the HTTP/REST documentation for the Cloud APIs: https://cloud.google.com/apis/docs/overview E.g. for the GKE API: https://cloud.google.com/container-engine/reference/rest/ (For people that rather use an existing library, this lets you pick one of 7 languages and start from there: https://cloud.google.com/docs/ )

Yes, but that doesn't deal with authentication. My problem was getting the JWT stuff working. The solution ended up being: https://gist.github.com/arohner/8d94ee5704b1c0c1b206186525d9...

Re: API Design Guide

#85

Post by tom_b »

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…

I personally like collection+json as a response type for REST. I will say that my own efforts at using a hypermedia-containing response type for a REST api shared across several teams have been mostly wasted effort. Consumers of the api treat the responses as plain-old JSON which somewhat kills the advantages of having a proper REST response in the first place . . .

Re: API Design Guide

#86

Post by orasis »

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…

You are just plain wrong. HTTP was designed to access and update named resources. Those status codes correspond to the status of that resource so are totally appropriate no matter if the resource is a static HTML file or a database driven JSON response. I would hate to consume your APIs over HTTP.

Re: API Design Guide

#87

Post by mcherm »

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 you consider to be "ad hoc JSON-over-HTTP services".

Sure, I've read Fielding's dissertation.[1] I think stateless, cacheable, layered systems are a great idea. I think "code on demand" is (usually) a stupid one... even if it does turn out to work surprisingly well for web browsers. But none of those matter.

I work with people who build "ad hoc JSON-over-HTTP services". They spend hundreds of millions of dollars building ad hoc JSON-over-HTTP services. They call them "REST" services.

I have to talk to these people, so I call them "REST" services too. Because I'd rather build something useful than spend time telling people that they're using a word "wrong", when the only real meaning of a word is whatever it will bring to mind in the person you are communicating with.

[1]: http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm

Re: API Design Guide

#88

Post by jauco »

camus2 wrote: post #12
andreygrehov wrote: post #5

I would like to add Microsoft's API Guidelines [1] here, which is also a well written document and can be helpful to anyone designing an API. [1]: https://github.com/Microsoft/api-guidelines/blob/master/Guid...

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 specific framework he might not be able to follow that structure, or it might be harder then necessary.

If instead, your specification only specifies the document layout (Roy Fielding calls it the "media type") then it's easier for people to implement your api. People usually have full control over the document contents.

If you don't design your API like that it's not a REST Api according to Roy Fielding. If your API is not going to be implemented by many providers and many consumers all talking to each other in countless permutations then there's not much use in following all of REST[1]. (And also not much use in calling your API a rest api)

Of course the word REST now means something else then Roy Fielding intended for it. I have no problem with that. I believe he did at some point.

[1] I don't remember the url or the exact quote, but I believe I read a piece by him where he said literally that REST as he described it is only useful for the many2many consumer/provider use case. I might be mistaken.

Re: API Design Guide

#89

Post by squeaky-clean »

daliwali wrote: post #78
daliwali wrote: post #65

Earlier quoted context omitted.

You are correct that in a REST system, every resource has a "primary key", that is the URL. Where you are wrong is that REST doesn't mandate that a resource can only be accessed by its "primary key". There is nothing stopping me from requesting the following URL: GET /users/daliwali?fields=name&include=friends,friends.country Any client would be able to follow that link and get something out of it, whether it's JSON…

In reply to fixermark, there is also nothing stopping you from very complicated queries in REST. There is not even a requirement that the server must respond immediately. For example I could request: POST /queries With some raw database query as the payload (please don't actually do this) and the server could respond with HTTP 202 Accepted, meaning that it's going to take some time to process, meanwhile check back at…

But at this point, it's so different and you've added so much work to it, I doubt anyone would recognize it as originally REST. You're basically rewriting GraphQL yourself. And sure, you're allowed to do that, but why?

Re: API Design Guide

#90

Post by nevi-me »

Very interesting read! I like that GOOG is pushing gRPC more on their own services. I've been a gRPC user since Sep/Oct last year, and it's made developing for Android, Node.js, JVM, Python more pleasant from a networking perspective. The ease of just moving logic from Node.js to a Java gRPC server, and then redirecting the HTTP2 proxy to the right place, has been awesome.

I've started teaching some people in the team how to use gRPC, and we're def going to be using it where permissible on client projects.

Post reply on HN