The Disadvantages of REST Are Its Advantages

I was recently asked a very interesting question as part of an interview process: "what are the disadvantages of REST?" I could think of a few issues off the top of my head, but they turned out to be deeper than I'd thought, and I had to research them.

It turns out what's just as interesting as the issues is that REST is questioned at all--not as much discussion as you might think has been posted to the blogosphere. I found the following discussed in various articles. In each case, I came to the conclusion that the main disadvantages of REST are also its advantages.

REST is stateless

While statelessness is usually an advantage for CRUD operations, it's not suitable for some scenarios. An app makes discrete requests to a service using a REST API, but it's disconnected--the service is unaware of the app's state and vice versa. Therefore, REST is not ideal for continuing operations for which the service needs context about the state of the client app.

For example, consider a web service that allows you to query prices of commodity shares using GET requests and to make purchases using POST requests. The market share price changes continually, and could differ significantly between requests. The web service would have to implement additional application logic to ensure the client can purchase shares at the desired price.

REST has no built-in security

REST relies on TLS/SSL for secure data transaction, but authentication is not part of REST. REST does not have built-in security, so developers need to implement their own mechanism. Here are the usual methods:

• Basic authentication (username and password) in the client app; this can be augmented with 2FA
• OAuth1 (uses a cryptographic signature)
• OAuth2 (no cryptographic signature)
• Custom protocols (e.g. some web services provide unique API keys to app developers)

This article has deeper information on the above security methods: Secure Your REST API the Right Way.

REST has too few verbs

It's been suggested that REST needs additional verbs (such as MERGE, INCLUDE, or APPEND). In my opinion, this isn't a real drawback; most web services only use the 4-5 most common verbs, and PATCH covers other cases. It seems to me the real problem is that POST tends to be overloaded and has become a catch-all for most processing operations.

REST depends on HTTP

This is mostly an advantage, but has disadvantages. Using HTTP as the app transport protocol makes REST available on any app or browser with an HTTP connection. In cases where HTTP is not available, REST can't operate. In contrast, SOAP can use virtually any transport.

The above points aren't an exhaustive list, and the InfoQ article What Are the Drawbacks of REST? goes into further depth on the subject. This article provided me a great deal of guidance and insight for this post.

Modern Skills for Modern Content

As I mentioned in The Content Revolution, the standard for writing modern developer content is higher than expected in the past. In order to write this kind of content, you'll need a broader set of skills, and not just technical skills.

I defined modern developer content as text and code that shows a reader how to create and run a meaningfully functional process or application. But what does it really mean to develop meaningfully functional content?

• Meaningful implies that you need to develop the ability to analyze existing content and determine what content is needed. You will need to interview and negotiate with client teams about what scenarios to cover.

• Functional implies that you have to write code. That doesn't mean you have to be a professional developer--it simply means you have to be able to put together code that works. I typically need example code to work from and have used test code as a guide, and my coding skills are surely not the greatest--but I've cobbled together advanced demo apps.

In terms of technical training, I'd suggest that you:

• Focus on proficiency in one programming language. You might be a code language polyglot and know a bit about many languages, but it doesn't help you as much in practice as having the concepts down. If you can code well in one language, you can figure out how to code in another. (I've chosen Java which is almost a two-for-one, it's so similar to C#.)

• Use different development tools / IDEs such as VS, Eclipse, JBoss, or IntelliJ as much as you can. It'll broaden your perspectives and IDEs are your friend when you code!

• GitHub. Love it or hate it, most companies are storing code and content on GitHub repositories. If you don't want to learn Git, use Git for Windows, Linux, or Mac, and get a GitHub account.

• Project management is a discipline applicable to any project, including construction. A formal PMP course isn't necessary, but wouldn't hurt. I strongly suggest learning whatever you can about project management. At the very least learn how to do a Work Breakdown Structure (WBS).

• Test your code. I've taken a course in software testing, but honestly didn't get much out of it. As PWs we do a lot of testing, but it's not formal QA testing. We don't write test suites that probe every possible use case of the product. Rather we narrowly define a demonstrative scenario (or a few scenarios) for the feature. It's more important to learn how to use test suite code as a source guide for demo code--but that's the subject of an entirely separate article.

Not all the skills are technical though, so I'd also offer this general advice:

• Find a niche. In the course of my work I encounter areas where confusion and need for direction exists in the developer community, such as deployment of apps in the cloud.

• Interviewing and negotiation are soft skills that aren't really soft but rather critical. Because so much of our success depends on interviewing skills and asking the right questions, I feel Precision Questioning is one of the best skills to develop. Like, "do I even need to be reading this?" We also need to get better at asserting our professional advice to clients, so courses in negotiation would also be useful.

• Blogs. I'd just as soon suggest you write a novel as write a blog. It's a big commitment. But there are side benefits. You learn more about blog publishing platforms. You can post tips you learn on the job, or bigger projects that are variations or improvements of work you've done.

• Video. The future venue for technical presentations is video (maybe podcasting, depending on your field). I've learned a lot from online videos, and if you learn how to use Camtasia or an animation suite, you'll be taken much more seriously.

• Social media. I've never been a fan of Twitter, but colleagues have told me that you can build a reputation by answering questions on certain niche tech channels. Slack is intriguing, and I'm a big fan--however, be aware that its reach is limited to your current organization. Update your profile on LinkedIn, and use it for networking. Have a separate email account that you use for professional networking and use this on LinkedIn.

Modern Content for Modern Apps

Microsoft has been so fond of bandying about the term modern applications of late that I started wondering what exactly that means.

The term modern usually refers to the flat design UI called Metro, so named because of its:

• roots in the modern design movement, especially Bauhaus
• focus on Swiss typography, as in signs on public transit systems, which also evoke the name "Metro" (typo geeks note the UI font is Segoe)
• Influence by cinematic motion design

Metro was originally designed for Zune and the Windows Phone, and spread to the rest of the platform. This was likely due to the push to have the OS interoperate seamlessly on "three screens:" desktop, mobile, and entertainment consoles.

But Microsoft has also used the term modern business applications or modern developer apps for enterprise and cloud services. "Modern" here seems to refer to the special syzygy in which mobile devices (or any device, like a PC or XBOX) take advantage of cloud services. I searched for specifics online, and found nothing definitive, but I'd define it as best I can as follows.

A modern app is one that runs in the cloud and so is:

• Accessible from any device (mobile, tablet, desktop, entertainment console, TV, IOT).
• Dynamically scalable and allocateable. You can dynamically scale and deploy cloud resources.
• Available as needed. Companies can rent resources as needed and do not have to buy/maintain physical infrastructure to support the app.
• Collaborative. Developers can collaboratively develop and distribute the code (e.g. via GitHub).
• Secure/sandboxed. Users are authenticated and apps cannot affect resources outside their permitted sandbox.

The question that follows, then, is why not create modern content to support modern apps? And what would that content be like?

Modern content is writing and/or applications that engage with a target community in a practical, social, shared way that invites participation. It is:

• Practical/presentational
• Social/collaborative
• Shared/dynamic (via cloud across users and devices)

Breaking down the definition in more detail:

• Presentational means speaking personally to the audience (e.g. demo videos)
• Social means that feedback/comments can be included and can influence the content (e.g. blogs)
• Collaborative means that readers can annotate or contribute (e.g. wikis)
• Uses text, example code, and possibly audio/video presentation
• Blends instructional design and technical writing disciplines (e.g. a guided "how to")
• Is highly practical, to the point, avoids excessive conceptual content
• Ideally builds or is built around a working example app (goodbye, "Hello World")
• Avoids deeply nested TOCs and relies on search and links to find content
• TOCs are now more like content lists or content maps (clickable graphic maps)
• Shared means that users can access content via the cloud via many devices (mobile, tablet, desktop, XBOX, IOT);
• Shared/dynamic also implies instantaneous, dynamically enhanced content: when one shared instance is changed, all views are updated (Amazon publishing model: publish, test, adjust, republish)

Be the very model of a modern content developer

I'd like to give proper credit to these sources: I based my definition of modern UI and modern apps on my own experience at Microsoft and also from these articles:

HowToGeek: Ways Modern Apps Are Different from Desktop Apps

Enable modern business applications

Enabling Modern Apps with the Windows Azure Pack

The Content Revolution

Since the Great Recession of 2007, several trends have affected corporate thinking and particularly the way we work in IT. We're only too aware of downsizing and outsourcing, as well as expansion of responsibilities, as in "test your own code" and "edit your own docs." But there are more subtle trends that, if well understood, can be used to our advantage.

In the steady but anemic economy since that recession, companies have been rather cautious. They're reluctant to invest in anything that isn't a core revenue contributor. In the software industry, roles branded with the scarlet letter 'O' for 'Overhead' have been purged: localization, writing, editing, even product support and QA.


It's ridiculous to think that testing isn't an integral part of a software release. Yet in tough times, such thinking can prevail. In the same way, it might be tempting to think that content is merely an enhancement tacked onto software, but the fact is certain content is an integral part of the product. What we need to do is figure out what that critical kind of content is, and train ourselves to develop it.


Social technology, particularly comments on web pages and web feedback, have exposed certain traditional of content as useless. We're all too familiar with long-winded conceptual discourses and procedures for trivial or obvious tasks. Such content used to be seen as adding value to a product, then necessary for completeness. Now it's generally skipped over as worthless.

Search technology has seen tremendous advances. We used to index online docs, but now readers use long-tail searches on Google and Bing to find answers to a specific question rather than slogging through an index. We used to create massive directories of website URLs (Yahoo, Excite, WebCrawler, and AltaVista). We used to think the key to discovering information was a vast interconnected web of hyperlinks (viz. the Hypermedia Era of the mid 90s). Or carefully organized TOCs. All of these strategies relied on teams of people trained in technical communication. In other words, major overhead for content that required a lot of slogging through.

A strange thing about technology is that we tend to see the current model as Shiny, even when it isn't even very efficient. Brick-sized cell phones were cumbersome, but the advantage of calling from the road was attractive. Massive web directories like Yahoo were likewise cumbersome to maintain and use, but we clicked through blindly because that was the way to find stuff on the web. So when efficient search engines came along, the Shine immediately faded from the directory sites.

What never changes is perceived value. Readers have always wanted to get directly to the answer they need at that moment. Content that provides a better way to do that is attractive and valuable.

Content is never going away, but the definition of critical, valuable content has changed. It must directly enable the customer to use the product now and quicken adoption. For example, a classic question in designing doc sets has always been, what's the first thing the reader needs to see?

It's been well known the first thing developers like to do when they download an SDK is to run the sample app and tinker with the source code. Thus the focus of "Getting Started" content has shifted from the general (conceptual overviews or development scenarios), to the specific: step-by-step procedures, including code, that when followed, actually build sample apps.

This is the revolution in content. Modern developer content must be text and code that shows a reader how to create and run a meaningfully functional application.

So what does this mean for a programmer/writer? What core skills do you need to create this new kind of content? Let's break down the definition of modern developer content:

• It must be code-rich. It might be a demo app. It might be text with example code. It might be procedural text that shows a reader how to build a sample app or perform a meaningful task. Whatever it is, it will need to provide code and show by example.


• It must be meaningfully functional. Whatever form it takes, the sample or procedure must work and demonstrate a task or procedure useful to the reader. You must show how to deploy and run it. It's not a proof of concept nor just a Hello World; it must target scenarios that are useful to customers.


• It must be contextual and scenario-based. It doesn't help readers simply to upload a demo app or sample code with no explanation, nor are how-to articles with no background. You owe it to the reader to explain why this scenario is useful in the framework of the product.


• Ideally, it should be end-to-end, meaning it provides complete setup and follow up. You need to consider all the setup steps and prerequisites, as well as any follow-up steps necessary for the sample to work. Run it yourself, as many times as necessary, and provide clear direction on each step. Customers are alienated by vague or missing directions, or omission of configuration or installations needed to make the sample work.

The standard for writing modern developer content is higher then before, and your skills will need to rise to meet the bar. But because modern content enables customers to use a product and quickens adoption, it's a provably valuable part of the business. By writing modern content, you become a critical part of your company and less of a commodity.

In times when many roles seem expendable, you need to become indispensable.

Role (R)evolution I: PMs & PWs

In the last several years the job descriptions for program managers (PMs) and programmer writers (PWs) at Microsoft has blurred significantly. The set of technical skills and responsibilities for PWs now overlaps many of those for PMs. This is happening due to a change in business needs that affects how you as a technical writer or project manager, train, work, and market yourself.

Before going on, I should define what I mean by these job titles, since they're largely specific to the Puget Sound tech community: Microsoft, and by extension Amazon, which has inherited Microsoft culture through its hires. These terms are less often used in the Silicon Valley sphere, although understood, and not at all used in the Eastern US tech community. At Microsoft, a Program Manager is a project manager in charge of a feature set or product. A Programmer Writer is a technical writer who writes content for a software developer audience. It's important to keep these definitions in mind as we examine how they're changing.

Let's look at PM and PW responsibilities as they stand now:

• Content: PMs' primary responsibility is engaging with customers through writing and speech--blog posts, demo code, and presentations (live and video). PWs still primarily write, but the focus is on code rich content, which is procedural text with code examples, procedures that build a sample app, or demo code. The big clue here is the emergent new title for PWs at Microsoft: Content Developers.

• Publication/presentation: However, the publication venues are different. PMs publish on product blogs and present video via Channel 9 and attend tech conferences, while PWs still publish content via MSDN and the various "developer centers" for each product.

• Code: Both disciplines work on demo and sample code. Another relatively new job role is figuring out how to use third-party tools with native products. For example, developing Azure SDK for Java apps (i.e. Java apps that access Azure cloud services) using a third party IDE like Eclipse or JBoss. Then deploying them using Kudu. This is the personal experience of other PMs and PWs I know, and mine as well.

• Project management: Managing project backlogs has become secondary for PMs, as each team--Dev, Test, Doc--are expected to be "self-managing" so they can focus on strategy and communication. Usually they do their own project management via scrums. This seems more like how it's done at Google, although the latter's workflow is far less hierarchically structured than Microsoft.

This has deep implications for how PWs need to train and market themselves. PWs were always expected to interview SMEs, mine source code, test code, or technical specs for the information they needed. These are still skills we use to fill in the big picture.

Now, however, PWs need to think more like PMs in that we're expected to assess the customer's need for information, estimate the return on time investment, and engage with community (through research or feedback).

It has often seemed to me that we writers have lectured customers with conceptual mumbo-jumbo or thrown often vague instructions at them for tasks they might not even care about. Rather we should be writing as one person to another, as a peer who has already struggled with a task, and so can clearly define the problem, then show how to solve it.

This really was the right way to do things all along. And it's not only the right way, I'm enjoying my work more than ever.

Creating Certificates for Cloud Apps

In years past, technical documentation would often brush off important steps in building a web app--for example, how to authenticate. The docs would simply say that it was an implementation detail that you know how to do anyway, so it was out of scope for the discussion. That may be, but it would have been nice to link to a simple hot-to. Recently I've been advocating for this kind of completeness of explanation for every step along the way in procedures and demos.

A common way to do authentication is to create and use a certificate. In this post we'll demonstrate creating and using a management certificate to authenticate with an Azure subscription.

Create a certificate for Azure using makecert

The Azure SDK for Java uses management certificates to authenticate with Azure subscriptions. These are X.509 v3 certificates you use to authenticate a client application that uses the Service Management API to act on behalf of the subscription owner to manage subscription resources.

The website creation code in this procedure uses a self-signed certificate to authenticate with Azure. For this procedure, you need to create a certificate and upload it to the Azure Management Portal (AMP) beforehand. This involves the following steps:

• Generate a certificate (CER file).
• Upload the CER file to your Azure subscription.
• Locally save the PFX file representing your client certificate.
• Convert the PFX file into JKS, because Java uses that format to authenticate via certificates.
• Write the application's authentication code, which refers to the path of the local JKS file.

When you complete this procedure, the CER certificate will reside in your Azure subscription and the JKS certificate will reside on your local drive. For more info on certificates, see Create and Upload a Management Certificate for Azure.

Create a certificate

To create your own self-signed certificate, open a Visual Studio command prompt as an administrator, cd to a directory in which you want to store certificates (such as C:\Certificates), and run the following command:

makecert -sky exchange -r -n "CN=<certificate_name>" -pe -a sha1 -len 2048 -ss My "<certificate_name>.cer"

For more info, see Create and Upload a Management Certificate for Azure.

Upload the certificate

To upload a certificate to Azure, go to the Settings page in the Azure Management Portal, then click the Management Certificates tab. Click Upload at the bottom of the page and browse to the location of the CER file you created.

Export the certificate as a PFX file

Next, export the certificate as a PFX file using the Certificate Manager (certmgr.msc):

1. Open the Certificate Manager snap-in for the management console by typing certmgr.msc in the Start menu textbox. (Or create a shortcut to C:\Windows\System32\certmgr.msc.)
2. You should see the certificate listed under Personal > Certificates. When makecert creates a certificate, it also registers it in the Personal Certificates store. If your certificate is not listed, import your X.509 certificate.
3. Export the certificate by right-clicking the certificate in the right pane, and selecting All Tasks > Export.
4. In the Certificate Export Wizard, on the first page, click Next; on the second page, select Yes, export the private key; on the third page, select Personal Information Exchange - PKCS #12 (.PFX) and Include all certificates in the certification path if possible; on the fourth page, click Password and provide a password; on the fifth page, specify the full path to the PFX file that the wizard will export. Click Next.
5. Click Finish to generate the PFX file.

For more information, see Create a Service Certificate for Azure.

Convert the PFX file into JKS

In the Windows Command Prompt (running as admin), cd to the directory containing the certificates and run the following command, where <JavaDir> is the directory in which you installed Java on your computer:

c:\<JavaDir>\jdk1.8.0_11\bin\keytool.exe -importkeystore 
-srckeystore c:\certificates\<CertificateName>.pfx 
-destkeystore c:\certificates\<CertificateName>.jks 
-srcstoretype pkcs12 -deststoretype JKS

When prompted, enter the destination keystore password; this will be the password for the JKS file. When prompted, enter the source keystore password; this is the password you specified for the PKS file. The two passwords don't have to be the same.

Note that the computer on which you run this command must have the JDK installed. Also, the path to the keytool depends on the location in which you install the JDK. For more information, see Key and Certificate Management Tool in the Java online docs.

Create a certificate for Azure using keytool

The Azure SDK for Java uses management certificates to authenticate with Azure subscriptions. These are X.509 v3 certificates you use to authenticate a client application that uses the Service Management API to act on behalf of the subscription owner to manage subscription resources.

The website creation code in this procedure uses a self-signed certificate to authenticate with Azure. For this procedure, you need to create a certificate and upload it to the Azure Management Portal (AMP) beforehand. This involves the following steps:

• Generate a PFX file representing your client certificate and save it locally.
• Generate a management certificate (CER file) from the PFX file.
• Upload the CER file to your Azure subscription.
• Convert the PFX file into JKS, because Java uses that format to authenticate using certificates.
• Write the application's authentication code, which refers to the local JKS file.


When you complete this procedure, the CER certificate will reside in your Azure subscription and the JKS certificate will reside on your local drive. For more info on management certificates, see Create and Upload a Management Certificate for Azure.

Create a certificate

To create your own self-signed certificate, open a command console on your operating system and run the following commands.

Note:  The computer on which you run this command must have the JDK installed. Also, the path to the keytool depends on the location in which you install the JDK. For more information, see Key and Certificate Management Tool (keytool) in the Java online docs.

To create the .pfx file:

<java-install-dir>/bin/keytool -genkey -alias AzureRemoteAccess

 -keystore <cert-store-dir>/<cert-file-name>.pfx -storepass <password>

 -validity 3650 -keyalg RSA -keysize 2048 -storetype pkcs12

 -dname "CN=Self Signed Certificate 20141118170652"

To create the .cer file:

<java-install-dir>/bin/keytool -export -alias AzureRemoteAccess

 -storetype pkcs12 -keystore <cert-store-dir>/<cert-file-name>.pfx

 -storepass <password> -rfc -file <cert-store-dir>/<cert-file-name>.cer

where:

<java-install-dir> is the path to the directory in which you installed Java.

<alias> is the keystore entry identifier.

<cert-store-dir> is the path to the directory in which you want to store certificates (for example C:/Certificates).

<cert-file-name> is the name of the certificate file (for example AzureWebDemoCert).

<password> is the password you choose to protect the certificate; it must be at least 6 characters long. You can enter no password, although this is not recommended.

<dname> is the X.500 Distinguished Name to be associated with alias, and is used as the issuer and subject fields in the self-signed certificate.

For more info, see Create and Upload a Management Certificate for Azure.

Upload the certificate

To upload a self-signed certificate to Azure, go to the Settings page in the Azure Management Portal, then click the Management Certificates tab. Click Upload at the bottom of the page and navigate to the location of the CER file you created.

Convert the PFX file into JKS

In the Windows Command Prompt (running as admin), cd to the directory containing the certificates and run the following command, where <java-install-dir> is the directory in which you installed Java on your computer:

<java-install-dir>/bin/keytool.exe -importkeystore

 -srckeystore <cert-store-dir>/<cert-file-name>.pfx

 -destkeystore <cert-store-dir>/<cert-file-name>.jks

 -srcstoretype pkcs12 -deststoretype JKS

1. When prompted, enter the destination keystore password; this will be the password for the JKS file.
2. When prompted, enter the source keystore password; this is the password you specified for the PFX file.

The two passwords don't have to be the same. You can enter no password, although this is not recommended.

Idempotence

Idempotence. The subtle killer. The heartbreak. The agony. But it's not what you think.

It's a painfully simple principle that sounds, on its face, like no more than common sense. Like a health problem, it can be the source of a lot of pain, if ignored. And yet some web services violate it.

An idempotent operation is one that can be executed multiple times without changing the result of the initial execution. Examples of idempotent mathematical operations would be x * 0 = 0, or |(|x|)| = |x|.

It seems rather obvious that a read-only RESTful web service request should behave in a similar fashion. For example, if you went to an ATM and requested a balance inquiry, you wouldn't expect the inquiry to change any data in your account. In RESTful Web services: The basics, Alex Rodriguez maintains that REST APIs that use an HTTP method inappropriate for their intended purpose constitutes poor design.

By "the intended purpose" Rodriguez means the appropriate CRUD operation effected by each HTTP method:

• POST creates a resource.
• GET retrieves a resource.
• PUT updates a resource, that is, changes its state.
• DELETE removes or deletes a resource.

We expect GET to be read-only and therefore idempotent. That is, it only retrieves resource data and never changes it. To be clear, "resource data" means data stored and maintained by a web service, for example, contact information stored in a database. It doesn't mean metadata--data used only by the web service to operate--for example, a counter that tracks how many times a resource was viewed, or the timestamp when the resource was last accessed. GET could change metadata and still be considered idempotent with respect to the underlying resources.

GET is meant to retrieve resource data, not to create objects or change their state. Here are a few ways in which it could be abused:

Abusing GET for POST

It's hard to imagine why someone would use GET to create a new resource--after all, that's what POST is for. But you could do it with a request like this:

GET /addressbook/contact?first_name=Arthur HTTP/1.1

An unintended consequence could be that someone would invoke this request thinking that it will query the database and return the contact record(s) having the first name 'Arthur'. Instead, the service will create a new record for 'Arthur'.

Instead of using GET to create a record, the appropriate request would use POST to send the data in the request body:

POST /addressbook HTTP/1.1
Host: address_server< ?xml version="1.0"?>
  <contact>
    <first_name>Arthur</first_name>
  </contact>

Abusing GET for PUT

You could also use GET to update an existing record--which you really should do using PUT. But let's look at how you might make the request with GET:

GET /addressbook/contact?first_name=Arthur&new_first_name=Michael HTTP/1.1

This looks like a strange GET request, but you might expect it to retrieve a record with fields matching the strings 'Arthur' and 'Michael'.

Instead of using GET to update a record, the appropriate request would use PUT to send the new data in the request body:

PUT /addressbook/Arthur HTTP/1.1
Host: address_server<?xml version="1.0"?>
  <contact>
    <first_name>Michael</first_name>
  </contact>

Heresy and bad practice

Such unorthodox uses of HTTP requests constitute bad practice in the following ways:

• They violate idempotence. You should be able to call GET an unlimited number of times, and expect that no record data will ever be changed.
• They present misleading expectations. If you make a GET request, you expect it only to retrieve data without changing the state of the data. Creating a record or updating a record is not the expected function of a GET request.
• They pass data as parameters instead of as structured data, which is a major advantage of REST. The above case uses GET to update an existing record uses REST in an almost SOAP-like manner, by passing data via parameters. Passing data in this way might be appropriate for some applications, such as query parameters in search engines, but it's a problem with hierarchically structured data. Instead, you should pass structured data (such as XML or JSON) in the request body of a POST or PUT method.

But there are cases where you might not use the "appropriate" HTTP method for its intended function. I've seen this implemented in a few APIs. You can use POST to initiate a state-changing operation. I'm not a fan of doing this. Yes, it can work if implemented carefully. Perhaps I'm a purist, but it breaks the integrity of the intended use of each HTTP method for its intended CRUD operation. However, this implementation makes sense if:

• You intend to create a unique new object each time POST is called, or
• You know that the service will only be called once for each set of data sent in the request.

For example, you might have a service that authenticates a user, then sends the user a one-time passcode (nonce). Any objects that you might have created are discarded. In this case, POST would make sense, because it created "virtual" resource data that was created and deleted in the process.

The Man from C.R.U.D.

While there are strong arguments for making it a best practice to hew to the "intended purpose" of the HTTP methods for each CRUD operation, inflexibly insisting on such rigidity might earn you the moniker "The Man from C.R.U.D." I believe there are exceptional cases that are sound implementations that are possibly even more appropriate than the orthodox usage.

The guidelines are reasonable and clear: never implement methods in a way that their expected use might be misinterpreted, and certainly never implement requests that alter resource data where idempotence is expected.