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

91–100 of 192 posts

Re: API Design Guide

#91

Post by thesandlord »

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/

I've used the simpler GCP APIs (like the Machine Learning ones) with direct REST calls. I've also been forced to use the REST API for things like Google Sheets because the client library documentation was so confusing.

For more complicated services, using a client library makes sense. Why reinvent the wheel?

With gRPC/Swagger/OpenAPI/etc you can also generate your own client stubs if you need to.

IMO, if you require a client library, there better be a really good reason...

(I work at Google Cloud, and often work with the API/libraries team. Opinions are my own)

Re: API Design Guide

#92

Post by daliwali »

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…

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/rest-apis-must-be-hyperte...

Re: API Design Guide

#93

Post by jauco »

daliwali wrote: post #65
e1g wrote: post #60

Earlier quoted context omitted.

REST limits my knowledge only to the primary key of the relationship. Given a trivial question like "here's a user, I need her friends and their countries of birth" and the REST answer is a separate endpoint or an O(n) operation on the client because these are _separate resources_. You want the country flag too? I'm sorry, I can't support that requirement. With GraphQL, it's - user(handle: "daliwali") { name, friends…

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…

that's almost exactly what a graphql get looks like

    http://myapi/graphql?query={me{name}}
http://graphql.org/learn/serving-over-http/#get-request

Re: API Design Guide

#94

Post by vfaronov »

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.

> In that sense, REST in practice has always been just RPC without a clear spec for procedure call like XML or JSON RPC.

HTTP, even when used without hypermedia, still has interesting features that are not found in traditional RPC. For example, you can’t just stick nginx in front of your gRPC server and tell it to cache stuff. You can’t tell your Thrift client to retry all idempotent requests automatically (without enumerating the functions that are idempotent). Not to mention upcoming things like HTTP/2 push and 103 (Early Hints).

I like to think that HTTP is less of a leaky abstraction over the network.

Re: API Design Guide

#95

Post by [deleted] »

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…

[deleted]

Re: API Design Guide

#96

Post by daliwali »

squeaky-clean wrote: post #89
daliwali wrote: post #78

Earlier quoted context omitted.

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?

>it's so different and you've added so much work to it

With web pages, it's standard and effortlessly handled by the browser. Given a form with inputs specified by the server, a client sends a request with media type application/x-www-form-urlencoded or multipart/form-data. There is a vast number of implementations for practically every language and platform. A machine client can send a form too, or JSON for that matter.

You have it backwards, Facebook is attempting to rewrite web standards by themselves. And that is undermining the open web.

Re: API Design Guide

#97

Post by rodionos »

veesahni wrote: post #50
rodionos wrote: post #41

HTTP Method DELETE. Payload: empty. I know DELETE is not supposed to have any payload, but using PATCH is awkward if you have to delete multiple resources based on a query or a filter. You need to specify a 'delete' action as part of PATCH request which means the payload model has to be different. Just awkward.

A bulk deletion isn't defined as part of their "Standard Methods" .. For stuff that doesn't fit the standard methods, they have this page on custom methods: https://cloud.google.com/apis/design/custom_methods That said, I'd implement a bulk deletion in one of three ways: :::: ONE DELETE /thingies/id1,id2,id3 When all is ok, the response is a 200. However, if one of the deletions fail, how you handle the response is m…

  POST /thingies/bulk_delete
Exactly. That's the approach we've taken. It has worked better for us than sending a delete action via PATCH.

Re: API Design Guide

#98

Post by [deleted] »

daliwali wrote: post #76
BigChiefSmokem wrote: post #63

Earlier quoted context omitted.

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 has become very clear to me everyone has a different interpretation of what REST can or should be This is very true, the term has been abused so much that it has no relation to its original meaning. We can loosely define REST by one of its key qualities: hypermedia, that is a lot easier to say than HATEOAS. By focusing on this distinction, it rules out 99% of APIs in the wild. On top of that, hypermedia media typ…

[deleted]

Re: API Design Guide

#99

Post by tomschlick »

avenoir wrote: post #19
camus2 wrote: post #18

Earlier quoted context omitted.

> Apart from HTTP Basic Auth, but please don't use that. What's wrong with basic auth with HTTPS? You can delegate authentication with OAUTH and then use OAUTH for authorization but authentication still has to be done somewhere.

I think Twillio API still uses or used basic auth via HTTPS.

So does Stripe. There is nothing wrong with basic auth for api tokens so long as you're using HTTPS.

Re: API Design Guide

#100

Post by solipsism »

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…

Don't worry, the term HATEOAS won't become trendy any time soon.
Post reply on HN