Search code examples
resthttpapi-design

Creating best API: Upload N files and json metadata

I am creating an API.

I am unsure what the API should look like.

Several BLOB files (PDF, JPG, ZIP, ...) should get uploaded and some JSON which contains meta data.

What is the most up-to-date way to design the API?

There are two cases:

  • the upload was successful. Then I think 201 (created) would be feasible
  • the upload was not successful (for example invalid meta data). Then 422 (Unprocessable Entity) should get returned.

Example:

  • Three pdf-files should get uploaded (at once) associated with some json meta data.
Solution

  • What you often see is that you have a resource for handling the BLOBs and one for the meta-data - Facebook and Twitter is doing this for images and videos.

    For example /files would take your BLOB data and return an ID for the uploaded BLOB data.

    The metadata would be send to another resource, called /posts and could consume application/json.

    In the application I currently work for, we had the same issue and decided to use one endpoint consuming multipart/form-data - here you can send the BLOBs and the metadata within different boundaries and have everything in one resource.

    Another way would be to base64 encode the BLOBs, which will result in an 33 % overhead, and I therefore not recommend it. But with base64 you could do all your work in one application/json resource.