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

131–140 of 192 posts

Re: API Design Guide

#131

Post by e1g »

ako wrote: post #66
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…

Any idea how it compares to oData?

Sorry, no experience with oData so can't give a useful comparison. One obvious difference is that GraphQL requires a structured query, which will always guarantee the structure of the response data. It's like static typing for business data objects. oData seems to embrace REST, so when I request a resource /person/james I have no assurances about what the response will look like. What fields are present? Is "email" a string or an array of strings? What's deprecated? RTFM. GraphQL is explicit so I know exactly what data is used in what views - makes change and debugging that much easier.

Re: API Design Guide

#132

Post by nandhp »

zeveb wrote: post #74
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.

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

Or for staying logged in across sessions (or not). But it should be fine for an API.

Re: API Design Guide

#133

Post by nandhp »

hathawsh wrote: post #30
jeppebemad wrote: post #26

I don't see the actual guidelines, only Contents, Introduction and Conventions. On iOS Chrome /Safari. Also the fixed buttons overflows.

The page's responsive design is buggy. On narrow screens, the entire left column disappears. All the important content is only accessible from that left column.

I don't think it disappears, it just moves into the menu button, which seems fairly typical for navigation sidebars on narrow screens.

Re: API Design Guide

#134

Post by rdtsc »

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…

Just guessing, if you had an API for creating documents for example, and you POST a request to /docs/ you'd get back not an just a single ID but a URL to /docs/. So then the client can operate on that resource and not have to compose it.

It can also be browse-able with a regular browser. If you visit it say with Firefox and go to .../api/ and the browser tells the backend it accepts text/html back, the service would return a list of sub-resources as proper hyperlinks. Pretty formatted json and so on. Might return a few items only not all if there are too many in a collection. After you see all sub-resources .../api/docs/ .../api/widgets/ etc. you navigate by clicking to any of those..

I have actually built that and it seemed like gimmick first but improved developer productivity quite a bit because the API is discoverable and provides live data (instead of just out-dated examples from docs that nobody updates.

Was it HATEOAS? I still don't know. But I knew it worked really nicely. Someone working on the backend could finish a feature and stick it in /api/newfeature/ a front-end developer would browser that get a sense of how it works, what data looks like and so on.

(Bonus points: figured a way to auto-generate docs from code comments from classes and modules and pushed them to the API resources, so now it is was self documented, and had live example and so on).

Re: API Design Guide

#135

Post by kevincox »

ex3ndr wrote: post #116

They didn't mention one very important thing - querying only required data and making connections between resources. For example, you need to download some git commits with user profiles. User is a different resource than git repo. How we can request such data in one single request? Then you will need also to load referenced issues (if present) that is implemented as different resource. GraphQL solve this problems in…

If the data is different there is very little need to ask in a single request. Just send two parallel requests. Of course in some cases getting a list of objects is cheaper then multiple requests but that is only if the objects are "related" and stored together.

However I do agree that GraphQL is great for a lot of use cases.

Re: API Design Guide

#137

Post by joncalhoun »

theptip wrote: post #115

An interesting design question arrises around nested resources. Google in this doc buys into deep nested structures, e.g. `//calendar.googleapis.com/users/john smith/events/123` (from [1]). I think this pattern is unambiguously sensible when the child objects are strictly scoped under the parent. But it's less clear how to represent resources that are shared between multiple parents; for example, what if event 123 ca…

I prefer the bare minimum approach. That is, if you NEED the user resource to access the event (eg the primary key is like [user ID, event ID]) then nest it in the url. Otherwise if an object has its own ID and could otherwise be accessed independently why not just do so?

Re: API Design Guide

#138

Post by scarface74 »

mbesto wrote: post #27
scarface74 wrote: post #25

Earlier quoted context omitted.

If you're using a good framework like C# Web Api, you don't have to choose. Just implement them all by adding them to the pipeline and the framework will automatically serialize/deserialize based on the accept header.

Interesting, do you have more details about this?

You register your custom serializer at application startup...

http://www.strathweb.com/2014/11/formatters-asp-net-mvc-6/

Your controller action looks like this:

public List Get() { ..... return employeeList; }

Based on the serializers you have registered and the request Accept header, WebApi will serialize the list into JSON, XML, BSon (all built in) or a custom serializer that you add like Protocal Buffers

http://www.infoworld.com/article/2982579/application-archite...

Basically you can have all four registered and the client decides what it accepts.

Re: API Design Guide

#139

Post by JimDabell »

johnjuuljensen wrote: post #79
mateo411 wrote: post #58

Earlier quoted context omitted.

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

> mostly I think it's bad because it makes the versioning aspect inaccessible from the lowest common denominator, the browser address bar.

That also rules out using any HTTP method other than GET. The browser address bar doesn't seem relevant here, and if it were, then it would rule out the vast majority of APIs.

Versioning through the URL breaks interoperability of clients using different protocol versions. If a client using v1 communicates with a client using v2, then they will see two separate sets of resources and they would never have the same identifiers for (what should be) the same resources.

Re: API Design Guide

#140

Post by theptip »

combatentropy wrote: post #124
theptip wrote: post #115

An interesting design question arrises around nested resources. Google in this doc buys into deep nested structures, e.g. `//calendar.googleapis.com/users/john smith/events/123` (from [1]). I think this pattern is unambiguously sensible when the child objects are strictly scoped under the parent. But it's less clear how to represent resources that are shared between multiple parents; for example, what if event 123 ca…

Here's one way to tackle it, if behind your REST API is an SQL database: /schema/table/key So: //www.example.com/calendar/events/123 To address many records, like all that belong to Bob, use the query string instead of purely the path: //www.example.com/calendar/events/?user=bob

This is in my experience the `standard` design; it does give you a lot of freedom to change what filters you allow, and to stack them. Nobody's going to get fired for this design, and there's a lot of prior art around it to draw examples from. It also has the benefit of keeping the API surface small and clean.

But it makes it a bit weird to do HATEOAS; you _could_ do `GET Bob => {events: "calendar/events/?user=bob"}` -- but then you're hyperlinking to a search and not a resource.

It also tells less of a narrative in the structure; `user=bob` is just another filter that you can use to apply to the events set. But we get a chance to describe the shape of the data a bit more if we choose to declare an intermediate resource (/users/) and attach some links to it (=>/users/bob/events).

Now, if there are ten ways that you need to slice your `events` set, and ?user=bob is but one of them, then scoping a sub-resource /users/events/ isn't that useful/descriptive.

As an aside, I think this is where HATEOAS is nice; it makes it very easy to navigate an API as a developer, see what actions are possible at every node, and hopefully learn the intent of the author of the API without having to chew through a set of API documentation. Django Rest Framework's API browser is a great example here.

Post reply on HN