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

Microsoft REST API Guidelines

github.com

Post reply on HN
Print view View original

31–40 of 149 posts

Re: Microsoft REST API Guidelines

#31

Post by vfaronov »

jcrites wrote: post #25
SwellJoe wrote: post #11

Earlier quoted context omitted.

REST seems like an elephant in a room with some blind folks. Everybody who touches it thinks it's something different than the next guy, and they're all describing only one element of the thing. That said, I don't actually know what this elephant looks like, either, because everybody I've read on the subject seems to have only a partial understanding of it...thus, I have a partial understanding of it. If you know wha…

The best way to understand REST is by example. First check out the blog post by Roy Fielding mentioned in this thread which summarizes the constraints [1]. Then let's examine how several popular restful services work versus those constraints. Here are some popular well-known services to use as examples: Google.com Amazon.com Facebook.com News.ycombinator.com. - You enter these services through the site root with no p…

The big problem with using the hypertext Web as an example of REST is that there is a human operator literally driving that "engine of application state". Most API clients cannot afford to compute their state transitions on a network of 80 billion neurons.

Re: Microsoft REST API Guidelines

#32

Post by beckler »

mikro2nd wrote: post #28

Funny thing: I've been thinking a bit about API versioning quite a bit lately, and the best solution I've come up with is the ONE thing not at all covered in this: put an `api-version` header into the request. I've seen both of the schemes recommended here, and I like neither very much. So what's wrong with my (header) solution?

Troy Hunt has an article where he shows three different ways to declare a version, including the header method.

https://www.troyhunt.com/your-api-versioning-is-wrong-which-...

Re: Microsoft REST API Guidelines

#33

Post by daliwali »

danpalmer wrote: post #2

Being that guy again, (and sacrificing my karma) but... This is not REST, it contains nothing about hypermedia, entities having knowledge of their URIs, or any way of discovering features of an API programmatically. While I'm sure there's plenty of good stuff in here (it looks otherwise fairly comprehensive), APIs will continue to be a disparate system that requires custom code for every integration until we can embr…

I don't know why everyone wants to downvote this comment. It's absolutely right.

I would add that REST has nothing to do with pretty URIs, JSON formatting, versioning, query strings, and more misconceptions that people seem to mistake for the architectural style. There is nothing that isn't RESTful with URIs like "/a89f30e9" instead of "/:type/:id". Even TBL thinks URIs should be opaque: https://www.w3.org/DesignIssues/Axioms.html#opaque

Re: Microsoft REST API Guidelines

#34

Post by balls187 »

yeukhon wrote: post #4

https://evertpot.com/dropbox-post-api/ This discuss some option for the GET vs POST. In Kibana, everything is done over GET as get parameters, and I find that extremely annoying and a poor design. A lot of public APIs also don't honor or have any intentions in supporting or using PATCH. Most APIs I have worked with only use PUT for modification. Anything resembles "creation" is automatically a POST.

An advantage of GET for all APIs is simplifying access to the API via a web browser.

Re: Microsoft REST API Guidelines

#35

Post by JimDabell »

mikro2nd wrote: post #28

Funny thing: I've been thinking a bit about API versioning quite a bit lately, and the best solution I've come up with is the ONE thing not at all covered in this: put an `api-version` header into the request. I've seen both of the schemes recommended here, and I like neither very much. So what's wrong with my (header) solution?

Neither of the schemes mentioned here are good as they change the URI for a resource, which breaks all sorts of things. Could you imagine if every website wanting to switch from HTML 4 to HTML 5 had to update their URIs from https://www.example.com/HTMLv4/contact.html to https://www.example.com/HTMLv5/contact.html? It would be chaos.

For instance, if client application A talks to the service using version 1.0 of the API and client application B talks to the service using version 2.0 of the API, then those client applications can't interoperate because they are seeing two different sets of resources.

Your solution isn't far off the approach recommended by everybody who rejects the different URI approach. You don't need an API version header. When your representation format for a resource changes, provide a `version` parameter for the media type. For example: `Content-Type: application/vnd.example.foo+json;version=2`.

This is exactly how HTTP and the `Content-Type` header are supposed to work – if your representation for a resource changes, you don't change the URI, you change the media type.

Re: Microsoft REST API Guidelines

#36

Post by Marazan »

vfaronov wrote: post #31
jcrites wrote: post #25

Earlier quoted context omitted.

The best way to understand REST is by example. First check out the blog post by Roy Fielding mentioned in this thread which summarizes the constraints [1]. Then let's examine how several popular restful services work versus those constraints. Here are some popular well-known services to use as examples: Google.com Amazon.com Facebook.com News.ycombinator.com. - You enter these services through the site root with no p…

The big problem with using the hypertext Web as an example of REST is that there is a human operator literally driving that "engine of application state". Most API clients cannot afford to compute their state transitions on a network of 80 billion neurons.

REST is a human driven protocol. That's why resources have a link to a description of what the resource is.

Re: Microsoft REST API Guidelines

#37

Post by brandonbloom »

deathanatos wrote: post #26

Pagination is one of those things I feel like so many of these things get wrong. LIMIT/OFFSET (or as MS likes to call it, TOP/SEEK) style results in O(n²) operations; an automated tool trying to pull the entirety of a large collection in such a scenario is not good. I have to again recommend the excellent "Pagination done the Right Way" presentation[1] from Use the Index, Luke (an equally excellent site). Just return…

Big +1 to killing offset in favor of order-by and an "after" or "before" criteria.

However, -1 to the idea of sticking any important "metadata" in headers. For one, it's dramatically easier to interact with response bodies than headers at the terminal or with simple programming libraries and tools. Having only one way of representing data requires fewer special cases. JSON is far superior to key/value pairs in terms of ability to represent structure. Lastly, if you ever decide to use a different "transport" protocol other than HTTP, you'll be glad you are already using a common representation without a side channel.

Re: Microsoft REST API Guidelines

#38

Post by gedy »

danpalmer wrote: post #2

Being that guy again, (and sacrificing my karma) but... This is not REST, it contains nothing about hypermedia, entities having knowledge of their URIs, or any way of discovering features of an API programmatically. While I'm sure there's plenty of good stuff in here (it looks otherwise fairly comprehensive), APIs will continue to be a disparate system that requires custom code for every integration until we can embr…

To be frank, main issue is people are arguing about semantics, one side thinks Fielding's definition is the only thing that can be called REST, and the other larger(?) side could care less about that academic definition and are describing some simple rules for HTTP APIs. While it would be nice if there were two terms, just saying "This is NOT REST" really doesn't clarify anything.

Re: Microsoft REST API Guidelines

#39

Post by JimDabell »

vfaronov wrote: post #31
jcrites wrote: post #25

Earlier quoted context omitted.

The best way to understand REST is by example. First check out the blog post by Roy Fielding mentioned in this thread which summarizes the constraints [1]. Then let's examine how several popular restful services work versus those constraints. Here are some popular well-known services to use as examples: Google.com Amazon.com Facebook.com News.ycombinator.com. - You enter these services through the site root with no p…

The big problem with using the hypertext Web as an example of REST is that there is a human operator literally driving that "engine of application state". Most API clients cannot afford to compute their state transitions on a network of 80 billion neurons.

No there isn't, a great deal of the web is loaded without direct human requests. For example:

* Web crawlers

* Archival services

* Embedded resources (stylesheets, JavaScript, images)

* Newsfeeds

Re: Microsoft REST API Guidelines

#40

Post by dsp1234 »

iheart2code wrote: post #29

Very cool document. I kind of got stuck at delta queries, though. How do you implement that? I can't find any reference to delta/removed queries on Mongo, Postgres, or MySQL. Do you just keep all records in the database and add a "removed" field? How would that solution work with user privacy & users truly wanting to remove data?

Delta queries can be serviced by any system that supports temporal tables[0][1], or another mechanism where data changes are tracked.

[0] - https://en.wikipedia.org/wiki/SQL:2011 (temporal support)

[1] - https://msdn.microsoft.com/en-us/library/dn935015.aspx

[2] - http://clarkdave.net/2015/02/historical-records-with-postgre...

Post reply on HN