REST object with resources

Question

I am designing a HTTP-based REST API. Let's say I have an entity called Entity that has a bunch of properties. Some of its properties are files. Let's say Entity has following properties:

name: string
description: string
photos: array of photos
videos: array of videos

API is designed to be used from mobile devices and should work well under conditions of slow or unstable connection. The thing is the object should be not considered as complete until I upload all the resources the client have.

What it the best way to construct a new object?

---

For now I come up with the following solution. Add readiness flag isReady, first post basic object data within single json:

POST /entities/ {name: "somename", description: "description", isReady: false}
obtain id of newly created `entityId`

Then upload resources one by one:

POST /entities/{entityId}/photos/ <photo data>
POST /entities/{entityId}/videos/ <video data>

And then update object's readiness flag

PUT /entities/{entityId}/ {isReady: true}

---

The second solution that comes to mind is to create separate endpoints for photos, videos. Then I'll be able to first post photos and videos and then create Entity with references to resources.

POST /photos <photo data>
obtain ids
POST /videos <video data>
obtain ids

POST /entities/ {name: "somename", description: "description", photos: ids[], videos:ids[]}

The question with the second solution: is it okay for resource to be referenced by multiple URIs?

/entities/photos/{photoId}
/photos/{photoId}

---

Is the first solution correct? Wouldn't the second one be overcomplicated?

Thanks in advance

Answer 1

I have successfully used both patterns; and both will work fine. I wouldn't say that either is more complicated than the other. One thing that you might also consider, for the first pattern, is to include in your entity description a "promise" to fulfill. For example, you might have a JSON object that enumerates the data you'll be providing:

photos_promise: {
    expect: 5,
    checksums: [..., ..., ..., ..., ...]
}

Then, when you upload the five photos, you can do an additional validation to ensure that the photo file you've received matches one of the provided checksums. When you've received five photos and they all match, you can have the service automatically "enable" your Entity resource. You can take it a step further and have "partial states" for these objects, such that when you get this entity after having posted three photos, you'd get:

photos: [{url: ..., ...}, ...],
photos_promise: {
    received: 3,
    expect: 2,
    checksums: [..., ...] 
}

This obviously does add complication, but it's also rather elegant.