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

91–100 of 149 posts

Re: Microsoft REST API Guidelines

#91

Post by foota »

niftich wrote: post #89
foota wrote: post #87

Earlier quoted context omitted.

That's not what the vulnerability is here. If you have a server endpoint that returns an array without wrapping it as a property on an object then an attacker can write a webpage that overrides the Array prototype and requests the json from your page as a script, thereby bypassing the cross origin check it would be subject to as an xhr request. So if you have a page which returns sensitive information as an array you…

On the contrary, that's precisely the vulnerability: 1. The API server needs authentication, which gets cached in the user-agent. 2. The same user-agent, with the same authentication context, is then directed to a malicious site. 3. The user-agent contains a javascript interpreter, and the malicious website serves a script to override the Array prototype. 4. The same script then executes a CSRF request to the API ser…

Sorry, you are right.

Re: Microsoft REST API Guidelines

#92

Post by JimDabell »

Avernar wrote: post #90
JimDabell wrote: post #39

Earlier quoted context omitted.

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

All those examples are hard coded algorithms in the bulk copy category. They pretty much just use the GET method to download all or a specific subset of a site. To truly drive a REST API requires a human or an AI. The AI doesn't need to be human equivalent, just smart enough to inteligently interpret the hypermedia. If the API changes the AI would be able to adapt. I'm talking about the complexity of the computer on…

I don't know where you got the idea that REST needs futuristic AI, and you haven't really explained why you think that way.

Why does a REST client have to intelligently interpret the hypermedia? Why are hard-coded algorithms a problem? Why does it need to adapt to changes in the API? None of those things are requirements for REST, you've inserted them for seemingly no reason.

For instance, consider an unattended webcam you want to use to show off, e.g. the growth of a flower bed remotely. It has the URI for a web service that returns a resource describing actions it can take:

    {
        "actions": [
            {
                "rel": "report-problem",
                "href": "https://example.com/report-problem",
                "method": "POST",
                "accept": "application/problem+json"
            },
            {
                "rel": "update-frame",
                "href": "https://example.com/update-frame",
                "method": "POST",
                "accept": "image/*"
            }
        ]
    }
The definition of the report-problem relationship is "This is the action to take when an error occurs."

The definition of the update-frame relationship is "This is the action to take when a new frame is available to upload."

This API defines one media type and two relationships. It requires no futuristic artificial intelligence or human intervention, it just needs to speak HTTP, parse simple JSON, and trigger the actions based on simple conditions.

Re: Microsoft REST API Guidelines

#93

Post by danpalmer »

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

> or any way of discovering features of an API programmatically. So, this is one of my issues with HATEOAS. When does this _actually_ come up in practice? I mean really, how do we normally consume APIs? We read the docs to figure out which endpoints we need to call, call them in the right order, and do the right stuff with the result. Nothing about that process is automatic; it takes a human to figure out what's avai…

It means being able to:

- Never write a "client" again, use your "REST" library and then just traverse relationships and call actions, rather like an ORM or having a local object graph. - Letting the API provider optimise your usage, by providing different data at different times, inlining at different times, etc, without any changes to your code.

Re: Microsoft REST API Guidelines

#94

Post by danpalmer »

falcolas wrote: post #67
danpalmer wrote: post #19

Earlier quoted context omitted.

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…

I'm not sure the point about the ORMs is entirely true. I see what you're saying, but the API boundary should be the canonical definition (unlike an ORM where the database might be), and the server and client need to conform to that, so there shouldn't be leakage.

Re: Microsoft REST API Guidelines

#95

Post by niftich »

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

> or any way of discovering features of an API programmatically. So, this is one of my issues with HATEOAS. When does this _actually_ come up in practice? I mean really, how do we normally consume APIs? We read the docs to figure out which endpoints we need to call, call them in the right order, and do the right stuff with the result. Nothing about that process is automatic; it takes a human to figure out what's avai…

Efforts like the Hypertext Application Language (HAL) [1] are attempts to implement HATEOAS.

The point that's often missed in casual discussions of REST is that 'link relations' are extremely important, because they represent well-specified ways of relating one resource to another. They are as critical to REST as mediatypes (MIME types) are.

In the graph theory sense, link relations are the label on an edge, URIs are the nodes, and mediatypes are formats that can be used as concrete representations of the nodes.

The IANA maintains a Link Relations registry [2].

[1] http://stateless.co/hal_specification.html

[2] http://www.iana.org/assignments/link-relations/link-relation...

Re: Microsoft REST API Guidelines

#96

Post by vfaronov »

JimDabell wrote: post #92
Avernar wrote: post #90

Earlier quoted context omitted.

All those examples are hard coded algorithms in the bulk copy category. They pretty much just use the GET method to download all or a specific subset of a site. To truly drive a REST API requires a human or an AI. The AI doesn't need to be human equivalent, just smart enough to inteligently interpret the hypermedia. If the API changes the AI would be able to adapt. I'm talking about the complexity of the computer on…

I don't know where you got the idea that REST needs futuristic AI, and you haven't really explained why you think that way. Why does a REST client have to intelligently interpret the hypermedia? Why are hard-coded algorithms a problem? Why does it need to adapt to changes in the API? None of those things are requirements for REST, you've inserted them for seemingly no reason. For instance, consider an unattended webc…

It also doesn't provide much benefit over a plain RPC-like interface, because, for practical reasons, the webcam will be coded to send requests directly to https://example.com/report-problem and https://example.com/update-frame (the "bookmarks"). If you want to change those URLs, your best hope is that the webcam will understand a 307 or 308 redirect.

Re: Microsoft REST API Guidelines

#97

Post by dragonwriter »

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

> or any way of discovering features of an API programmatically. So, this is one of my issues with HATEOAS. When does this _actually_ come up in practice? I mean really, how do we normally consume APIs? We read the docs to figure out which endpoints we need to call, call them in the right order, and do the right stuff with the result. Nothing about that process is automatic; it takes a human to figure out what's avai…

> So, this is one of my issues with HATEOAS. When does this _actually_ come up in practice?

For the type of systems REST is designed to address, all the time. Its not just random happenstance that REST was articulated in the context of an existing, well-known, widely-used system of that type (the WWW.)

Arguably, many API designers are neither designing the kind of systems REST is intended for nor designing things for which their priority is for them to be well-behaved components in a distributed system that, taken as a whole, is the kind of system REST is intended for. Which is fine, but then there is little reason to use REST and less to use pretend-REST.

Re: Microsoft REST API Guidelines

#98

Post by niftich »

dwightgunning wrote: post #74
ChrisAtWork wrote: post #70

Earlier quoted context omitted.

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

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 friendly error page' upon 4xx/5xx. Since they are graphical applications, they have also been used as rudimentary debug/sanity-check tools at the expense of curl.

Together, these forces combined to drive some APIs to respond with a 200 for any response. Often, faithfulness to spec or faithfulness to the intent of the design takes a backseat to making a solution work. The combination of these traditions survives in the myriad APIs that essentially use HTTP as an browser-accessible RPC mechanism.

Re: Microsoft REST API Guidelines

#99

Post by JimDabell »

vfaronov wrote: post #96
JimDabell wrote: post #92

Earlier quoted context omitted.

I don't know where you got the idea that REST needs futuristic AI, and you haven't really explained why you think that way. Why does a REST client have to intelligently interpret the hypermedia? Why are hard-coded algorithms a problem? Why does it need to adapt to changes in the API? None of those things are requirements for REST, you've inserted them for seemingly no reason. For instance, consider an unattended webc…

It also doesn't provide much benefit over a plain RPC-like interface, because, for practical reasons, the webcam will be coded to send requests directly to https://example.com/report-problem and https://example.com/update-frame (the "bookmarks"). If you want to change those URLs, your best hope is that the webcam will understand a 307 or 308 redirect.

RPC vs REST is an entirely different argument. We're talking about REST best practices here, not "let's do RPC instead".

There's no reason for the webcam to hard-code URIs, and that's a violation of the architectural constraints. Just arbitrarily deciding to disregard facets of the architectural pattern without giving a reason does not add to this discussion.

None of this relates to whether or not you need futuristic AI or human intervention. I think from the example, it's pretty clear you need neither for a REST API.

Re: Microsoft REST API Guidelines

#100

Post by iheart2code »

ChrisAtWork wrote: post #73
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 are pretty easy, assuming you have a rich data store behind your data. As others have said, your data store needs to be able to say, "Show me changes since XYZ". Most of the Big Apps can do that, and from there the problems is one of API Semantics. This doc addresses the API Semantics, rather than the application design. To try to solve the design problem would be impossible as every application is diff…

I understand what the doc is trying to convey, I just hadn't ever thought of the application-level logic for record deltas before, so I got incredibly distracted from the document. It made me wonder how other people, not using temporal tables, are accomplishing this right now.
Post reply on HN