PutCursorAsync is deprecated in ArangoDB 3.7

[DiscoPYF]

Endpoint PUT /_api/cursor/{cursor-identifier} (PutCursorAsync.PutCursorAsync) is deprecated in ArangoDB 3.7 in favor of a new endpoint POST /_api/cursor/{cursor-identifier}.

https://www.arangodb.com/docs/3.7/http/aql-query-cursor-accessing-cursors.html#read-next-batch-from-cursor-deprecated

It is likely that the endpoint will be removed in a future version, so we should make the change at some point.

We could:

• Create a new endpoint method, e.g. PostExistingCursor
• Add another method overload to PostCursorAsync though it may not be very clear from a consumer point of view

There is also the question of compatibility with previous ArangoDB version. It might be a good idea to keep PutCursorAsync and mark it as "up to ArangoDB 3.6".

[rossmills99]

I like your idea to add PostExistingCursorAsync method and leave the existing PutCursorAsync, but mark it as deprecated.

This is an example of where our decision to stay close to the underlying REST implementation is possibly annoying - if we had a method named "ReadNextCursorBatch" or something, then we could change the underlying implementation from PUT -> POST without needing to change our public API. I'm only mentioning it as a point of interest - not suggesting we change our approach :).

At least by preserving both methods we provide clients the ability to continue supporting ArangoDB 3.6.

[rashtao]

Consider that removing PUT /_api/cursor/{cursor-identifier} from the server-side API is a breaking change, which as of now is going to happen in ArangoDB 4.0, potentially together with others API breaking changes.
The main reason for deprecating it now is because it does not fully honor the HTTP specification with respect to idempotency (https://tools.ietf.org/html/rfc7231#section-4.2). According to the HTTP specification GET, HEAD, OPTIONS, TRACE, PUT and DELETE requests should be idempotent, so they must behave according to the following definition:

A request method is considered "idempotent" if the intended effect on
the server of multiple identical requests with that method is the
same as the effect for a single such request.

If you keep using it, please make sure that the HTTP client used by this driver does not retry automatically failing requests to this url path.

[DiscoPYF]

This change is also mentioned in "API changes in 3.8": https://www.arangodb.com/docs/stable/release-notes-api-changes38.html#endpoints-added

The cursor API endpoint PUT /_api/cursor/ to retrieve more data from an existing AQL query cursor is now also available under POST /_api/cursor/.

The new POST API is a drop-in replacement for the existing PUT API and functionally equivalent to it. The benefit of using the POST API is that HTTP POST requests will not be considered as idempotent, so proxies may not retry them if they fail. This was the case with the existing PUT API, as HTTP PUT requests can be considered idempotent according to the HTTP specification.

The POST API is not yet used by ArangoDB 3.8, including the web UI and the client tools. This is to ensure the compatibility of 3.8 with earlier versions, which may be in use during upgrade to 3.8, or with one of the 3.8 client tools. The PUT API will remain fully functional in this version of ArangoDB and the next. The following version of ArangoDB will switch to using the POST variant instead of the PUT for its own requests, including web UI and client tools. Driver maintainers should eventually move to the POST variant of the cursor API as well. This is safe for drivers targeting 3.8 or higher.

[tjoubert]

Solved by #396

[DiscoPYF]

@tjoubert #396 only deprecates PutCursorAsync but doesn't provide an alternative implementation. We should also provide a replacement method beforing considering this issue resolved so I'm reopening.