DELETE endpoints for the whole spec

[BrapiCoordinatorSelby]

Create a way to delete entities via the API.

** Remember this is a REQUEST to delete entities, a server can handle it however it wants to. There is no expectation that anything will be permanently deleted out of a database. **

See POST /delete/observations and POST /delete/images for potential examples

[daveneti]

Adding delete endpoints is a simple one line configuration change in the Specification generator:

[dmeidlin]

After looking over the POST-based batch delete specification for observations and images, and after considering the risks and benefits of either a POST-based or DELETE-based specification for processing batch deletion, a DELETE-based specification is more favorable especially when considering the roles of intermediary servers in a production environment. Also, full CRUD operations would be necessary for the client to create a batch for deletion, review the batch, make any changes to the batch, and finally delete the batch. Here is an outline of the main points.

Production Considerations that Favor POST over DELETE

• URL exposure: With DELETE, the resource identifier is typically in the URL, which may be logged or visible in browser history. POST allows sending identifiers in the request body, providing slightly more privacy.
• Browser support: Some older browsers or network equipment may not fully support DELETE, potentially leading to unexpected behavior. POST is universally supported.
• Method override issues: Some older proxies or firewalls only support GET and POST. While DELETE usually works fine, in rare cases it might be blocked or mishandled.

Production Considerations that Favor DELETE over POST

Developers

• CSRF protection: DELETE requests are typically not vulnerable to Cross-Site Request Forgery (CSRF) attacks, as browsers don't allow cross-origin DELETE requests without proper CORS headers. POST requests, however, are more susceptible to CSRF and require additional protection measures like CSRF tokens.
• Accidental execution: DELETE semantics make it clear that a resource is being removed. Using POST for deletion could potentially lead to confusion or accidental execution if not clearly documented.

Intermediary Servers (load balancers, API Gateways, reverse proxies, WAFs, caches, etc.)

• Caching: DELETE requests are not typically cached by intermediaries, while POST requests may be cached under certain circumstances. This could lead to unexpected behavior if caching is not properly managed for POST-based delete operations.
• Proxy handling: Some proxies or firewalls might be configured to handle DELETE and POST requests differently. They may block or modify POST requests more aggressively, potentially interfering with the delete operation.
• Load balancing: Some load balancers or API gateways might route DELETE and POST requests differently. This could result in requests being directed to different server instances, potentially causing consistency issues.
• Idempotency assumptions: Intermediaries and networking equipment often assume DELETE requests are idempotent and may retry them automatically in case of network errors. POST requests are not assumed to be idempotent, so automatic retries are less likely, potentially leading to incomplete operations in case of network issues.
• Content filtering: Some content filtering systems (e.g., in corporate networks) might have stricter rules for POST requests, potentially blocking or altering the delete payload.

Automated Deployment/DevOps Services

• Logging and monitoring: Network monitoring tools often treat POST and DELETE requests differently. Using POST for deletions might lead to misleading logs or statistics about API usage.
• HTTP acceleration: Certain HTTP acceleration techniques used by ISPs or CDNs might behave differently for POST and DELETE, potentially affecting performance or reliability.

Required Features for Batch Delete

Considerations for Batch Delete

• The client will need a preview prior to deletion.
• A concurrency check may be necessary for batch deletions, flagging any entities in the deletion request that have been mutated by another user in the interim.

Considerations for POST-based

• Implement additional security measures such as CSRF tokens for POST-based delete.
• Use appropriate cache control headers for POST-based delete.

Post-based and DELETE-based

• The same additional server-side features are needed to handle exceptions for DELETE-based batch deletions as are needed to ensure idempotency for all POST-based deletions.
• Implement proper authentication and authorization for both methods.
• Use HTTPS to encrypt all traffic.
• Clearly document API behavior, especially if using POST for deletions.
• Implement robust error handling and logging.

DELETE-based Implementation

The risk of unintended consequences when intermediary servers handle deletions with POST request favors implementing batch deletions using a DELETE endpoint specifically for deleting a collection of BrAPI entities. The client will generally need all CRUD operations for processing batch deletions:

• POST /delete/batch: The request is similar as the current POST /delete/observations where the body contains a <BrAPIVariable>SearchRequest object, but instead of carrying out the deletion operation it creates a collection of <BrAPIVariable> for deletion and responds with either a just DeletionCollectionDbId or with a DeletionCollectionDbId and the collection itself.
• GET /delete/batch/<deletionCollectionDbId>: The current contents of the deletion collection are returned either for getting the results of the original POST as in a search request, or the client wants to review the current contents of the deletion collection.
• PUT /delete/batch/<deletionCollectionDbId>: The request body contains a JSON object of key-value pairs where the key is a <BrAPIVariable>DbId and value is a boolean flag to add/remove the entity from the deletion collection. This enables the client to make any changes after the review but prior to deletion. The response contains the state of the deletion collection after the update.
• DELETE /delete/batch/<deletionCollectionDbId>: The entities in the deletion collection are deleted and the response contains an instance of <BrAPIVariable>DeleteResponse containing the unique ids of the <BrAPIVariable> entities that were successfully deleted.

Each BrAPI variable would need a DELETE endpoint for deleting a single instance of the BrAPI variable.

• DELETE /<BrAPIVariable>/<BrAPIVariableDbId>: It responds with the entity that was successfully deleted.