GraphQL API: mutation or query?

Question

I'm developing a GraphQL API in which there is an import feature with a preliminary data comparison (between existing data & the imported file) and a subsequent confirmation request

The current flow is:

1. The API consumer does a GQL query query previewImport($data: String) where $data is a base64-encoded spreadsheet. The data is parsed in the back-end and a record with a guid is inserted in the database. Finally the API returns a diff result between the data in the spreadsheet and the data in database, and the guid.
2. The front-end then asks the user to confirm the import after seeing the comparison (created, updated, deleted). To this end the request mutation confirmImport($guid: String) is made to the API and the changes are persisted in the database.

So I'm wondering: should previewImport be a query or a mutation ? From the API consumer's point of view, it is definitely a query. But in the back-end DB a record is inserted, albeit with the only purpose to be linked to a confirmImport request shortly thereafter, and then deleted.

In the GQL Mutation spec it is said that:

It is expected that the top level fields in a mutation operation perform side‐effects on the underlying data system.

Technically, the temp record does affect the data system. But domain-wise, it changes nothing to the entities that are important to the app so I'm still kind of in the dark

Answer 1

I agree that query previewImport is more intuitive, provided the preview operation is idempotent.

A query suggests not just "read, not write", but also "I can call this all day long without error". A mutation , on the other hand, typically persists a change and informs me if I try to repeat the same operation, either as an error or an "already processed, you idiot" response.