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

101–110 of 192 posts

Re: API Design Guide

#101

Post by einrealist »

daliwali wrote: post #83
zeveb wrote: post #73

Earlier quoted context omitted.

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.

I'd argue, choose whatever format is best for your case. If its easy, chose a binary format for small footprint and a human readable format. But chose formats that are semantic and are able to drive the client. That's what the "R"epresentation is all about in "REST".

Re: API Design Guide

#102

Post by [deleted] »

SEJeff wrote: post #57
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.

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

[deleted]

Re: API Design Guide

#103

Post by moca »

somedumbguy22 wrote: post #56

I wonder if someone from the Apigee team wrote these, as Google recently acquired Apigee[1], and the guidelines are mostly inline with what Apigee recommends.[2] [1] https://techcrunch.com/2016/09/08/google-will-acquire-apigee... [2] https://apigee.com/about/resources/ebooks/web-api-design

This guide has been in use since 2014, including recently launched Cloud Spanner API.

Disclaimer: co-author of the design guide.

Re: API Design Guide

#104

Post by hadriendavid »

zerocrates wrote: post #44
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.

It's just never been clear to me what HATEOAS is really supposed to be good for. Sure, a client can follow the links in an automated fashion, but how is it supposed to know what the resources actually are and which links it needs to follow, which resources it has to create or modify, to actually accomplish anything? The general idea of returning links to related resources and/or actions is fine and good, but the rhet…

How I interpret HATEOAS:

The client knows what and how it can access on the behalf of the authenticated user. Examples:

Representation for a user with no privileges:

    {
        "articles": [{
            "id": 123
            "title": "A title",
            "links": {
                "self": {
                    "href": "http://blog.com/articles/123",
                    "methods": ["GET"]
                }
            }
        }],
        "links": {
            "self": {
                "href": "http://blog.com/articles",
                "methods": ["GET"]
            }
        }
    }
Representation for a user who is authorized to add/edit/delete articles:

    {
        "articles": [{
            "id": 123
            "title": "A title",
            "links": {
                "self": {
                    "href": "http://blog.com/articles/123",
                    "methods": ["GET", "DELETE", "PUT"]
                }
            }
        }],
        "links": {
            "self": {
                "href": "http://blog.com/articles",
                "methods": ["GET", "POST"]
            }
        }
    }
This reduces the authorization logic on the client side.

Re: API Design Guide

#105

Post by pbreit »

thesandlord wrote: post #91
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…

Isn't building a client library for a REST API the definition of reinventing the wheel?

Re: API Design Guide

#106

Post by eveningcoffee »

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…

What about status=ok|error[|partial]? how do you feel about this? Given its value you may have either result or errors attribute.

Re: API Design Guide

#107

Post by eveningcoffee »

johnjuuljensen wrote: post #59
justinsaccount wrote: post #52

Earlier quoted context omitted.

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.

I think that this example illustrates why parent mentioned that this is a trap.

Re: API Design Guide

#108

Post by euyyn »

arohner wrote: post #84
euyyn wrote: post #14

Earlier quoted context omitted.

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

Ah, yeah, coding the OAuth2 flow in a new language (vs using an existing library) is tricky, at the very least because OAuth2 itself is complex. The best docs I know for that are here https://developers.google.com/identity/protocols/OAuth2Servi... (we should link to it from the docs of the Cloud APIs).

From a glimpse, what's said there matches what your code is doing, so thanks a lot for sharing it!

Re: API Design Guide

#109

Post by fosk »

zerocrates wrote: post #44
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.

It's just never been clear to me what HATEOAS is really supposed to be good for. Sure, a client can follow the links in an automated fashion, but how is it supposed to know what the resources actually are and which links it needs to follow, which resources it has to create or modify, to actually accomplish anything? The general idea of returning links to related resources and/or actions is fine and good, but the rhet…

To me the best advantage is that by following links, the client doesn't have to builds those links in the first place.

So the client will keep working even if a few months from now you want to change the link to something else. A simple example: if retrieving articles can be done by requesting this link "/articles", I can potentially change it in the future to "/v2/articles" and the client would still work.

Re: API Design Guide

#110

Post by rexpop »

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…

Wow, it seems linguistic prescriptivism has a stronger foothold in engineering domains. Probably fewer social class issues.
Post reply on HN