15 ms·
Microsoft REST API Guidelines
- jdprt 7y agoWhere's the section saying "so get rid of your SOAP WS already OK?" That would be lovely!
- will4274 7y agoWhat's wrong with SOAP? SOAP is a lot more than REST, so you'd need to explain an additional technology beyond REST in order to recommend moving away from SOAP.
- dang 7y agoDiscussed in 2016: https://news.ycombinator.com/item?id=12122828 https://news.ycombinator.com/item?id=12122828
- jmuguy 7y agoWhat do other folks here think of how MS handles query params, specifically stuff like filtering? https://github.com/Microsoft/api-guidelines/blob/master/Guidelines.md#97-filtering https://github.com/Microsoft/api-guidelines/blob/master/Guid... When working with the Graph API for 365 I thought it was really weird how you had to pass some params GET https://api.contoso.com/v1.0/products?$filter=name eq 'Milk'
- Ididntdothis 7y agoAt first look I think using spaces is a bad idea but maybe it’s ok.
- wnevets 7y agoyeah seeing spaces is kinda weird IMO
- drbw 7y agoAren't things like $filter, $orderBy etc. straight out of the OData standard[1]. [1] https://www.odata.org/ https://www.odata.org/
- brenden2 7y agoIt looks weird when you write it that way, but the ' ' character gets translated into '+' when you encode the URI before making a request. If it was me, I'd prefer to see the '+' encoding than ' ' because it looks strange when it's not a valid URI.
- deleted 7y ago[deleted]
- vkaku 7y agoToo much emphasis on interfaces than on programmability. I don't even know if they follow their own rules too. Also, they define DELETE as idempotent, which is a little different from how some of us write APIs.
- zerocrates 7y agoHow are you thinking of doing it differently? DELETE is typically considered idempotent.
- treve 7y agoThey don't define DELETE as idemptotent, the HTTP standard does. It also feels very natural for DELETE to be IMHO, so I would be curious what strange thing you do
- alkonaut 7y agoNote that idempotent in this context means “2 calls will end up with the same server state as one call”. It does not mean for example that the second call can’t return a different response than the first.
- JMTQp8lwXL 7y agoIf "idempotent" means "do the same thing", one would expect the same response on a subsequent call, no? "Do the same thing" isn't specific enough. Does it mean the state of the system? Does it mean the response code? Does it mean the response body? Does it mean all of these things? All seem like reasonable interpretations.
- alkonaut 7y agoIn the context of REST it means the same server state (a database table state, a mailbox state, file system state etc) It doesn’t mean “do the same thing” or “get the same response”, only “end up in the same place”. You can do a delete x, get an OK response, and the important state is that x is now deleted on the server. Then the next call to delete x does nothing (which is different from the first which deleted x!). So to be idempotent it has to do something different. The response in the second case can be both “ok” (because the thing is deleted) but also e.g “x doesn’t exist”.
- BstBln 7y ago„Some services MAY add fields to responses without changing versions numbers. Services that do so MUST make this clear in their documentation“ WTF
- cosmodisk 7y agoRemember doing an integration with a finance company's API. I read their documentation,write the code,all works fine, we are moving towards go live date. A week later, my integration fails. I try hell knows how many things, eventually contact their lead dev asking what am doing wrong...The answer was "Oh,emm,yes,we've kind of changed the response format slightly, it's not in the documentation"... I got that fixed.. It's working again.Then, we suppose to go live next week.2 days before go live date I get told we are cancelling all business with the company...All the integration code goes into a bin.
- BstBln 7y agoAssuming you’re working with JSON, it’s very easy to ignore extra fields and no reason to deploy any fixes for that :)
- gt2 7y agoWhere did it say it was an extra field? It says format change which could make for problems for sure! edit: ah you must be referring to the GP. But the anecdote just says format change.
- 7y ago
- jedberg 7y agoEvery single person writing a REST api should have to memorize this table: GET - Return the current value of an object, is idempotent; PUT - Replace an object, or create a named object, when applicable, is idempotent; DELETE - Delete an object, is idempotent; POST - Create a new object based on the data provided, or submit a command, NOT idempotent; HEAD - Return metadata of an object for a GET response. Resources that support the GET method MAY support the HEAD method as well, is idempotent; PATCH - Apply a partial update to an object, NOT idempotent; OPTIONS - Get information about a request, is idempotent. Most importantly, that PUT is idempotent. Credit to arkadiytehgraet for retyping the table to be readable. Please give them an upvote for the effort.
- gkoberger 7y agoI agree REST APIs should be built this way, however I disagree any end user should ever have to think about APIs this way. I think a good SDK should hide most of this complexity away, and no real human should ever have to know the difference between a PUT or a POST. APIs should think more like people; people shouldn't have to think more like APIs. EDIT: Since I didn't make my case well enough, here's an example. Let's say you want to charge a credit card. Are you doing a `POST /charge`? Or would it be better to say `card.charge(500)`? My point isn't that there shouldn't be a proper REST API below it, but rather that we should offer abstractions so normal semi-technical people can use APIs and don't have to think too much like a computer.
- mattlutze 7y agoI feel like, if we're not writing data-interfacing applications with PUT and POST as specifically different actions in mind, we're doing something wrong. People think in ambiguity; adding a new item or replacing an existing item, as in this example, shouldn't be something an application needs to guess at.
- jmull 7y agoHow could someone use an API correctly without understanding it?
- erjjones 7y agoIdeally, they wouldn't re-invent the wheel again and just stick with the ODATA protocol. They already have the platform to do so - https://docs.microsoft.com/en-us/odata/resources/roadmap https://docs.microsoft.com/en-us/odata/resources/roadmap
- mumblemumble 7y agoEvery time I see a discussion about REST guidelines, I get a little bit more happy about having switched to gRPC.
- asdkhadsj 7y agoMan, I wanted to love gRPC. The disconnect between Protobufs and languages just felt too great though. You could do some weird things that just made every language feel, to some degree, non-idiomatic. I switched to Twirp at one point to retain the simplicity of RPC + Protobuf, but avoid some of the complexity we didn't need via gRPC... but even that suffered, of course, from the Protobuf problem. Finally I'm back to plain HTTP and JSON. We don't worry too much about REST fundamentals, and honestly we're more like an ad-hoc (JSON) RPC over HTTP, but it's simple. The only problem is documentation. The one thing that I found perfect with Protobuf. Seems really hard to have everything here.
- addcn 7y agoHow would you articulate "the protobuf problem" to a gRPC novice like me? Also re http/rest docs -- check out my open source project -- it's sort of like Git but for Rest APIs https://github.com/opticdev/optic https://github.com/opticdev/optic
- asdkhadsj 7y agoI go over it in a bit more detail here: https://news.ycombinator.com/item?id=21621592 https://news.ycombinator.com/item?id=21621592 But in short, Protobuf is inherently a language of its own. Like JSON or etc. But it's feature rich enough that it can cause a fair number of incompatibilities between a language's preferred style or usage of features. Where the incompatibility shows up depends on the language. I found it to be very different between Rust and Go, for example.
- ben509 7y ago> You could do some weird things that just made every language feel, to some degree, non-idiomatic. Could you elaborate on this?
- laurent123456 7y agoI find that MS are often quite good at developing good APIs and documenting them. In this new doc I particularly like the Delta Queries section [0]. It's something that's difficult to get right but with this you can pretty much copy and paste their guidelines for your project. 0: https://github.com/Microsoft/api-guidelines/blob/master/Guidelines.md#10-delta-queries https://github.com/Microsoft/api-guidelines/blob/master/Guid...
- jayd16 7y agoOk, this may be a dumb question but is there any risk to using/enforcing PATCH in your APIs in this day and age? I still avoid it but that's probably just cargo culting now, right?
- SSchick 7y agoAt MS, in our team no manager gave the slightest damn about being restful or any proper consistent API design. Everything was constantly rushed and just 'tacked on', random API versions were created, contracts were broken, nothing was consistent. It was a mess. That said, I believe most of these guidelines completely ignored in most teams.
- TinyRick 7y agoAs a fairly heavy consumer of the Azure DevOps REST APIs, this sounds pretty accurate.
- dpark 7y agoIt’s almost as if there are different groups in Microsoft with different priorities. Why is it so hard to get 130k people in complete assignment across all areas? Seems like a simple problem.
- Someone1234 7y ago> It’s almost as if there are different groups in Microsoft with different priorities. Why is it so hard to get 130k people in complete alignment across all areas? Seems like a simple problem. I feel like this could have been said without the sarcasm and it would have been a great discussion starter. Instead a potentially valid point/retort will be obscured by the tone and discussion surrounding it. For example: > Unfortunately large organizations often struggle to get groups into alignment on issues like this, unless there's a strong mandate from the top down (e.g. Amazon). No sarcasm or snark, same basic substance.
- mixmastamyk 7y agoAnd not correct either. As mentioned, if Satya said so it would happen within months.
- dpark 7y agoThere are a limited number of mandates that can come from the top. Upper management loses credibility when they issue endless mandates, even if all of the mandates are reasonable. It’s also unrealistic that everyone underneath can focus on many mandates at once. Which leads to the loss of credibility when mandates start getting ignored out of necessity.
- MiyamotoAkira 7y agoThis keeps bothering me: >7.1 URL structure >Humans SHOULD be able to easily read and construct URLs. >This facilitates discovery and eases adoption on platforms >without a well-supported client library. The URL is ephemeral on REST. That is because you create the documents on the fly. They can be linked or not to things that you store on the datastore. Allows you to easily change around as needed because the URL is not the API. The hyperlinks are the API. The URL is like a memory pointer. You shouldn't care about it.
- danellis 7y agoWhy isn't this called "HTTP API Guidelines"? It doesn't seem to have much to do with REST at all. For example, it says that people should be able to construct URLs, whereas the REST style uses the URLs found in resources. To be clear, I'm not saying that there is anything wrong with the practices they propose here, just that they're not what they're claiming they are.
- vearwhershuh 7y agoThe primary innovation in REST is HATEOAS (which isn't mentioned in the document at all.) JSON isn't a hypertext, it just isn't a good format for REST-ful services. http://intercoolerjs.org/2016/01/18/rescuing-rest.html http://intercoolerjs.org/2016/01/18/rescuing-rest.html http://intercoolerjs.org/2016/05/08/hatoeas-is-for-humans.html http://intercoolerjs.org/2016/05/08/hatoeas-is-for-humans.ht... Doesn't anyone notice this? I feel like I'm taking crazy pills. https://www.youtube.com/watch?v=HOK6mE7sdvs https://www.youtube.com/watch?v=HOK6mE7sdvs
- ben509 7y agoSo that's what HATEOAS is. I had been wondering why the Github APIs had these absurdly large responses with a shit-ton of urls. > JSON isn't a hypertext, it just isn't a good format for REST-ful services. The point of REST was to take ideas from the browser and apply them to other services. But HATEOAS is proving that REST only really makes sense if you've got a browser on the other end. > Doesn't anyone notice this? I feel like I'm taking crazy pills. The first comment I saw on this article was, _every single person writing a REST api should have to memorize this table_. If you were trying to sell people on a new library and said, "everyone here has to memorize this table," you'd get laughed at as a crazy person.
- ssijak 7y agoNo, HATEOAS is not for humans but was imagined for api consumers. All those links that you mentioned in the Github api responses are named and you as a client can use them, where the actual url can change. Also, you as an api consumer can know what actions are available. That being said, I have never seen developing api client driven mainly by HATEOAS
- einrealist 7y agoImagine an API returning HTML, too. I've built such APIs (not public). I consider it best practice. The HTML representation can be utilized as the frontend. At least, its the interactive documentation to the API. In fact, when I built such APIs, I usually started with the HTML representation.
- isvalid 7y agoCool guidelines!
- littlecranky67 7y agoI've designed quite some REST APIs, but I've come to the conclusion that all those semantic/HATEOS or other REST guidelines don't always apply or make sense, depending on the problem domain. I worked in finance and designed a REST API, and besides the standard user/account object, basically ALL the data and operations were neither idempotent, cacheable, durable and often couldn't possible be designed using HATEOS et al. Quotes, orders, offers and transactions carry lots of monetary amounts which are sent in user currency, which is auto-converted depending on the user requesting it (and currency conversion rates is part of the business). Most offers are only valid a limited amount of time (seconds to minutes) because of changing market rates. There is also no "changing" of object as in PATCH/DELETE, all you do is trigger operations via the API and every action you ever did is kept in a log (regulatory wise, but also to display for the end user). There is some way to try to hammer this thing to fit with HATEOS et. al. and I put some effort in it, but I would have ended up splitting DTOs into idempotent/mutable and non-idempotent/mutable parts and spread them across different services, bloat the DTOs themselves (i.e. include all available currencies in a quote/offer) and have the validity/expiry of objects via HTTP caching (instead of the DTOs). That would have ended up in a complex and hard-to-read API, would have significantly worse performance (due to lot of unneeded data & calculations) and some insane design decisions (like keeping expired offers/quotes around just so they are still available at their service URL with an id, even though the business requirements would never store expired offers). Sometimes you just need to use your own head, accept that the problem domain might not be covered by other "guidelines", and come up with a sane design yourself.
- pas 7y agoREST shines where there is a big path dependent interaction graph - ie. feature switches, permissions, plans/packages and other statefull stuff.
- einrealist 7y agoThis is more a opinionated design document for HTTP than it is for REST. There is not a single word about semantic formats and HATEOAS. I really expected more from Microsoft in this area. Had I the time to write such a design document, I would start with ressources, versioning, URI and semantic documents. I would write about entity models, linking (links, link templates) and actions. I would write about representations and about how represenations can support optimizations, embedding of resources and entity expansion, which would otherwise be addressed by inventions like GraphQL. And only afterwards, I would write about HTTP as a transfer protocol. But that part can be brief, because there is already the HTTP specification out there.
- BstBln 7y agoAlso seems they never heard about versioning via content negotiation :)
- excerionsforte 7y agoVersioning through HTTP Headers was the spark for why I was looking around for guidelines. I think it is the better way to go other than URL versioning.
- BstBln 7y agoI think so too, but even in case one disagrees, they should have mentioned it. Otherwise you’d think they never had heard of it :)
- perlgeek 7y ago> An example URL that is not friendly is: > https://api.contoso.com/EWS/OData/Users('jdoe@microsoft.com')/Folders('AAMkADdiYzI1MjUzLTk4MjQtNDQ1Yy05YjJkLWNlMzMzYmIzNTY0MwAuAAAAAACzMsPHYH6HQoSwfdpDx-2bAQCXhUk6PC1dS7AERFluCgBfAAABo58UAAA=') https://api.contoso.com/EWS/OData/Users('jdoe@microsoft.com'... A well-deserved dig at the sharepoint API.