Live data from Hacker News

Microsoft REST API Guidelines

github.com

101–110 of 149 posts

Re: Microsoft REST API Guidelines

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

Any app of decent size will probably end up passing HTTP's error codes. 200 + error is OK, except it can mess with caching. A 5xx with details in the response is fine.

You might be tempted to map some errors, like "item not found" to 404, and so on. But you still need to provide the real error code. So you're not gaining much.

Honestly, I don't get the obsession with using HTTP features to represent part of an API. It never saves work; you're writing a custom client each time anyways. From a purely code perspective, you're going to deserialize the body or a context object from a header. Moving that data into multiple headers can only require more code, not less. Same for verbs. I've never gotten any benefit beyond GET-for-read, POST-for-write.

Elasticsearch is a good example. The URL space is overloaded with special things, allows you to create objects you can't reference, and so on. They use verbs, except you still have extra parameters tacked on. There's zero benefit to me, the user, of them making it REST like.

Maybe if REST-someone creates a machine usable spec like WSDL (just "simpler") then all these HTTP headers could be put to use.

Re: Microsoft REST API Guidelines

#102

Earlier quoted context omitted.

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.

Any app of decent size will probably end up passing HTTP's error codes. 200 + error is OK, except it can mess with caching. A 5xx with details in the response is fine. You might be tempted to map some errors, like "item not found" to 404, and so on. But you still need to provide the real error code. So you're not gaining much. Honestly, I don't get the obsession with using HTTP features to represent part of an API. I…

The advantage is that there is some level of standardization.

404? That means the entity doesn't exist. 302? I should look somewhere else. 401? The server doesn't know who I am.

Accept? I can specify the format. ETag? I can get a faster response if I include the token in the next request.

This stuff is really, really common, and people can learn your API very quickly. A transparent caching server can improve performance.

Sure, with a custom protocol you can get a tight system. Hell, write your own transport layer for even more control. But it will take longer to learn and harder to interoperate.

Re: Microsoft REST API Guidelines

#103

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.

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/result etc, it can be whatever is needed as a response to the client. For paged results, data/nextToken or something similar are perfectly serviceable imho.

To me an error should be top-level in the response object, as well as meta, and the data itself should be a consistent property and nested as such. Other platforms add their own wrappers which include the headers with the response object. ymmv.

Re: Microsoft REST API Guidelines

#104

Earlier quoted context omitted.

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.

Any app of decent size will probably end up passing HTTP's error codes. 200 + error is OK, except it can mess with caching. A 5xx with details in the response is fine. You might be tempted to map some errors, like "item not found" to 404, and so on. But you still need to provide the real error code. So you're not gaining much. Honestly, I don't get the obsession with using HTTP features to represent part of an API. I…

WSDL-like descriptors for REST-like APIs:

[1] Swagger: http://swagger.io/

[2] RAML: http://raml.org/

[3] WADL: https://www.w3.org/Submission/wadl/

Re: Microsoft REST API Guidelines

#105
post #98

Earlier quoted context omitted.

Is that a failure of the people or failure of the spec?

Failure of people and tools. Like the sibling comment says, often tools designed to consume HTTP will throw a more severe class of error upon 4xx/5xx, which then changes the codepath significantly, making it more difficult for the programmer to treat 2xx and 4xx/5xx responses similarly for parsing out the headers and the response body. Web browsers are also guilty of some of these behaviors. They would inject a 'user…

Which is irritating as all hell at times... the .Net http client does this, which makes snagging the actual response text and code difficult... Same wrt .Net for response codes, there's a lot of errors that can happen with the JSON deserializer for services, but it returns a 500 series error not a 400 series. I usually wrap the on error in the app file, and replace those responses for .Net projects.

Worth noting, not sure if this is improved/fixed in .Net Core based services.

As I mentioned in another thread, I'm in favor of the response always being an object at the top level, with a data property for any response data, and an error property for any errors, errors having a "message" property that is the error message string, and a "code" property that matches the numeric http response code.

This also helps if your error classes have these codes in them, that way the http response code can be set based on the error, defaulting to 500.

Re: Microsoft REST API Guidelines

#106
post #81
post #53

Earlier quoted context omitted.

This isn't just some poorly labelled content from a 10 year old legacy website from a time before they knew any better, the OData website got a recent redesign sporting new Stock photos and even larger font for their disingenuous labeling which still continue to push OData crapware under the REST banner to fool devs/CIO's into thinking if they adopt OData they're taking advantage of the best form of REST - which is i…

I recently had the misfortune to have to tackle oData to talk to Dynamics CRM. The choice was between that and SOAP so it was the lesser of two evils. But compared to the other nice, modern REST API's I'm used it smelt of mould and enterprisey cobwebs. I'd have preferred an old school RPC API over that. At least API's that abuse REST from that direction tend to have the virtue of simplicity.

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.

Re: Microsoft REST API Guidelines

#107

Earlier quoted context omitted.

Any app of decent size will probably end up passing HTTP's error codes. 200 + error is OK, except it can mess with caching. A 5xx with details in the response is fine. You might be tempted to map some errors, like "item not found" to 404, and so on. But you still need to provide the real error code. So you're not gaining much. Honestly, I don't get the obsession with using HTTP features to represent part of an API. I…

The advantage is that there is some level of standardization. 404? That means the entity doesn't exist. 302? I should look somewhere else. 401? The server doesn't know who I am. Accept? I can specify the format. ETag? I can get a faster response if I include the token in the next request. This stuff is really, really common, and people can learn your API very quickly. A transparent caching server can improve performa…

The time spent reading that 404 in this case means "the object ID isn't found" versus "this path doesn't exist" pretty much negates any benefit - you still have to include sub codes. Same for "access denied because token expired" vs "invalid token". Not mention all the stuff that'll get crammed into 400/500/503.

If your app is simple enough that all errors map 1:1 to HTTP, great. Or if it doesn't need that level of error management. Otherwise HTTP just confuses the issue.

Re: Microsoft REST API Guidelines

#109
post #10

Earlier quoted context omitted.

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…

No clients know that "comments" means Comments, because no one has standardised it yet. There's no reason that we can't define "rel=comments" as being the comments for something, in the same way that https://schema.org/ has defined schemas for a range of taxonomies on the web already. I don't have an example of a public API that can be used by a generic client because no one is making them. I've played around with th…

So all this push to "do it right" and HTATEOAS, is not actually meant to provide immediate benefit? It is only meant to help enable benefit in the future, when everyone is on board, and the usage of "rel" in json responses is agreed upon?

Re: Microsoft REST API Guidelines

#110

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 request for taco 8 WAS found... it's a taco processor that looked for taco 8 for you. everything worked 200 successfully. the response is meta content about an error message.
Post reply on HN