Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Best practices for REST API design (2020)

stackoverflow.blog

Post reply on HN
Print view View original

121–130 of 273 posts

Re: Best practices for REST API design (2020)

#121

Post by etxm »

packetlost wrote: post #49
mhoad wrote: post #25

Just for a point of reference here is Google’s take on the exact same topic. It has a bit more of a gRPC background but still is very REST friendly by default. https://cloud.google.com/apis/design/resources Also as one of the most common pushbacks people have with gRPC is that everyone generally expects JSON still in 2021 especially in the browser. Not sure if this is super well known or not but gRPC integrates well…

gRPC is also a 300lb gorilla of a framework for communication and has huge problems with versioning if you aren't "running at HEAD".

That’s a skinny gorilla.

Re: Best practices for REST API design (2020)

#122

Post by capableweb »

Toutouxc wrote: post #111
capableweb wrote: post #87

Earlier quoted context omitted.

It's less buzzwords and more that you're required to understand HTTP and probably be a programmer to understand what's being said. For you and other non-programmers: https://tools.ietf.org/id/draft-ietf-httpbis-semantics-03.ht... (particularly https://tools.ietf.org/id/draft-ietf-httpbis-semantics-03.ht... ) Also knowing that mochiweb is a library for doing HTTP servers would help. Once you've learned these two, the…

> For you and other non-programmers > Once you've learned these two, the sentence immediately becomes clear > it can sound like mumbo-jumbo, but I'm sure it makes sense for them, since they are professionals Did you just link a person to a two-kilometer long page about HTTP, assumed they're not a programmer and almost accused them of not being professional enough, because they haven't heard of some Erlang library? >…

> Did you just link a person to a two-kilometer long page about HTTP, assumed they're not a programmer and almost accused them of not being professional enough, because they haven't heard of some Erlang library?

Nope, I linked to a specific section of a HTTP specification that goes through "Content Negotiation" since that was what the topic was about and I wanted to share a resource to spelunker so they could read more about it, as if you're familiar with the topic, what seliopou wrote is not alien.

Re: Best practices for REST API design (2020)

#123

Post by capableweb »

pionar wrote: post #114
capableweb wrote: post #87

Earlier quoted context omitted.

It's less buzzwords and more that you're required to understand HTTP and probably be a programmer to understand what's being said. For you and other non-programmers: https://tools.ietf.org/id/draft-ietf-httpbis-semantics-03.ht... (particularly https://tools.ietf.org/id/draft-ietf-httpbis-semantics-03.ht... ) Also knowing that mochiweb is a library for doing HTTP servers would help. Once you've learned these two, the…

I'm a programmer, and I know HTTP quite well. I know what HTTP semantics are, and this sentence is still gibberish to me. I'd wager the reason I don't is because I'm not that familiar with the erlang ecosystem, so have no idea what mochiweb is, and don't know what this does differently. Your first sentence was quite condescending, FYI, not sure if it was meant to be.

> Your first sentence was quite condescending, FYI, not sure if it was meant to be.

No, it was not and thank you for flagging that. Is it condescending to assume one is not a web developer if they don't know content negotiation? I thought that was Web 101 and pretty much one of the first things you go through when learning about HTTP, but maybe things have changed as of late.

I'm sorry spelunker if my message came off as condescending, I have no real idea of your professional and was only trying to provide a resource to learn more, not to push anyone away.

Re: Best practices for REST API design (2020)

#124

Post by adamscybot »

gengstrand wrote: post #98
fc373745 wrote: post #9

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

I also wanted to understand why GQL was getting so much attention in a REST vs GraphQL way so I implemented a GQL microservice that had the same features as a service that I had implemented previously as REST. Both services ran on node.js and connected to the same data stores, etc. I ran both services on the same load test lab and documented my findings at https://glennengstrand.info/software/architecture/microservi.…

If you're a front end developer the advantages a clear because of much superior tooling. The reason for this the agreed SDL spec format which is part and parcel of GQL. REST is just a loose collection of ideas and OpenAPI is not integral to REST as theres no single over arching spec of organisation for REST.

In my experence therefore, the tooing (code gen, doc gen) etc around OpenAPI is piss poor in comparison to gql. Just look at GraphIQL compared to postman.

Re: Best practices for REST API design (2020)

#125

Post by NicoJuicy »

nojvek wrote: post #44

I’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…

Did you ever check out odata? It seems that's exactly what you want

Re: Best practices for REST API design (2020)

#126

Post by GordonS »

nojvek wrote: post #44

I’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…

OData adds this kind of functionality to REST APIs, in a standardised way. It can do filtering, pagination, sorting etc (your backend data provider of course needs to support these operations).

Re: Best practices for REST API design (2020)

#127

Post by adamscybot »

systemvoltage wrote: post #106
throwoutttt wrote: post #32

Earlier quoted context omitted.

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.

Yes and by doing so you lost the advantages of a predictable and well organised API.

GraphQL has first class support for this scenario.

Re: Best practices for REST API design (2020)

#128

Post by slt2021 »

ngrilly wrote: post #65

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

you can return urls that guarantee proper pagination with your response, if the output is more than the limit. this way you can incorporate your logic (id of the last returned item is a starting point) in pagination and make sure as your API evolves, client applications pagination logic doesn't have to change as long as you provide proper pagination links

for example GET /customer/1/orders/

response:

{'orders': [order1, order2, order3],

'navigation': {

'firstpage': '/get/customer/1/orders/',

'nextpage': '/get/customer/1/orders/?query=orderId^GT4',

'lastpage': '/get/customer/1/orders/?query=orderId^GT990',

'totalrows': 1000

}

GT means greater than

Re: Best practices for REST API design (2020)

#129

Post by adamscybot »

n_e wrote: post #108
fc373745 wrote: post #75

Earlier quoted context omitted.

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.

Yep. OpenAPI spec is not rich enough to represent relations like this so its rubbish for FE dev to use to generate models/api client.

In general, the tooling/spec has thousands of open bugs, isnt going anywhere, moves very slowly and is missing fundamental features.

https://github.com/OAI/OpenAPI-Specification/issues/1998 heres the ticket where it will inevitably be ignored and die. But even if it was supported in the spec, the open source generators wont support it anyways.

Said generators also uses "logic less" templates to generate something that very much needs logic. As a FE dev, I love nothing more than to fork a an archaic Java based generator to get the client gen working...not.

Re: Best practices for REST API design (2020)

#130

Post by HyperRational »

the_arun wrote: post #104
jayd16 wrote: post #63

Earlier quoted context omitted.

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

With Amazon S3 Select, you can use simple structured query language (SQL) statements to filter the contents of Amazon S3 objects and retrieve just the subset of data that you need. By using Amazon S3 Select to filter this data, you can reduce the amount of data that Amazon S3 transfers, which reduces the cost and latency to retrieve this data.

Amazon S3 Select works on objects stored in CSV, JSON, or Apache Parquet format. It also works with objects that are compressed with GZIP or BZIP2 (for CSV and JSON objects only), and server-side encrypted objects. You can specify the format of the results as either CSV or JSON, and you can determine how the records in the result are delimited.

You pass SQL expressions to Amazon S3 in the request. Amazon S3 Select supports a subset of SQL. For more information about the SQL elements that are supported by Amazon S3 Select, see SQL reference for Amazon S3 Select and S3 Glacier Select.

You can perform SQL queries using AWS SDKs, the SELECT Object Content REST API, the AWS Command Line Interface (AWS CLI), or the Amazon S3 console. The Amazon S3 console limits the amount of data returned to 40 MB. To retrieve more data, use the AWS CLI or the API.

https://aws.amazon.com/blogs/aws/s3-glacier-select/

https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-gla...

Post reply on HN