API Practices If You Hate Your Customers
https://cacm.acm.org/magazines/2019/12/241052-api-practices-...
Best practices for REST API design (2020)
101–110 of 273 posts
Re: Best practices for REST API design (2020)
#102Earlier quoted context omitted.
As a user I expect that to happen. Cursors on the other hand are awful for getting to arbitrary pages, they are mostly useful for "More" links as on HN or Reddit. It's a trade-off.
I’d say they’re right: cursors are way better for an API. Pages are way better for a person. This here is about an API.
How often do people really jump to an arbitrary page? I'd say filtering / searching capabilities are far more important for users than paging.
Re: Best practices for REST API design (2020)
#103A question I’ve always had about 404 and APIs... How do you distinguish between an invalid path (no end point) and a valid path requesting a resource that doesn’t exist?
valid path: maybe return 200 (the request is ok), but return an empty object.
invalid path: 404
Re: Best practices for REST API design (2020)
#104I’d say REST apis should also support selections. E.g I only care about these fields. It’s the #1 reason why graphql is so popular. You only fetch what you want. But I have missed feelings about graphql. I wish they didn’t invent a new language, it was just json. I’ve encountered so many little bugs because graphql parsing is different between different servers. Ideas of graphql are great, implementation seems over c…
You can do it with query params. Its not enforced or consistent because not everything that serves data can parse the data. You could throw static json blobs on S3 as a rest API but selections would not be supported.
I wish S3 supported filters on predefined content - eg. json. That would be a killer feature
Re: Best practices for REST API design (2020)
#105All these "best practices" are exactly why I embraced GraphQL quickly and flushed "REST" down the toilets for big projects (http+json is fine for small ones, since no lib overhead). GraphQL is unashamedly the new SOAP. I.e. we have a spec, not a series of "best practices" thus endless architectural debates where people are shamed for 'doing it the wrong way' online. - Accept and respond with JSON: No, why? what if I…
Never understood the hype around GraphQL. You want to know how to halve your performance and responses/s on your service? add graphql. All things that GraphQL claims to do can be implemented in RESTful services easily. If you want specificity in your query fetching, just add query params or put them in the request body If you want schema validations, there are many libraries that help you with that. And if you want d…
I think people like it because the popular frontend library (Apollo) makes certain things easy in React, like caching.
From a backend perspective, it's about 100x more work than dumb RPC (which I prefer over "REST"). I have spent so much time becoming aware of very "interesting" decisions. For example, gqlgen for Go generates code that fetches every element of a slice in parallel. We used to create one database transaction per HTTP request, but you can't do this with GraphQL, because it fetches each row of the database in a separate goroutine, and that is not something you can do with database transactions. It's also exceedingly inefficient.
All in all, it's clear to me that GraphQL is built with the mindset that you are reaching out to an external service to fetch every piece of data. That makes a lot of sense in certain use cases, but makes less sense if you are just building a CRUD app that talks to a single database.
I am hoping that people get bored with this and make gRPC/Web not require a terabyte of Javascript to be sent to the client. RPCs are so easy. Call a function with an argument. Receive a return value and status code. Easy. Boring. It's perfect.
Re: Best practices for REST API design (2020)
#106Earlier quoted context omitted.
Never understood the hype around GraphQL. You want to know how to halve your performance and responses/s on your service? add graphql. All things that GraphQL claims to do can be implemented in RESTful services easily. If you want specificity in your query fetching, just add query params or put them in the request body If you want schema validations, there are many libraries that help you with that. And if you want d…
For comprehensive APIs,GraphQL is often more performant. 1 request that takes 500ms is far better to 5 requests that take 200ms
You can create a single endpoint that's non-RESTFul to make a single call.
Re: Best practices for REST API design (2020)
#107Do not use a page argument for pagination. If you have another process/client concurrently adding/removing items, then some items will be returned twice, and others will never be returned. It is better to use, for example, the ID of the last returned item as a starting point for the next query.
What does Hackernews use in this case?
from what I can tell, every item in the hackernews data set is a monotonically increasing integer id and comments/posts are not fundamentally treated differently.
for instance your comment is 26227524
and the parent post is 26225373
edit: hacker news pagination is not high priority apparently since they just use the easiest way with p= some number.
Re: Best practices for REST API design (2020)
#108Earlier quoted context omitted.
Unless I’m missing something, the response schema will have an optional “comments” field whether the “with_comments” arg is passed or not.
it's just a hit to the db. Graphql works the same way if i'm not mistaken. and if its the case that you don't want the comments at all, then in the conditionals write your sql statements if you want comments select * from resource where id= some resource id if you don't select without comments from resource where id= some resource id there's no need to get into specifics, the point is graphql is not bringing anything…
I’m talking about the GraphQL or OAS schema.
With a REST API, the “resource” type will always have an optional “comments” field, whatever the value of arg is.
With a GraphQL API you’ll have the right type depending on your query.
Re: Best practices for REST API design (2020)
#109Earlier quoted context omitted.
So, what you are saying is reimplement graphQL.
no, what im saying is graphql is introducing something they think is novel, when it already can be done in REST. it's not hard. In my specific case, using Flask-Marshmallow i can do this ``` some_resource = Resource.find_by_id(resource_id) arg = request.args.get('type_of_resource') if arg == 'with_commments': return full_resource_schema.dump(some_resource), 200 if arg == 'no_comments': return no_comments_schema.dump(…
What would you do if someone wanted:
- some fields of the resource - some fields of the comments - some fields of the user that made the comments
Re: Best practices for REST API design (2020)
#110Earlier quoted context omitted.
What does Hackernews use in this case?
from what I can tell, every item in the hackernews data set is a monotonically increasing integer id and comments/posts are not fundamentally treated differently. for instance your comment is 26227524 and the parent post is 26225373 edit: hacker news pagination is not high priority apparently since they just use the easiest way with p= some number.
It's okay for a submission to show up twice/not show up at all on a single page view of HN, so I can see why it wouldn't be a priority.