Placing data on the I2E Server: POST or PUT?

October 30 2013

The past few weeks have been busy: we’re fresh from our Text Mining Summit, which included a dedicated training session for users who wished to develop against the I2E Web Services API.

I also had the opportunity to go on site to a customer to provide some focused API training.

These sessions generated lots of interesting questions about automating processes from an administration perspective as well as a user perspective.

As I was presenting some high-level slides during the Text Mining Summit, I noted that I was mixing up put and post (and sometimes place and push!) in a way that is forgivable when using them as English verbs, but unhelpful when trying to explain a RESTful Web Service.

So after the Summit, I went back to our Developers Guide and back to my notes and started over, to create a helpful explanation of when you POST and when you PUT to the I2E Server.

Both PUT and POST are methods to transfer data to the server and there are some use cases when they can be used interchangeably.

One example of that is creating a new file called newfile.txt in the Source Data collection on the I2E server:

PUT url=http://i2eserver:8334/api;type=data/newfile.txt data=filecontent

POST url=http://i2eserver:8334/api;type=data/?base=newfile.txt data=filecontent
 

The end result will be the same in either case, but as you can see from the URL, the resource name is set differently:

With the PUT, you are asserting that newfile.txt will be the name, i.e. the client application has naming rights
With the POST, you are hinting (with base=filestem.extension) that newfile.txt will be the name, i.e. the server has naming rights
 

This difference becomes apparent when you perform the request again:

With the PUT, the file is still called newfile.txt: you have updated (or overwritten) the existing file
With the POST, the file is on the server as newfile (2).txt: you have created a new file
 

To find out what the server has done in these two cases, you should inspect the HTTP status code as well as response:

If a file has been created, using either PUT or POST, the HTTP status code will be 201 and the response body will contain a URI for that resource.

If a file has been updated using PUT (you cannot, of course, update a resource with POST), the HTTP status code will be 200 and there will be an empty response body.
 

One final note: if you try to POST to a specific resource:

POST url=http://i2eserver:8334/api;type=data/newfile.txt data=filecontent
 

The I2E server will respond with a 405 code to “gently” remind you that this is an inappropriate request.

I hope that this is a clear explanation of how the I2E server treats PUT and POST. There is also more information available in the I2E WSAPI Developers Guide, but if you still have questions, please contact i2esupport@linguamatics.com