14 ms·

Microsoft REST API Guidelines

339 points by alpb 10y ago

danpalmer 10y ago
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 embrace the full benefits of REST, and develop the technology and conventions/standards for integrating RESTful services. Edit: for an example of what's possible with 'real' REST, check out this talk: https://vimeo.com/20781278 https://vimeo.com/20781278 – better documentation, easy parsing, API optimisation without client changes, discovery, and the API is fully human readable/usable as well.
- pstuart 10y ago
  Any shining examples you'd care to share?
  - petersellers 10y ago
    The JSON API spec is pretty good: http://jsonapi.org/ http://jsonapi.org/
  - yeukhon 10y ago
    Search for "rest api standard" you will find a bunch. While I like standard, and I am always an advocate of standard, I also don't agree with standard body's decision on the exact format. This is the challenge. HATEOS is an absolutely great idea, but also painful to implement, making payload larger. One question I ask is "how many kinds of resource links do I need to supply?"
  - gregmac 10y ago
    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 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. [1] [1] https://jeffknupp.com/blog/2014/06/03/why-i-hate-hateoas/ https://jeffknupp.com/blog/2014/06/03/why-i-hate-hateoas/
    - icebraining 10y ago
      The thing is, those servers and clients already exist, people are just to tied to their notion of "API" to see them. And in fact, you used them to post that very comment. A website is a RESTful service which a generic client can interact with despite not having any custom code. Does it do so by magically understanding what an <a> or <img> tags are or by magically decoding PNG bytestreams? No, the service uses standard formats that the browser knows and which encode these semantics, allowing it to process them despite its original developers quite possibly not even knowing that service existed.
      - gregmac 10y ago
        > No, the service uses standard formats that the browser knows and which encode these semantics, allowing it to process them despite its original developers quite possibly not even knowing that service existed. You're correct. But that's not what we're talking about. We're talking about a web browser that can understand its posting a Comment, not a form (or a random collection of key-value pairs). The primitives that make the web work are quite different from the high-level concepts that make an application work. My browser understands how to display links and forms and text and graphics. It does not understand how to display a comment or a user account or the number of votes a comment has, let alone know when I'm allowed to vote up or down, understand the relationship between a user account and a comment, understand a comment being owned by my user account or another, etc, etc. What exactly is the end goal? That a HATEOAS-style REST API can be created, you can go to some entry point with your browser, and with no one writing any UI code it just understands how to render the Hacker News site? It will magically understand that the main page contains a list of articles, those articles have comments, links to an original source, etc? This is my understanding of the goal of HATEOAS. If that's not the goal, I don't understand what it gets besides being a way to build a tiny part of documentation necessary to consume an API.
    - danpalmer 10y ago
      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/ 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.
- ihsw 10y ago
  There are degrees of completeness and this expands on the REST standard by a whole lot more. Frankly I would prefer adhering to this standard.
- varenc 10y ago
  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.
  - danpalmer 10y ago
    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!
    - falcolas 10y ago
      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.
      - danpalmer 10y ago
        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.
- rimantas 10y ago
  Not sure about your karma sacrifice, but if someone has doubts: > What needs to be done to make the REST architectural style clear on the > notion that hypertext is a constraint? In other words, if the engine of > application state (and hence the API) is not being driven by hypertext, > then it cannot be RESTful and cannot be a REST API. Period. Is there > some broken manual somewhere that needs to be fixed? That's by Roy T. Fielding himself (http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte...) So if it is not HATEOAS it is not REST. Alas, I am not aware about any term which can be used for these Richardson maturity model Level 2 services.
  - danpalmer 10y ago
    Thank you for that quote, I shall save it for future use. Also lots of replies and 0 points. That's what I'm talking about, this always gets downvoted.
  - d0mine 10y ago
    It reminds me that GIF is pronounced GIF by most people even if the inventor pronounces it as JIF. The language is what people use to communicate. REST may mean whatever most people think it means regardless what the inventor of the term thinks it should mean. Another example is the word hacker. For most people it is "a person who uses computers to gain unauthorized access to data" (according to Google) that is different from the meaning used on this site: "one who works like a hack at writing and experimenting with software, one who enjoys computer programming for its own sake" http://www.etymonline.com/index.php?term=hacker http://www.etymonline.com/index.php?term=hacker
- SwellJoe 10y ago
  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 what the whole elephant looks like, and have good resources for what makes something actually REST, I'd be interested.
  - icebraining 10y ago
    I suggest you go to the original source, ie, Roy Fielding: https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arc... http://roy.gbiv.com/untangled/tag/rest http://roy.gbiv.com/untangled/tag/rest https://www.infoq.com/articles/roy-fielding-on-versioning https://www.infoq.com/articles/roy-fielding-on-versioning
    - toomanythings4 10y ago
      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.
  - danpalmer 10y ago
    This is the video that made it finally "click" for me. https://vimeo.com/20781278 https://vimeo.com/20781278 We don't yet have the abstractions, libraries, conventions or standards for this to work fully yet, but we're close.
  - ianai 10y ago
    I think the above commentor got it right. You map the CRUD actions to HTTP verbs and statuses, as many of them make sense for your API, with links to further resources along the way.
  - jcrites 10y ago
    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-hypertext-driven http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte...
- daliwali 10y ago
  I don't know why everyone wants to downvote this comment. It's absolutely right. I would add that REST has nothing to do with pretty URIs, JSON formatting, versioning, query strings, and more misconceptions that people seem to mistake for the architectural style. There is nothing that isn't RESTful with URIs like "/a89f30e9" instead of "/:type/:id". Even TBL thinks URIs should be opaque: https://www.w3.org/DesignIssues/Axioms.html#opaque https://www.w3.org/DesignIssues/Axioms.html#opaque
- gedy 10y ago
  To be frank, main issue is people are arguing about semantics, one side thinks Fielding's definition is the only thing that can be called REST, and the other larger(?) side could care less about that academic definition and are describing some simple rules for HTTP APIs. While it would be nice if there were two terms, just saying "This is NOT REST" really doesn't clarify anything.
- xienze 10y ago
  > 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 available and the right way to use it. To me the hypermedia part of REST has always seemed like a pointless academic exercise. Yes it's really cool to be able to point a service browser at your service's root resource and have it map the whole thing out but in practice, when is this ever anything but a neat party trick?
  - danpalmer 10y ago
    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.
  - niftich 10y ago
    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 http://stateless.co/hal_specification.html [2] http://www.iana.org/assignments/link-relations/link-relations.xhtml http://www.iana.org/assignments/link-relations/link-relation...
  - dragonwriter 10y ago
    > 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.
- deleted 10y ago
  [deleted]
- einrealist 10y ago
  No worries. There are people out there, like me, who agree with you. You have my vote on this. Lets say Microsoft at least created their own format, that allows some discovery. That is a good approach, because a big upfront design can be harmful. There are few decisions in HTML you can take as an example. I am currently working on having a format for my company, that is based on Siren. Its no easy thing to do, because I want it to be easy to be used (which is not simple).
yeukhon 10y ago
https://evertpot.com/dropbox-post-api/ 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.
- ams6110 10y ago
  I have worked with some systems that do not expose all http methods. Having a fallback way to invoke a method as a GET or POST makes your API more usable to more clients.
- balls187 10y ago
  An advantage of GET for all APIs is simplifying access to the API via a web browser.
- dozzie 10y ago
  > 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.
  - yeukhon 10y ago
    We ran into a situation exactly like that. We hit the limit of the length of GET. Thanks.
mythz 10y ago
Funny that Microsoft uses OData as an example of a bad URL: https://github.com/Microsoft/api-guidelines/blob/master/Guidelines.md#71-url-structure https://github.com/Microsoft/api-guidelines/blob/master/Guid... Whilst continuing to praise OData as "the best way to REST" - http://www.odata.org http://www.odata.org
- erjjones 10y ago
  Thinking the exact same thing +1
- bunderbunder 10y ago
  Microsoft came up with OData about 10 years ago, but it's now steered by a technical committee with a lot of participants. I wouldn't necessarily be so quick to assume that the OASIS committee - or Microsoft's representatives on it - speak for all of Microsoft. Let alone an internal guidelines committee that they apparently convened fairly recently (given the age of the report) when they use that slogan.
  - mythz 10y ago
    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 in-contrast and devalues sincere efforts like this where they're actually looking to promote good HTTP API practices.
    - andybak 10y ago
      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.
daxfohl 10y ago
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.
- tarequeh 10y ago
  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.
  - niftich 10y ago
    Send the most appropriate HTTP status code, along with an error resource the client purports to understand (by accept header content negotiation). If the client isn't declaring to accept a mediatype you produce, you send your fallback error format, which could be anything you choose: text/plain, or some custom format you design, or some generic hypermedia type that defines an error field.
  - PallarelCoedr 10y ago
    Perhaps look at HTTP Problem Details? https://tools.ietf.org/html/rfc7807 https://tools.ietf.org/html/rfc7807
  - MichaelGG 10y ago
    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.
deathanatos 10y ago
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 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": {} } vs. ["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.) [1]: http://use-the-index-luke.com/no-offset http://use-the-index-luke.com/no-offset [2]: https://tools.ietf.org/html/rfc5988 https://tools.ietf.org/html/rfc5988
- brandonbloom 10y ago
  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 of ability to represent structure. Lastly, if you ever decide to use a different "transport" protocol other than HTTP, you'll be glad you are already using a common representation without a side channel.
  - 10y ago
zeveb 10y ago
Wow, 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.
- mianos 10y ago
  From the same people who brought you the XML SOAP API. Smart people. Too smart?
mikro2nd 10y ago
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?
- beckler 10y ago
  Troy Hunt has an article where he shows three different ways to declare a version, including the header method. https://www.troyhunt.com/your-api-versioning-is-wrong-which-is/ https://www.troyhunt.com/your-api-versioning-is-wrong-which-...
- JimDabell 10y ago
  Neither of the schemes mentioned here are good as they change the URI for a resource, which breaks all sorts of things. Could you imagine if every website wanting to switch from HTML 4 to HTML 5 had to update their URIs from https://www.example.com/HTMLv4/contact.html https://www.example.com/HTMLv4/contact.html to https://www.example.com/HTMLv5/contact.html https://www.example.com/HTMLv5/contact.html? It would be chaos. For instance, if client application A talks to the service using version 1.0 of the API and client application B talks to the service using version 2.0 of the API, then those client applications can't interoperate because they are seeing two different sets of resources. Your solution isn't far off the approach recommended by everybody who rejects the different URI approach. You don't need an API version header. When your representation format for a resource changes, provide a `version` parameter for the media type. For example: `Content-Type: application/vnd.example.foo+json;version=2`. This is exactly how HTTP and the `Content-Type` header are supposed to work – if your representation for a resource changes, you don't change the URI, you change the media type.
  - jdmichal 10y ago
    Interestingly enough, putting it in Content-Type is also invalid unless the mime type allows it. (Which, of course, is trivial if you're defining your own.) Specifically, RFC 2616 specifies that clients SHOULD only specify parameters which are valid for the mime type [0]. This can get more restrictive; for instance, JSON-API (application/vnd.api+json) states that any parameters MUST result in 415 UNSUPPORTED MEDIA TYPE [1]. [0] https://www.w3.org/Protocols/rfc2616/rfc2616-sec3.html#sec3.7 https://www.w3.org/Protocols/rfc2616/rfc2616-sec3.html#sec3.... [1] http://jsonapi.org/format/ http://jsonapi.org/format/
iheart2code 10y ago
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?
- dsp1234 10y ago
  Delta queries can be serviced by any system that supports temporal tables[0][1], or another mechanism where data changes are tracked. [0] - https://en.wikipedia.org/wiki/SQL:2011 https://en.wikipedia.org/wiki/SQL:2011 (temporal support) [1] - https://msdn.microsoft.com/en-us/library/dn935015.aspx https://msdn.microsoft.com/en-us/library/dn935015.aspx [2] - http://clarkdave.net/2015/02/historical-records-with-postgresql-and-temporal-tables-and-sql-2011/ http://clarkdave.net/2015/02/historical-records-with-postgre...
- ChrisAtWork 10y ago
  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 different.
  - iheart2code 10y ago
    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.
    - ChrisAtWork 10y ago
      I don't think I've ever seen delta's done at-scale with actual temporal tables, but rather with transaction Id's of some sort. For example (based on the doc) when you register a delta link, there's a row written to Azure Tables saying, "owner:iheart2code, deltaToken:foo, lastRecordIdSeen:123". When you then make the Delta request, we look up "foo" for you, find that the last id you've seen is 123, and then only give you records from the transaction table with an id larger than that. Temporal is always a can of worms, as clocks are impossible to keep in sync and there are endless race conditions. Making the delta tokens causal, rather than temporal, is the way to go. Anything else is brutal in the distributed systems world...
blakeyrat 10y ago
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 sure why that's such a blind spot. Doesn't every web service need to upload files eventually?
- gedy 10y ago
  POST /users/{id}/avatar ? What additional guidance would you expect?
  - blakeyrat 10y ago
    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 .ashx handler, but is that literally the best way? It feels like a horrible nasty hack.
    - niftich 10y ago
      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?
      - blakeyrat 10y ago
        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.
captn3m0 10y ago
Interesting to see Microsoft talk about "human-readable URLs". I still remember the mess kb.microsoft (or the surrounding MS infra) was at a time. Nice to see them support such stuff, still.
intellix2 10y ago
Surprised people are still talking about REST after GraphQL
intellix2 10y ago
Surprised people are still talking about REST after Facebook unveiled GraphQL
spdustin 10y ago
Seems ... strange to bash their own "Best Way to REST" offering, OData [0] [0]: http://www.odata.org http://www.odata.org
raz32dust 10y ago
Jeez... anyone else find the caps hurting the eyes? Is it necessary? Sorry I have nothing constructive to add. Just had to bring this up.
horacios 10y ago
Several of the REST API Guideline authors were the same ones inventing WS-* protocols 15 years ago. They were convinced REST wasn't good enough to build web-scale apps. Better late than never!
ZalandoTech 10y ago
Zalando released our RESTful API guidelines a few months back -- they're very comprehensive and open-source. Feedback and suggestions welcome: https://zalando.github.io/restful-api-guidelines/ https://zalando.github.io/restful-api-guidelines/
dehora 10y ago
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 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/compatibility/Compatibility.html 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 :)
aligajani 10y ago
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.
- fooyc 10y ago
  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.

339 points by alpb 10y ago

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 embrace the full benefits of REST, and develop the technology and conventions/standards for integrating RESTful services. Edit: for an example of what's possible with 'real' REST, check out this talk: https://vimeo.com/20781278 https://vimeo.com/20781278 – better documentation, easy parsing, API optimisation without client changes, discovery, and the API is fully human readable/usable as well.

pstuart 10y ago
Any shining examples you'd care to share?
- petersellers 10y ago
  The JSON API spec is pretty good: http://jsonapi.org/ http://jsonapi.org/
- yeukhon 10y ago
  Search for "rest api standard" you will find a bunch. While I like standard, and I am always an advocate of standard, I also don't agree with standard body's decision on the exact format. This is the challenge. HATEOS is an absolutely great idea, but also painful to implement, making payload larger. One question I ask is "how many kinds of resource links do I need to supply?"
- gregmac 10y ago
  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 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. [1] [1] https://jeffknupp.com/blog/2014/06/03/why-i-hate-hateoas/ https://jeffknupp.com/blog/2014/06/03/why-i-hate-hateoas/
  - icebraining 10y ago
    The thing is, those servers and clients already exist, people are just to tied to their notion of "API" to see them. And in fact, you used them to post that very comment. A website is a RESTful service which a generic client can interact with despite not having any custom code. Does it do so by magically understanding what an <a> or <img> tags are or by magically decoding PNG bytestreams? No, the service uses standard formats that the browser knows and which encode these semantics, allowing it to process them despite its original developers quite possibly not even knowing that service existed.
    - gregmac 10y ago
      > No, the service uses standard formats that the browser knows and which encode these semantics, allowing it to process them despite its original developers quite possibly not even knowing that service existed. You're correct. But that's not what we're talking about. We're talking about a web browser that can understand its posting a Comment, not a form (or a random collection of key-value pairs). The primitives that make the web work are quite different from the high-level concepts that make an application work. My browser understands how to display links and forms and text and graphics. It does not understand how to display a comment or a user account or the number of votes a comment has, let alone know when I'm allowed to vote up or down, understand the relationship between a user account and a comment, understand a comment being owned by my user account or another, etc, etc. What exactly is the end goal? That a HATEOAS-style REST API can be created, you can go to some entry point with your browser, and with no one writing any UI code it just understands how to render the Hacker News site? It will magically understand that the main page contains a list of articles, those articles have comments, links to an original source, etc? This is my understanding of the goal of HATEOAS. If that's not the goal, I don't understand what it gets besides being a way to build a tiny part of documentation necessary to consume an API.
  - danpalmer 10y ago
    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/ 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.
ihsw 10y ago
There are degrees of completeness and this expands on the REST standard by a whole lot more. Frankly I would prefer adhering to this standard.
varenc 10y ago
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.
- danpalmer 10y ago
  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!
  - falcolas 10y ago
    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.
    - danpalmer 10y ago
      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.
rimantas 10y ago
Not sure about your karma sacrifice, but if someone has doubts: > What needs to be done to make the REST architectural style clear on the > notion that hypertext is a constraint? In other words, if the engine of > application state (and hence the API) is not being driven by hypertext, > then it cannot be RESTful and cannot be a REST API. Period. Is there > some broken manual somewhere that needs to be fixed? That's by Roy T. Fielding himself (http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte...) So if it is not HATEOAS it is not REST. Alas, I am not aware about any term which can be used for these Richardson maturity model Level 2 services.
- danpalmer 10y ago
  Thank you for that quote, I shall save it for future use. Also lots of replies and 0 points. That's what I'm talking about, this always gets downvoted.
- d0mine 10y ago
  It reminds me that GIF is pronounced GIF by most people even if the inventor pronounces it as JIF. The language is what people use to communicate. REST may mean whatever most people think it means regardless what the inventor of the term thinks it should mean. Another example is the word hacker. For most people it is "a person who uses computers to gain unauthorized access to data" (according to Google) that is different from the meaning used on this site: "one who works like a hack at writing and experimenting with software, one who enjoys computer programming for its own sake" http://www.etymonline.com/index.php?term=hacker http://www.etymonline.com/index.php?term=hacker
SwellJoe 10y ago
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 what the whole elephant looks like, and have good resources for what makes something actually REST, I'd be interested.
- icebraining 10y ago
  I suggest you go to the original source, ie, Roy Fielding: https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arc... http://roy.gbiv.com/untangled/tag/rest http://roy.gbiv.com/untangled/tag/rest https://www.infoq.com/articles/roy-fielding-on-versioning https://www.infoq.com/articles/roy-fielding-on-versioning
  - toomanythings4 10y ago
    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.
- danpalmer 10y ago
  This is the video that made it finally "click" for me. https://vimeo.com/20781278 https://vimeo.com/20781278 We don't yet have the abstractions, libraries, conventions or standards for this to work fully yet, but we're close.
- ianai 10y ago
  I think the above commentor got it right. You map the CRUD actions to HTTP verbs and statuses, as many of them make sense for your API, with links to further resources along the way.
- jcrites 10y ago
  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-hypertext-driven http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte...
daliwali 10y ago
I don't know why everyone wants to downvote this comment. It's absolutely right. I would add that REST has nothing to do with pretty URIs, JSON formatting, versioning, query strings, and more misconceptions that people seem to mistake for the architectural style. There is nothing that isn't RESTful with URIs like "/a89f30e9" instead of "/:type/:id". Even TBL thinks URIs should be opaque: https://www.w3.org/DesignIssues/Axioms.html#opaque https://www.w3.org/DesignIssues/Axioms.html#opaque
gedy 10y ago
To be frank, main issue is people are arguing about semantics, one side thinks Fielding's definition is the only thing that can be called REST, and the other larger(?) side could care less about that academic definition and are describing some simple rules for HTTP APIs. While it would be nice if there were two terms, just saying "This is NOT REST" really doesn't clarify anything.
xienze 10y ago
> 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 available and the right way to use it. To me the hypermedia part of REST has always seemed like a pointless academic exercise. Yes it's really cool to be able to point a service browser at your service's root resource and have it map the whole thing out but in practice, when is this ever anything but a neat party trick?
- danpalmer 10y ago
  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.
- niftich 10y ago
  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 http://stateless.co/hal_specification.html [2] http://www.iana.org/assignments/link-relations/link-relations.xhtml http://www.iana.org/assignments/link-relations/link-relation...
- dragonwriter 10y ago
  > 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.
deleted 10y ago
[deleted]
einrealist 10y ago
No worries. There are people out there, like me, who agree with you. You have my vote on this. Lets say Microsoft at least created their own format, that allows some discovery. That is a good approach, because a big upfront design can be harmful. There are few decisions in HTML you can take as an example. I am currently working on having a format for my company, that is based on Siren. Its no easy thing to do, because I want it to be easy to be used (which is not simple).

yeukhon 10y ago

https://evertpot.com/dropbox-post-api/ 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.

ams6110 10y ago
I have worked with some systems that do not expose all http methods. Having a fallback way to invoke a method as a GET or POST makes your API more usable to more clients.
balls187 10y ago
An advantage of GET for all APIs is simplifying access to the API via a web browser.
dozzie 10y ago
> 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.
- yeukhon 10y ago
  We ran into a situation exactly like that. We hit the limit of the length of GET. Thanks.

mythz 10y ago

Funny that Microsoft uses OData as an example of a bad URL: https://github.com/Microsoft/api-guidelines/blob/master/Guidelines.md#71-url-structure https://github.com/Microsoft/api-guidelines/blob/master/Guid... Whilst continuing to praise OData as "the best way to REST" - http://www.odata.org http://www.odata.org

erjjones 10y ago
Thinking the exact same thing +1
bunderbunder 10y ago
Microsoft came up with OData about 10 years ago, but it's now steered by a technical committee with a lot of participants. I wouldn't necessarily be so quick to assume that the OASIS committee - or Microsoft's representatives on it - speak for all of Microsoft. Let alone an internal guidelines committee that they apparently convened fairly recently (given the age of the report) when they use that slogan.
- mythz 10y ago
  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 in-contrast and devalues sincere efforts like this where they're actually looking to promote good HTTP API practices.
  - andybak 10y ago
    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.

daxfohl 10y ago

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.

tarequeh 10y ago
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.
- niftich 10y ago
  Send the most appropriate HTTP status code, along with an error resource the client purports to understand (by accept header content negotiation). If the client isn't declaring to accept a mediatype you produce, you send your fallback error format, which could be anything you choose: text/plain, or some custom format you design, or some generic hypermedia type that defines an error field.
- PallarelCoedr 10y ago
  Perhaps look at HTTP Problem Details? https://tools.ietf.org/html/rfc7807 https://tools.ietf.org/html/rfc7807
- MichaelGG 10y ago
  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.

deathanatos 10y ago

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 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": {} } vs. ["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.) [1]: http://use-the-index-luke.com/no-offset http://use-the-index-luke.com/no-offset [2]: https://tools.ietf.org/html/rfc5988 https://tools.ietf.org/html/rfc5988

brandonbloom 10y ago
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 of ability to represent structure. Lastly, if you ever decide to use a different "transport" protocol other than HTTP, you'll be glad you are already using a common representation without a side channel.
- 10y ago

zeveb 10y ago

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

mianos 10y ago
From the same people who brought you the XML SOAP API. Smart people. Too smart?

mikro2nd 10y ago

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?

beckler 10y ago
Troy Hunt has an article where he shows three different ways to declare a version, including the header method. https://www.troyhunt.com/your-api-versioning-is-wrong-which-is/ https://www.troyhunt.com/your-api-versioning-is-wrong-which-...
JimDabell 10y ago
Neither of the schemes mentioned here are good as they change the URI for a resource, which breaks all sorts of things. Could you imagine if every website wanting to switch from HTML 4 to HTML 5 had to update their URIs from https://www.example.com/HTMLv4/contact.html https://www.example.com/HTMLv4/contact.html to https://www.example.com/HTMLv5/contact.html https://www.example.com/HTMLv5/contact.html? It would be chaos. For instance, if client application A talks to the service using version 1.0 of the API and client application B talks to the service using version 2.0 of the API, then those client applications can't interoperate because they are seeing two different sets of resources. Your solution isn't far off the approach recommended by everybody who rejects the different URI approach. You don't need an API version header. When your representation format for a resource changes, provide a `version` parameter for the media type. For example: `Content-Type: application/vnd.example.foo+json;version=2`. This is exactly how HTTP and the `Content-Type` header are supposed to work – if your representation for a resource changes, you don't change the URI, you change the media type.
- jdmichal 10y ago
  Interestingly enough, putting it in Content-Type is also invalid unless the mime type allows it. (Which, of course, is trivial if you're defining your own.) Specifically, RFC 2616 specifies that clients SHOULD only specify parameters which are valid for the mime type [0]. This can get more restrictive; for instance, JSON-API (application/vnd.api+json) states that any parameters MUST result in 415 UNSUPPORTED MEDIA TYPE [1]. [0] https://www.w3.org/Protocols/rfc2616/rfc2616-sec3.html#sec3.7 https://www.w3.org/Protocols/rfc2616/rfc2616-sec3.html#sec3.... [1] http://jsonapi.org/format/ http://jsonapi.org/format/

iheart2code 10y ago

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?

dsp1234 10y ago
Delta queries can be serviced by any system that supports temporal tables[0][1], or another mechanism where data changes are tracked. [0] - https://en.wikipedia.org/wiki/SQL:2011 https://en.wikipedia.org/wiki/SQL:2011 (temporal support) [1] - https://msdn.microsoft.com/en-us/library/dn935015.aspx https://msdn.microsoft.com/en-us/library/dn935015.aspx [2] - http://clarkdave.net/2015/02/historical-records-with-postgresql-and-temporal-tables-and-sql-2011/ http://clarkdave.net/2015/02/historical-records-with-postgre...
ChrisAtWork 10y ago
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 different.
- iheart2code 10y ago
  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.
  - ChrisAtWork 10y ago
    I don't think I've ever seen delta's done at-scale with actual temporal tables, but rather with transaction Id's of some sort. For example (based on the doc) when you register a delta link, there's a row written to Azure Tables saying, "owner:iheart2code, deltaToken:foo, lastRecordIdSeen:123". When you then make the Delta request, we look up "foo" for you, find that the last id you've seen is 123, and then only give you records from the transaction table with an id larger than that. Temporal is always a can of worms, as clocks are impossible to keep in sync and there are endless race conditions. Making the delta tokens causal, rather than temporal, is the way to go. Anything else is brutal in the distributed systems world...

blakeyrat 10y ago

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 sure why that's such a blind spot. Doesn't every web service need to upload files eventually?

gedy 10y ago
POST /users/{id}/avatar ? What additional guidance would you expect?
- blakeyrat 10y ago
  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 .ashx handler, but is that literally the best way? It feels like a horrible nasty hack.
  - niftich 10y ago
    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?
    - blakeyrat 10y ago
      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.

captn3m0 10y ago

Interesting to see Microsoft talk about "human-readable URLs". I still remember the mess kb.microsoft (or the surrounding MS infra) was at a time. Nice to see them support such stuff, still.

intellix2 10y ago

Surprised people are still talking about REST after GraphQL

intellix2 10y ago

Surprised people are still talking about REST after Facebook unveiled GraphQL

spdustin 10y ago

Seems ... strange to bash their own "Best Way to REST" offering, OData [0] [0]: http://www.odata.org http://www.odata.org

raz32dust 10y ago

Jeez... anyone else find the caps hurting the eyes? Is it necessary? Sorry I have nothing constructive to add. Just had to bring this up.

horacios 10y ago

Several of the REST API Guideline authors were the same ones inventing WS-* protocols 15 years ago. They were convinced REST wasn't good enough to build web-scale apps. Better late than never!

ZalandoTech 10y ago

Zalando released our RESTful API guidelines a few months back -- they're very comprehensive and open-source. Feedback and suggestions welcome: https://zalando.github.io/restful-api-guidelines/ https://zalando.github.io/restful-api-guidelines/

dehora 10y ago

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 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/compatibility/Compatibility.html 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 :)

aligajani 10y ago

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.

fooyc 10y ago
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.