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]?
API Design Guide
61–70 of 192 posts
Re: API Design Guide
#62Earlier quoted context omitted.
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.
That's where we started.
The next natural step will be - "Thanks for the comments, now the user needs to sort them by votes/date, ok?" and the URL starts looking like a query anyway, so you're on the way of re-implementing GraphQL. Then do you send avatars/timestamps/changeflags for all comments, or only on main body in this endpoint? Now you have the over/under-fetching problems.
The step after that will be "Oh there are 300 of them - I just want the top 3 comments first, and a pager for the rest ok?" and you simply can't do that with the structure REST mandates.
Re: API Design Guide
#63What 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.
Re: API Design Guide
#64Earlier 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.
Yeah.. The bigger issue with this app is that it responds with a default apache 404 page instead of a 404 code + its usual xml response.
Re: API Design Guide
#65Earlier 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 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 or HTML, without needing specialized tooling such as a GraphQL client. A hyperlink makes that query widely accessible and interoperable with any HTTP client.
Re: API Design Guide
#66I 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…
Any idea how it compares to oData?
Re: API Design Guide
#67Earlier quoted context omitted.
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.
That's where we started. The next natural step will be - "Thanks for the comments, now the user needs to sort them by votes/date, ok?" and the URL starts looking like a query anyway, so you're on the way of re-implementing GraphQL. Then do you send avatars/timestamps/changeflags for all comments, or only on main body in this endpoint? Now you have the over/under-fetching problems. The step after that will be "Oh ther…
>the structure REST mandates.
There is no structure that REST mandates, if there were it would be a specification and not an architectural style. There is nothing that says that you can't query for that:
GET /comments?sort=votes&limit=3
The exact string doesn't matter, what matters is the client can discover this. How HTML does this is by generating query parameters based on form inputs.
Re: API Design Guide
#68Earlier 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…
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…
Context: Friendly banter
>> Bottom line - your server should always return HTTP status 200 and a separate API error response.
That is a very absolute statement from a pragmatic guy, asking people to concede viewpoints other than their own :)
I'd be interested in learning how status codes other than 200 cause problems at scale though?
Re: API Design Guide
#69What 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.
[deleted]
Re: API Design Guide
#70Earlier 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…
Indeed you need a client that is capable of mapping allowed methods and links to something useful, but it's not hard to imagine how one might go about this:
* For related resources (imagine a DB FK), instead of listing a uuid you point a link to the location of that resource. This means if the resource location changes the client doesn't need to be updated, it just uses whatever the new link is.
* Methods listed can drive available actions, e.g. imagine you have both mutable and immutable objects, a smart client could reason if PATCH is available then a UI element can be spawned allowing the user to modify this resource.
This is useful in a single client scenario whereby the API schema can be modified to a certain extent without the need to modify the client. It is also useful in a multi-client scenario (either distinct or versioned clients) for ensuring consistency between clients as you no longer need to ensure all clients are modified to use the new schema.
At least, this is how I understood it, I haven't tried it in practice.