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

31–40 of 192 posts

Re: API Design Guide

#31

Post by einrealist »

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.

I think, there is just too much bias involved. At least thats what I am experiencing. Not using HATEOAS ever, but complaining about it makes me angry.

My preaching: If you can write a client by using a semantic document format (e.g. HTML, XML+XSD, Json-Ld), you end up with a more elegant and stable implementation. And as a provider of such an API, I spend more focus on the surfacing domain than the structure of my resources.

It makes me sad, that even Google does not try.

Re: API Design Guide

#32

Post by veesahni »

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.

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]

Re: API Design Guide

#33

Post by [deleted] »

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.

[deleted]

Re: API Design Guide

#34

Post by daliwali »

e1g wrote: post #29
etaty wrote: post #10

I am curious if anyone went to GraphQL without regrets?

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…

REST describes relationships very well, via hyperlinks. You navigated to this page via a hyperlink. If your API doesn't do that, it's not REST, this is what people usually mean when they point out that an API isn't complying to the REST style.

Re: API Design Guide

#36

Post by johnjuuljensen »

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]

Code can follow links as well, as long as the semantics doesn't change.

Aside from versioning through mimetypes, which I believe is a really bad idea, I find HATEOAS to be a beautiful concept, although not very useful in practice.

It's a good place to start though. Trying to design for that can help you shape your API properly, just like SOLID or TDD can do for code.

Re: API Design Guide

#37

Post by aaronblohowiak »

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…

That is great in theory but it throws out all of the deeply rooted tooling that reports and aggregates http status codes across the service architecture. It is nice to be able to tail the apache log and see the status. In your situation I would need to have an additional system that uses application details for similar purposes.. you can do it as you describe but there is a cost! It is also against convention, which increases the custom tribal knowledge that people working in that system have to acquire. By the time you "outgrow" http I assume you'd have custom metrics and logging/tracing, but I would not suggest it as a good place to start.

Re: API Design Guide

#38

Post by moca »

lilbobbytables wrote: post #13
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.

Well, I can tell you from using their API's that Google doesn't necessarily use them. I don't recall that specific scenarios, but over the past year I learned this with the maps API. As long as you're hitting a real endpoint, then it will return 200 - even when there are errors and it should clearly return a matching http status code. I suppose it so the same API could be implemented in any given protocol, however, I…

Many Google APIs were created before this guide. New APIs published at https://github.com/googleapis follow this guide. Having the same API available via both REST and gRPC is very valuable, as gRPC often provides 10x performance.

Re: API Design Guide

#39

Post by johnjuuljensen »

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…

HTTP has some very useful status codes, which convey standard conditions found in most apis: 200, 201, 400, 401, 404, 403, 406, 429, 500

Also note that not all APIs will be used be developers. Often it's someone less proficient with programming, and you can't rely on them to check the content of the return message. Help them help themselves by making curl (or whatever) bitch when there is an error.

It takes a bit more work to design an API that works over multiple transports, but a good framework, such as Servicestack.net if your in .Net land, mostly does it for you. By advocating 200 for all responses you're basically reverting to SOAP and WCF (Windows Communication Foundation).

Each to his own though, and for internal stuff, it might make a lot more sense.

Re: API Design Guide

#40

Post by daliwali »

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 service.

There is a standardized solution for machine-to-machine REST: JSON-LD [1], with best practices[2] to follow, and even some formalized specs[3][4]. To Google's credit, they are now parsing JSON-LD in search results, which is much nicer to read and write than the various HTML-based micro-data formats.

On a related note, REST has nothing to do with pretty URLs, naming conventions, or even HTTP verbs. That is to say, it is independent of the HTTP protocol, but maps quite naturally to it.

[1]: http://json-ld.org/

[2]: http://json-ld.org/spec/latest/json-ld-api-best-practices/

[3]: http://micro-api.org/

[4]: http://www.markus-lanthaler.com/hydra/

Post reply on HN