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.
Microsoft REST API Guidelines
21–30 of 149 posts
Re: Microsoft REST API Guidelines
#22Earlier quoted context omitted.
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…
I suggest you go to the original source, ie, Roy Fielding: https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arc... http://roy.gbiv.com/untangled/tag/rest https://www.infoq.com/articles/roy-fielding-on-versioning
I was going to post the same. I was lucky enough to get a few answers from Fielding himself when I first started learning this.
Re: Microsoft REST API Guidelines
#23Earlier 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…
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 them in a few projects and there are rough edges, but no reason we can't move forward to them. Google already use 'real' REST for some of their mobile apps as far as I can remember.
Re: Microsoft REST API Guidelines
#24Earlier 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…
This is pretty much the crux of the problem that the Semantic Web / Linked Data folks have been working on for years. They have the technology to do it (RDF). This technology is not widely used for a number of reasons, but "because it can never exist (and I'll write that in boldface for extra credibility)" is not one of them.
People have been able to agree on many common vocabularies of stuff, like "" and "" and "rel=pingback", and have it work more or less. It is not absurd to suggest that such an agreement can be achieved -- to some extent -- in APIs.
Re: Microsoft REST API Guidelines
#25Being 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…
The best way to understand REST is by example. First check out the blog post by Roy Fielding mentioned in this thread which summarizes the constraints [1]. Then let's examine how several popular restful services work versus those constraints.
Here are some popular well-known services to use as examples: Google.com Amazon.com Facebook.com News.ycombinator.com.
- You enter these services through the site root with no prior knowledge about the services aside from standard media types (HTML/CSS/JS)
- Hypermedia is the engine of application state – meaning that you load a webpage a.k.a. resource that contains hypermedia links to other resources, and you navigate between states in the application by following those hypermedia links. For example, the hacker news homepage contains links to news articles and comment threads about them, which contains links to reply to those comments, and so on.
- The application describes how to compose requests using standard media types such as web forms and JavaScript. Because the pages instruct the client about what requests to compose and to which URL, the services have control over their own name spaces which have no fixed resource names or hierarchy.
I consider REST to be most easily understood as a departure to application protocol design prior to the Web, where each application and service had a unique and custom binary protocol, and a client for these services had to be reprogrammed to interact with it. REST is a set of constraints for designing services that run at Internet scale and that highly decouples clients and servers. Fielding's thesis on REST has more detail on the principles by which the REST architectural style was derived.
[1] http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte...
Re: Microsoft REST API Guidelines
#26Pagination 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 a link to the "next page" (make the next page opaque); while this removes the ability to of the client to go to an arbitrary page on its own, in practice, I've never seen that matter, and the generalized URL format allows you to seek instead of by LIMIT/OFFSET by something indexable by the DB; HTTP even includes a standardized header for just this purpose[2].
I also think the generalized URL is more in line with Fielding's definition of REST, in that the response links to another resource. (I don't know if being in the header invalidates this; to me, it does not.)
If you get the metadata out of the data section of your response, and move it to the headers, where it belongs, this usually then lets you keep the "collection" of items you are return as an array (because if you need to put metadata along side it, you need:
{
"the_data_you_really_want": [1, 2, 3],
"metadata, e.g., pagination": {}
}
["the", "data", "you", "wanted", "in a sensible format"]
(I've seen metadata-pushed-into-the-body turn API endpoints that literally need to return no more than "true" or "false" into object that then force a client to know and look up the correct key in an object… sigh.)
Re: Microsoft REST API Guidelines
#27Wow, they REALLY LIKE TO SHOUT THEIR HEADINGS.
Otherwise, what I've read so far looks like a really good start. Say what one will about Microsoft's products, but there are a lot of smart folks there.
Re: Microsoft REST API Guidelines
#28Funny 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?
Re: Microsoft REST API Guidelines
#29Very 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?
Re: Microsoft REST API Guidelines
#30Earlier 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…
> There is no magical "smart client" that somehow knows that rel=comments means that the link leads to comments about the current resource and can figure out it should POST there to create a new comment. It has no idea what the hell a "comment" is.
Yes there is: that client is a human being. The point of REST and HATEOAS is to write something that works properly for humans, and to which general software can specifically be adapted.
That's part of why I loathe single page apps and JavaScript so much: HTTP & HTML already offer an incredible expressive range, and JavaScript just tramples over the forms and scaffolding they create.