POST creating multiple resources from non-JSON:API payload

I’m working on an application where a user can provide an export from another application and create / update several resources. Consider uploading an address book in vCard format: There might be several entries (individual vCards), some of which represent new resources and some represent updates to existing resources. The request body might be any of

  • text/vcard
  • application/vcard+json
  • application/vcard+xml

Is there a good way to respond to such a request in JSON:API, or does the response need to be strictly outside the JSON:API model?


Two questions:

  • Is the client able to encapsulate the payload on a JSON:API request?
  • Does the client wish to do multiple operations to multiple resources (and resource types) ​in a single request?

I’m also interested in this use case, and I think JSON:API could provide at least some guidelines on how to deal with it.

I’m not sure encapsulating within a JSON:API request would make sense. If the client has a vCard / xCard / jCard representation of an address book with multiple entries, what’s the right request to make? What I’d like to avoid is putting the intelligence for interpreting the address book in the client; it might not even be aware that multiple entries might be present.

I could do something like POST to create an import-task, with the text of the address book data as an attribute, but that becomes another issue as soon as I support an address book format that’s binary.

My current thought is to model individual “contacts” as resources (all of the same type, at least for now), and the service will determine which cards from an import correspond to existing contacts in the collection and which represent new contacts. Updates and creations will be applied as appropriate, and then the service tells the client… something.

The more I think about it, the more I like creating an import-task, and recording whatever makes sense on that, and allow the client to GET that to see updates on progress. It feels a little bit like overkill for small address books, but for large imports, it can make a lot of sense. It would also serve well for server-side synchronization operations (“Update contacts from this 3rd-party service”). The creation request could be a POST of address book data in vCard / xCard / jCard / csv format (with the appropriate Content-Type), or a JSON:API request.

The only way I can figure out how to do this with the specific contacts in the response really requires the client to determine what resources to update and what resources to create, which just doesn’t seem sane.