Documentation for POST API requests

[Lukas Schwab]

Hi everyone!

I maintain the arxiv PyPI package––a wrapper for the API––and a couple of personal projects built around it (e.g. arxiv-feeds, which translates query results into a JSON Feed).

Two years ago someone opened this GitHub issue re. making an API request with an unusually long id_list; a GET request receives a 414 response.

The User's Manual mentions:

The request can be made via HTTP GET, in which the parameters are encoded in the url, or via an HTTP POST in which the parameters are encoded in the HTTP request header. Most client libraries support both methods.

 And

As mentioned above, the API can be called with an HTTP request of type GET or POST. For our purposes, the main difference is that the parameters are included in the url for a GET request, but not for the POST request. Thus if the parameters list is unusually long, a POST request might be preferred.

Unfortunately, I can't get a POST request to produce anything but an empty result. No matter how I set the query parameters, they aren't reflected in the response's link field.

Is there something I'm missing? Is there a good reference client I can inspect?

Thanks for any help!

Lukas

Testing

I expect results matching those for this GET equivalent:

curl --request GET \

  --url 'http://export.arxiv.org/api/query?search_query=quantum'

Setting search_query in a POST header, as suggested by the API:

curl --request POST \

  --url http://export.arxiv.org/api/query \

  --header 'search_query: quantum'

Setting search_query in a POST body:

curl --request POST \

  --url http://export.arxiv.org/api/query \

  --header 'content-type: application/json' \

  --data '{

"search_query": "quantum"

}'

Here's an example response for the post requests:

<?xml version="1.0" encoding="UTF-8"?>

<feed

  xmlns="http://www.w3.org/2005/Atom">

  <link href="http://arxiv.org/api/query?search_query%3D%26id_list%3D%26start%3D0%26max_results%3D10" rel="self" type="application/atom+xml"/>

  <title type="html">ArXiv Query: search_query=&amp;id_list=&amp;start=0&amp;max_results=10</title>

  <id>http://arxiv.org/api/iQlyOhQ3W8t8kI903+StmrBZNWM</id>

  <updated>2020-03-29T00:00:00-04:00</updated>

  <opensearch:totalResults

    xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/">0

  </opensearch:totalResults>

  <opensearch:startIndex

    xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/">0

  </opensearch:startIndex>

  <opensearch:itemsPerPage

    xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/">10

  </opensearch:itemsPerPage>

</feed>