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

71–80 of 192 posts

Re: API Design Guide

#71

Post by ihsw »

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/

Client libraries can be helpful and sometimes reduce a lot of plumbing/boilerplate that you would end up writing on your own (eg: authentication, paging).

Most environments -- Ruby, Python, PHP -- have minimal HTTP clients in standard libraries however they all have capable third-party libraries. Unirest as you mention, but also Requests for Python or Guzzle for PHP.

Product-specific clients generally build on these third-party libraries or go with the standard libraries instead. The product-specific clients generally offer more comprehensive error handling, for example if an API relies on arcane error codes that wouldn't immediately be obvious to an end-user.

Re: API Design Guide

#72

Post by fixermark »

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…

We're reasoning about a simple case, however. GraphQL is recursive, and HTTP parameters are generally not. You can use them to wrap a recursive language, but at that point you're just using the URL as a transport layer for the recursive language, and if the language is expressive enough it won't fit in a GETtable URL anyway... Past a threshold of complexity, you get into wanting that GraphQL client.

Re: API Design Guide

#73

Post by zeveb »

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 latter specifies a single canonical representation[1], which can be hashed and used for comparison, while the former does not (unless one specifies e.g. alphabetic ordering of properties). The latter format may also has a standard specification for transmission e.g. as a URL parameter[2].

And it's obviously a student-level exercise to write a validator, spec or grammar for the latter format, while the former is rather more open-ended.

Friends don't let friends JSON.

[1] Which HN sadly turns into a linked mess — Base64-decode the transport representation[2] if you'd like to see the canonical representation.

[2] {KDM0Omh0dHA6Ly9qc29uLWxkLm9yZy9jb250ZXh0cy9wZXJzb24oMjppZDM5Omh0dHA6Ly9kYnBl ZGlhLm9yZy9yZXNvdXJjZS9Kb2huX0xlbm5vbikoNDpuYW1lMTE6Sm9obiBMZW5ub24pKDQ6Ym9y bjEwOjE5NDAtMTAtMDkpKDY6c3BvdXNlNDI6aHR0cDovL2RicGVkaWEub3JnL3Jlc291cmNlL0N5 bnRoaWFfTGVubm9uKSk=}

Re: API Design Guide

#74

Post by zeveb »

camus2 wrote: post #18
amingilani wrote: post #11

My biggest pain when designing a rest API is a standard authentication method that won't drive me crazy. So far i've always used 3rd party modules to implement different kinds of authentication but I never quite understood it in depth. Apart from HTTP Basic Auth, but please don't use that.

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

> What's wrong with basic auth with HTTPS?

The only thing wrong that I can see is that it's 2017 and the browsers still don't have a good (indeed, AFAIK, any) UI for logging out.

Re: API Design Guide

#75

Post by zeveb »

camus2 wrote: post #6

Please drop fixed headers from web pages. If you want easy access to the top of the page use anchor links instead. On a laptop headers often take a big chunk of available screen. It just pisses me off every time I see a page with a fixed header. All your reader aren't using imacs...

And it tends to break using Space or Page Down to advance.

I really wonder if hipsters ever actually read web pages, or if they just load them, look at them and then go back to discussing the merits of their fair trade, artisanally-roasted espressos.

Re: API Design Guide

#76

Post by daliwali »

BigChiefSmokem wrote: post #63
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…

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 types and linked data are important for an API to be self-documenting, so there is a rather high bar for developers to implement.

Re: API Design Guide

#77

Post by fixermark »

johnjuuljensen wrote: post #43
amingilani wrote: post #11

My biggest pain when designing a rest API is a standard authentication method that won't drive me crazy. So far i've always used 3rd party modules to implement different kinds of authentication but I never quite understood it in depth. Apart from HTTP Basic Auth, but please don't use that.

Basic auth is great. It lowers the barrier of entry, to anyone with a browser. Not all users of APIs are developers.

https basic auth, I assume you mean.

For http basic auth, you may as well just "secure" the resource by hosting it at http://my-username-and-password.example.com or http://example.com/username/password/resource

Re: API Design Guide

#78

Post by daliwali »

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…

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 the URL in the Location header when it's finished.

REST does not mandate any upper bound on complexity, that's up to you to decide.

Re: API Design Guide

#79

Post by johnjuuljensen »

mateo411 wrote: post #58
johnjuuljensen wrote: post #36

Earlier quoted context omitted.

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?

I should probably have moderated that statement, but mostly I think it's bad because it makes the versioning aspect inaccessible from the lowest common denominator, the browser address bar.

Versioning through the url and versioning through mimetypes requires the same amount of work from the user, but the former is a lot simpler. If you then also take into account, that many http clients have poor support for manipulating headers (SAP and PowerShell (earlier version) for instance), then choosing mimetype versioning makes it harder (impossible) for your users.

Re: API Design Guide

#80

Post by johnjuuljensen »

fixermark wrote: post #77
johnjuuljensen wrote: post #43

Earlier quoted context omitted.

Basic auth is great. It lowers the barrier of entry, to anyone with a browser. Not all users of APIs are developers.

https basic auth, I assume you mean. For http basic auth, you may as well just "secure" the resource by hosting it at http://my-username-and-password.example.com or http://example.com/username/password/resource

I thought https was implied these days :)

Yes absolutely https.

Post reply on HN