Bulk Synchronous Standards

[travisgosselin]

Proposal of new API Standards for bulk operations that attempt to provide some consistency with a RESTful approach. That being said there are many compromises here. This content covers concepts around Synchronous bulk operations to a single resource.

Bulk operations to multiple resources is out of scope, along with async bulk operations and async in general. That being said, schema for bulk operations should be reviewed and considered for consistency in future standards around async and schema.

[travisgosselin]

• This approach places the emphasis on supportin bulk operations for a single resource. Bulk operations may still be desirable at a larger network level across resources... and having a distinct resource for that would make sense as an API that supports providing batch support across many resources (proxy) - out of scope for this update:

POST network.api.spscommerce.com/v1/batch
{
    "operations": [
        {
            "method": "POST",
            "path": "/my-resource",
            "body": {
                "company": {
                    "id": 1234
                },
                "name": "Receiver Profile Name"
            },
            "result_placeholder": "${receiverPlaceholder}"
        }
}

• Additionally, this specifies that it is for Synchronous handling of bulk updates. Async handling would require the use of a status monitor pattern potentially and may mean a new resource entirely for async bulk updates, such as an "import" endpoint: network.api.spscommerce.com/v1/resource-import. More details on async discussion will inform the approach to this. This draft is NOT ready for review just yet: Async Polling Standards #70

[brandonsahadeo]

Generally, looks pretty good to me 👍🏼

[travisgosselin]

Rough notes from our zoom meeting about this, thanks for everyone who participated:

- not idempotent
- patch atomicity - should we add an option in the request body to indicate if its all a single transaction or not?
	- we are ok with allowing partial updates given the lack of consistency in PATCH
	- lets move ahead with a proposed request parameter for transactions...? - have this but make it optional and provide a default
	- transactionality across requests (pages of patch)? - out of scope.
- response body is extendable?
	- NO need, and not ideal (for now)
- schema changes:
	{
		operationId:
		action: 
		entityId:
		entityRef:
		status:
		detail: {} extensible object?
			- define a better object here that can provide errors and details
	}

- ordinal? identifying response objects
	- ordinal should be "operationId"
	- operationId can be provided as a string on request (optional)
	- if not provided the response includes the index of the item from the original request

- multiple items in same PATCH for the same id
	- allow this, but indicate expectation for etag usage
	- suggestion on operationId usage in this regard (given the same id can appear twice)

- are enum actions and status extensible?
	- easy to make extensible later, not now

- Retreival? FETCH
	- different use case, to be excluded

- Etag Usage?
	-  no concerns here
	- response can return etags on each object
		- consistent with how we handle this today with individual objects.

I'll convert to Draft for now until updates are made in accordance with the above notes.