I'm building an API that, among other things, will allow the consumer to create a record. That record can have an array of images (passed as URLs). Assume that the consumer passes an array of image URLs, but some return a 404, exceeds a file size limit, etc. -- what should the API do? I see two possible options:

  1. Fail. Report back to the consumer on the first sign of trouble.
  2. Create the record anyway, skipping the invalid URLs and just report back to the consumer which image URLs failed and why.

I'm trying to use JSON API for my request and response format. Per the spec, it says that:

The members data and errors MUST NOT coexist in the same document.


This would suggest that my option #2 is a no-go. Thoughts?

  • Are you doing that yourself, or is it a task given by a project manager , If the latter, ask to him. – Walfrat Jun 22 '17 at 13:40
  • 1
    Why not reject the entire request to post the record if anything about the record can't be processed for any reason, and return http error 400 to the client? – Thomas Carlisle Jun 22 '17 at 14:03
  • Yes, that's an option. Just wondering if the API should be forgiving. – ProgrammerNewbie Jun 22 '17 at 14:24

Yers, I guess that option #2 is not possible in JsonAPI.

BTW, your question looks related to the notion of ACID-ity in databases.

You did not tell what kind of record-s you are creating. I would however suggest to avoid creating an "incomplete" record.

OTOH, you might consider creating a record and in addition adding various related data giving the failed images URL.

The point is what would you (or later users of your API) do with such "incomplete" records? Or you might extend your API to not only "create" records but also "complete" records with additional (yet ungiven) data. Then the "create" request would return e.g. a set of invalid images, etc...

In other words, is the case of missing images URL an exceptional situation, or is it something "normal"? If it is a normal situation, you should design the API to handle it (as a success).

Notice also that an URL can be temporarily "wrong" (e.g. because the web server providing that image is temporarily out of order, but might work tomorrow)

(your question is IMHO too broad)

| improve this answer | |
  • The record can exist without any images as they are optional. However, from the consumer's perspective, he/she may consider it "incomplete" (e.g. maybe they really really want to have all those images. I'm leaning towards a less forgiving approach to the API. If it's that important to the consumer that all images be part of the record, then the consumer needs to double check the input before calling the API. Just wondering if that's the right attitude to have. – ProgrammerNewbie Jun 22 '17 at 14:04

Why the array? Have your API handle one image at the time and throw like a pro if the image cannot be retrieved.

| improve this answer | |

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.