Live data from Hacker News

Microsoft REST API Guidelines

github.com

41–50 of 149 posts

Re: Microsoft REST API Guidelines

#41
I'd love to see some guidance on how you're supposed to do file uploads (think: uploading an image avatar for a user) and fit it into the REST structure. These guidelines don't even mention "x-www-form-urlencoded" except in a bit of fluff about CORS.

Made more frustrating by Microsoft's own WebAPI2 basically having zero support for file uploads, meaning we had to go way outside the library to code support for it.

Not sure why that's such a blind spot. Doesn't every web service need to upload files eventually?

Re: Microsoft REST API Guidelines

#42

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…

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…

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

I don't see it that way at all. Sure, there are minor quibbles about various approaches, but you can easily place everybody into one of two camps: the ones who don't know/care about REST's technical definition, and the ones that do. The two groups largely agree about what REST is amongst members of their own group, but disagree with the other group.

Re: Microsoft REST API Guidelines

#43
post #36

Earlier quoted context omitted.

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.

Are you suggesting that Fielding did not intend REST to be used in automated systems?

By "distributed hypermedia systems", did he really mean "alternative browsers for alternative WWWs"?

Re: Microsoft REST API Guidelines

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

> In Kibana, everything is done over GET as get parameters, and I find that extremely annoying and a poor design.

Kibana (4.x) being a website to display queries and some charts and weighing over hundred megabytes is itself a clear example of a poor design.

Re: Microsoft REST API Guidelines

#45
post #13

Funny that Microsoft uses OData as an example of a bad URL: https://github.com/Microsoft/api-guidelines/blob/master/Guid... Whilst continuing to praise OData as "the best way to REST" - http://www.odata.org

Microsoft came up with OData about 10 years ago, but it's now steered by a technical committee with a lot of participants. I wouldn't necessarily be so quick to assume that the OASIS committee - or Microsoft's representatives on it - speak for all of Microsoft. Let alone an internal guidelines committee that they apparently convened fairly recently (given the age of the report) when they use that slogan.

Re: Microsoft REST API Guidelines

#46

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…

Interestingly enough, putting it in Content-Type is also invalid unless the mime type allows it. (Which, of course, is trivial if you're defining your own.)

Specifically, RFC 2616 specifies that clients SHOULD only specify parameters which are valid for the mime type [0]. This can get more restrictive; for instance, JSON-API (application/vnd.api+json) states that any parameters MUST result in 415 UNSUPPORTED MEDIA TYPE [1].

[0] https://www.w3.org/Protocols/rfc2616/rfc2616-sec3.html#sec3....

[1] http://jsonapi.org/format/

Re: Microsoft REST API Guidelines

#47

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…

From the parent Microsoft guideline [1], they make the explicit differentiation between Server-driven and Client-driven paging, the Server-driven seems to be exactly what you describe in your first paragraph:

> Paginated responses MUST indicate a partial result by including a continuation token in the response. The absence of a continuation token means that no additional pages are available.

> Clients MUST treat the continuation URL as opaque, which means that query options may not be changed while iterating over a set of partial results.

> Example:

  {
    ...,
    "value": [...],
    "@nextLink": "{opaqueUrl}"
  }

They then explain Client-driven paging, if the client really wants to do it:

> Clients MAY use $top and $skip query parameters to specify a number of results to return and an offset. The server SHOULD honor the values specified by the client; however, clients MUST be prepared to handle responses that contain a different page size or contain a continuation token.

But if you want to obtain the entire collection, you would not use Client-driven paging, but only rely on Server-driven paging

[1] https://github.com/Microsoft/api-guidelines/blob/master/Guid...

Re: Microsoft REST API Guidelines

#48
post #10
post #3

Earlier quoted context omitted.

Any shining examples you'd care to share?

Agreed, and specifically: > APIs will continue to be a disparate system that requires custom code for every integration until we can embrace the full benefits of REST Have an example of a client that DOESN'T require custom code to use an API? I think this entire debate is summed up best by: > There is no magical "smart client" that somehow knows that rel=comments means that the link leads to comments about the curren…

> Have an example of a client that DOESN'T require custom code to use an API?

Your web browser.

Right here. It's talking with HN's API for me to let me post this comment.

Whenever you have an URL that responds to the browser's requests to let the user do something, that's an API. Maybe a shitty, ad-hoc, poorly designed one, but it's an API. You can even write custom code against if if you want to.

Re: Microsoft REST API Guidelines

#49

Earlier quoted context omitted.

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

[deleted]

Re: Microsoft REST API Guidelines

#50

Earlier quoted context omitted.

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

True, and some of these use cases are very interesting.

jcrites does not mention them, though. I realize now that his comment does not preclude them, either, but still this example would be more convincing if automated clients were emphasized, because that is what most people are actually building and care about.

Post reply on HN