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

141–149 of 149 posts

Re: Microsoft REST API Guidelines

#141

Post by deathanatos »

draw_down wrote: post #88
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…

> while this removes the ability to of the client to go to an arbitrary page on its own Yeah, that's the whole problem with this approach.

Sometimes, you can look at what the index is and find a better thing than page numbers to use; for example, if your collection is ordered/indexed on a timestamp, you can navigate to dates&times instead of page numbers. (e.g., in a UI presentation you might expose the ability to choose a date to go to, instead of a page)

Re: Microsoft REST API Guidelines

#142

Post by Marazan »

vfaronov wrote: post #43
Marazan wrote: post #36

Earlier quoted context omitted.

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"?

Yes, they can be used by automated system but the automated system was developed by humans who explored the RESTful service.

Re: Microsoft REST API Guidelines

#143

Post by ChrisAtWork »

JimDabell wrote: post #78
ChrisAtWork wrote: post #69

Earlier quoted context omitted.

The API version header has a few problems. 1. Older proxies used to remove/strip headers they don't understand. 2. Frameworks and libraries don't always give access to n non-standard headers, meaning they just can't used. 3. It's harder for humans to look at a request and see what's going on.

Proxies stripping headers isn't a problem if you use HTTPS or HTTP 2. Additionally, the proper place for this is the Content-Type header, which is a standard header any proxy would understand. I can't say I've come across a framework or a library that makes it impossible to access a non-standard header, and if there are any, that would be a pretty glaring bug. Nevertheless, the proper place for this information is in…

Why do you think HTTPS would fix this?

For the TLS case, there are enough MITM proxies, both in the Enterprise and elsewhere, to make this a real concern. There are also API Aggrigators which are effectively MITM and need to be taught to "play-well" with custom headers.

Certainly in the consumer case HTTPS would keep a majority of consumer facing ISPs from header-stripping, but there is still a pretty big hole.

Re: Microsoft REST API Guidelines

#144

Post by tracker1 »

ChrisAtWork wrote: post #121
tracker1 wrote: post #106

Earlier quoted context omitted.

For that matter, I know it's "bad" to use RPC, but imho it's sometimes the cleanest/simplest interface you can make for something on an API.

There's nothing wrong with RPC APIs. Other than being "Not Cool" due to the legacy of SOAP, they can deliver some very nice value. Various RPC mechanisms like Bond and Protocol Buffers (and more recently GRPC) are trying hard to make RPC cool again. Personally, I hope they succeed, as REST (like any technology) doesn't work for everything.

For that matter, communication abstractions over websockets... Which has been most interesting to me in terms of offering some better security choices.

Re: Microsoft REST API Guidelines

#146

Post by dehora »

It's great to see Microsoft release these guidelines. It's good work, a broad document with a lot of interesting topics covered. You can always debate the details (the pagination discussion here is very interesting), but having seen first hand at Zalando how much dedication and effort goes into API guidelines to support a large number of service teams, plus releasing them into the public, it's no small feat and they deserve credit for doing this.

There's naturally been some discussion around REST/HTTP APIs and design styles. One of the things we've tried to do with the Zalando guidelines (https://zalando.github.io/restful-api-guidelines) is go into more detail on using HTTP and JSON, and how REST properties are used. Zalando, like everyone else, has had to think through versioning and compatibility, so it was interesting to read what Microsoft do here. The Zalando guidelines take a different approach, using media types for versioning, document just one set of compatibility rules, plus a deprecation model, and it's working very well in practice so far (http://zalando.github.io/restful-api-guidelines/compatibilit...).

Btw, in case anyone from Microsoft working on the guidelines is reading and ever wanted to swap guideline notes or ideas, that would be awesome. And once again, great job releasing the doc :)

Re: Microsoft REST API Guidelines

#147

Post by tracker1 »

tracker1 wrote: post #103
ferentchak wrote: post #61

Earlier quoted context omitted.

How do you feel about using StatusCodes to return api information. /tacos/8 ... not found 404 vs { "meta":{ "errors":["not found"] } } or something like that without getting into the form of the JSON returned.

I tend to prefer a simple JSON object that wraps any response... { data: any, error: object } So that only the presence of an error needs to be checked... within the error should always be a friendly message property and optionally a numeric code, that mirrors the response code (404), etc. { error: { code:404, message: 'Not found' } } This tends to work well with error traps in server-side workflows... As to the data…

in C# terms...

    //use CamelCasePropertyNamesContractResolver

    public class ApiResponse {
      public T Data { get; set; }
      public Exception Error { get; set; }

      public ApiResponse(T data) {
        this.Data = data;
      }
   
      public ApiResponse(Exception error) {
        this.Error = error;
      }
    }
In this way, all API requests return ApiResponse

Re: Microsoft REST API Guidelines

#149

Post by fooyc »

aligajani wrote: post #148

Roy Fielding thinks this isn't REST. He says REST APIs != HTTP APIs. So, read with caution. Also, I noticed the MSFT guide doesn't mention HATEOS.

HATEOS is one of the steps too far that contributed in making REST suck more for everyone.

People following this also tend to follow it like a dogme, and find that their APIs are slow, too meta/abstract, and hard to consume.

Post reply on HN