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

61–70 of 149 posts

Re: Microsoft REST API Guidelines

#61

Post by ferentchak »

brandonbloom wrote: post #37
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…

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.

Re: Microsoft REST API Guidelines

#62

Post by PallarelCoedr »

tarequeh wrote: post #55
daxfohl wrote: post #21

Well presented. It would be great if there was a language / framework that made this guaranteed. As-is everything just returns 500 error on any exception, lets you return errors with 200, allows update on GET, etc. Even the Haskell ones.

Handling errors over REST API is something I've struggled with. What's the best way to handle errors? Data validation errors will be different from system/server errors. Tough to establish a universally applicable error response structure. I used to be in favor of sending 200 responses with error codes but now gravitating back towards relaying the most relevant HTTP error & letting the clients handle it.

Perhaps look at HTTP Problem Details? https://tools.ietf.org/html/rfc7807

Re: Microsoft REST API Guidelines

#63

Post by niftich »

blakeyrat wrote: post #60
gedy wrote: post #51

Earlier quoted context omitted.

POST /users/{id}/avatar ? What additional guidance would you expect?

Well, for one thing, it's a huge PITA to have 99 controllers that all take JSON and one oddball that has to take forms-urlencoded because you can attach a file. This is out of the scope of this document, but I'd also like to see some guidance on how to implement the controller for that oddball using Microsoft's own WebAPI2 library. I ended up having to go entirely outside the library and implement it as a generic .as…

You're thinking of 'multipart/form-data' with a content-disposition of 'attachment', which is the usual way of uploading binary blobs to a controller resource.

But conceivably you could have controllers that accept a PUT or a POST of an 'image/jpeg'. Why wouldn't you, if you're aiming for image uploads?

Re: Microsoft REST API Guidelines

#64

Post by seanp2k2 »

ferentchak wrote: post #61
brandonbloom wrote: post #37

Earlier quoted context omitted.

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…

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.

The actual HTTP status should be relevant. I don't want to get HTTP/200 with {error: not found}. Instead, useful errors should be like:

HTTP/400 {error: invalid foobar in request. Foobar should be a string, but instead got '123'}

Or something like that. Tell developers what the problem actually was, and potentially how to fix it. http://jsonapi.org/format/#error-objects has some good ideas and suggests a standard.

That said, even discarding the body, you should be able to determine if a request was successful by the HTTP status code alone, IMO. If you made a new thing, 201, thing ain't there, 404, your request sucks, 400, etc. Don't make people using your API parse your [especially true if you've invented your own format] JSON errors if they don't want to.

Re: Microsoft REST API Guidelines

#65

Post by yeukhon »

dozzie wrote: post #44
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.

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

We ran into a situation exactly like that. We hit the limit of the length of GET.

Thanks.

Re: Microsoft REST API Guidelines

#66

Post by blakeyrat »

niftich wrote: post #63
blakeyrat wrote: post #60

Earlier quoted context omitted.

Well, for one thing, it's a huge PITA to have 99 controllers that all take JSON and one oddball that has to take forms-urlencoded because you can attach a file. This is out of the scope of this document, but I'd also like to see some guidance on how to implement the controller for that oddball using Microsoft's own WebAPI2 library. I ended up having to go entirely outside the library and implement it as a generic .as…

You're thinking of 'multipart/form-data' with a content-disposition of 'attachment', which is the usual way of uploading binary blobs to a controller resource. But conceivably you could have controllers that accept a PUT or a POST of an 'image/jpeg'. Why wouldn't you, if you're aiming for image uploads?

You're right, I had the wrong MIME type. It's been ages since I was working with this stuff.

To answer your second question: because I simplified the example. We run a health insurance website and we need to support life changes events either with or without supporting documentation. It makes no sense to have two separate controllers, as that would mean you could have a successful file attached to an errored-out life change, or the reverse.

But look, never mind. I was just asking because our solution to this problem I imagine most REST APIs would eventually come across felt really hacky and awful and I'm really not proud of the code I wrote to support it, but maybe we're the weirdo freaks and nobody else has to do anything more complicated than assign a file to a user ID.

Re: Microsoft REST API Guidelines

#67

Post by falcolas »

danpalmer wrote: post #19
varenc wrote: post #7

Earlier quoted context omitted.

I'm fine with APIs continuing to be disparate systems if they have a simple, sensible design and have comprehensive documentation. Let's just stop calling them "REST" since they're not as you've pointed out.

Why not push for them to become something more? Documentation for humans is good, but you know what's better? Documentation for computers so that we don't have to build integrations anymore!

I would love to see how this could be realistically done. I recall this being attempted with WSDLs, but there was still a ton of man hours required to integrate with an endpoint.

There is still always an impedance mismatch between the server representation and what the client representation that needs to be fixed.

Like ORMs, such integration automation will always be, at best, a leaky abstraction that makes the easy bits easier, and the hard bits harder.

Re: Microsoft REST API Guidelines

#68

Post by beachy »

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

And send emails.

Re: Microsoft REST API Guidelines

#69

Post by ChrisAtWork »

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?

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.

Re: Microsoft REST API Guidelines

#70

Post by ChrisAtWork »

seanp2k2 wrote: post #64
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.

The actual HTTP status should be relevant. I don't want to get HTTP/200 with {error: not found}. Instead, useful errors should be like: HTTP/400 {error: invalid foobar in request. Foobar should be a string, but instead got '123'} Or something like that. Tell developers what the problem actually was, and potentially how to fix it. http://jsonapi.org/format/#error-objects has some good ideas and suggests a standard. Th…

"Success With Info" is something that just causes problems.

The number of examples we found of "Success with Info" going horribly wrong was abundant. Turns out checking return codes is something people have failed to do pretty much since the invention of the return code...

Post reply on HN