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

51–60 of 192 posts

Re: API Design Guide

#51

Post by programd »

johnjuuljensen wrote: post #39
programd wrote: post #24

Earlier quoted context omitted.

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

Thank you all for the good responses on the error code issue. I particularly appreciate the ops view on this, e.g. the existence of much tooling around monitoring HTTP codes. Since I'm a pragmatist I'm not going to defend my point of view too vigorously, but concede that there are other considerations, particularly when designing services to work at scale. Everything breaks at scale, including many things we believe to be wise and true :)

Re: API Design Guide

#52

Post by justinsaccount »

johnjuuljensen wrote: post #39
programd wrote: post #24

Earlier quoted context omitted.

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

The problem with things like 404 is then you need to differentiate between

"Hi, this is the application and the object/document/whatever you are looking for was not found"

with

"Hi, this is the server and the api endpoint was not found"

An API I use returns a standard apache 404 error page when the item you are looking up doesn't exist. If the API endpoint was renamed my code that consumes it wouldn't have any idea anything was wrong.

Re: API Design Guide

#53

Post by programd »

moca wrote: post #8
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.

Thanks for the comment. The error handling chapter will be published in a few weeks. For now, you can reference https://github.com/googleapis/googleapis/blob/master/google/... . Disclaimer: I am one of the co-authors.

Canonical error codes used by Google, mapped to HTTP error codes: https://github.com/googleapis/googleapis/blob/master/google/...

Re: API Design Guide

#54

Post by euyyn »

justinsaccount wrote: post #52
johnjuuljensen wrote: post #39

Earlier quoted context omitted.

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

The problem with things like 404 is then you need to differentiate between "Hi, this is the application and the object/document/whatever you are looking for was not found" with "Hi, this is the server and the api endpoint was not found" An API I use returns a standard apache 404 error page when the item you are looking up doesn't exist. If the API endpoint was renamed my code that consumes it wouldn't have any idea a…

I mean, if the API endpoint is renamed, they have broken all their clients.

Re: API Design Guide

#55

Post by daliwali »

justinsaccount wrote: post #48
daliwali wrote: post #34

Earlier quoted context omitted.

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.

REST describes relationships just fine. Now return a list of 100 documents that each have a list of related comments. Your client just needs to request GET /documents GET /documents/1/comments GET /documents/2/comments GET /documents/3/comments GET /documents/4/comments GET /documents/5/comments .. GET /documents/99/comments GET /documents/100/comments Easy, right?

Easy mode: GET /documents?include=comments

Think of how this can be done on a web page. The documents page has a link to follow, "include comments", which links to "?include=comments". The exact query doesn't matter, what's important is that a client can discover new information without needing any out-of-band information.

Re: API Design Guide

#57

Post by SEJeff »

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.

FWIW, Roy Fielding's paper[1] on REST (where the word comes from) was very specific that a REST api is a hypermedia/hypertext based api, and that if it isn't hypermedia, it isn't REST. He clarified[2] this later on. This isn't from some internet toughguy, but the guy who literally coined the phrase. Sadly, his implementation was also all XML so gross, but you get the idea. HATEOS is just an implementation of a JSON based hypermedia api.

Me? I'm a fan of grpc for everything. HTTP/2 > HTTP1 and binary compressed protobuffers > deflate compressed (gz) json. http://grpc.io

[1] https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arc...

[2] http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte...

Re: API Design Guide

#58

Post by mateo411 »

johnjuuljensen wrote: post #36
veesahni wrote: post #32

Earlier quoted context omitted.

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.

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

Re: API Design Guide

#59

Post by johnjuuljensen »

justinsaccount wrote: post #52
johnjuuljensen wrote: post #39

Earlier quoted context omitted.

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

The problem with things like 404 is then you need to differentiate between "Hi, this is the application and the object/document/whatever you are looking for was not found" with "Hi, this is the server and the api endpoint was not found" An API I use returns a standard apache 404 error page when the item you are looking up doesn't exist. If the API endpoint was renamed my code that consumes it wouldn't have any idea a…

Yes, an additional 4xx code to help differentiate between api endpoints and resources would be nice.

I didn't mean to imply that HTTP status codes could stand alone as error messages, so for a 404 error I'd also respond with more data, to help the user identify the issue.

Re: API Design Guide

#60

Post by e1g »

daliwali wrote: post #34
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…

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.

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 {
         country {
           name, population, flag
         }
      }
    }
No separate endpoint. You want to show to the client how many dogs those friends have, and if any of them play frisbee? No problems, and no backend engineers involved.

This is why I said REST is a key-value protocol like in redis. With redis you can either embed a small objects (which is not a relationship) or keep a PK of the relationships (which means many queries). The more consumers your API has, and the higher the latency, the more expensive either of those choices becomes.

Post reply on HN