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

I'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.

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

The 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/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

Every time I see a discussion about REST guidelines, I get a little bit more happy about having switched to gRPC.

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

Discussed in 2016: https://news.ycombinator.com/item?id=12122828

Ideally, 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

What do other folks here think of how MS handles query params, specifically stuff like 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'

I 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/Guid...

> An example URL that is not friendly is:

> https://api.contoso.com/EWS/OData/Users('jdoe@microsoft.com'...

A well-deserved dig at the sharepoint API.

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

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

Also seems they never heard about versioning via content negotiation :)

Ok, 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?

Where's the section saying "so get rid of your SOAP WS already OK?" That would be lovely!

Cool guidelines!

„Some services MAY add fields to responses without changing versions numbers. Services that do so MUST make this clear in their documentation“

WTF

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