GET and POST Methods
When to use GET or POST methods with Haven OnDemand HTTP calls.

HTTP GET and POST Methods

You can use both HTTP GET and POST methods to run Haven OnDemand APIs, and the Try It pages available for many of the APIs will generate calls for either one.

However, although both methods take similar parameters and often overlap, they are not interchangeable. Depending on context, one or the other is preferable.

Use GET when:

  • Not uploading a file
  • Submitting a small amount of data
  • Submitting non-sensitive information

Use POST when:

  • Uploading a file
  • Submitting a large amount of data
  • Submitting sensitive information
  • Using the /1/job platform API

Use the GET Method

HTTP GET is a read-only method used to retrieve remote data. It can be used to query existing repositories, but not to upload files.

GET encodes data directly into the request URI. Because the length of a URL is necessarily limited, GET is not used for submitting large amounts of data for processing. Also, since URLs are easily intercepted or cached, Haven OnDemand recommends you avoid using GET to transmit sensitive information.

Use GET, for example, to run short searches on datasets.

Note: You can limit some of the risk of interception by using HTTPS rather than HTTP.
Although you cannot upload files with GET, you can submit, within the input URL, an object store reference or another URL, which may in turn point to a file of any size.

Use the POST Method

HTTP POST is both read and write. It allows you to insert or update remote data with material attached in the body of the call. Because sensitive data is hidden in the body and not visible in the URL, POST is more protected from interception than GET.

Use this method with any API in which you send data in a file parameter.

curl -X POST --form "file=@productbarcode258.png" --form "apikey="

Example: the Job API

The /1/job API makes a characteristic use of POST to submit a job to the server for asynchronous processing.

The job itself is a new json object that you upload with POST for parsing. It might consist of nothing more than a series of simple tasks which individually could be run with GET. But as soon as the list becomes elaborate or long, or you want to run multiple calls to the dataset as a batch, it is more convenient to encapsulate this in a job.

   "actions": [
      { "name": "analyzesentiment",
         "version": "v1", 
         "params": {
            "text": "I like cats",
      { "name": "analyzesentiment",
         "version": "v1", 
         "params": {
            "text": "I like dogs",

The job in this example is a list of two separate actions, submitted to Haven OnDemand with POST. (See also Synchronous and Asynchronous API).