Best practice to design API to upload a document with Meta Data information...

Hi,

I need to develop a rest API to allow user to upload a file with meta data information. the metadata has around 15 fields. I am using form-data to let user upload the file and meta data as json string.

It doesn't look good since the meta data object schema can't be published on Apigee developer portal.

what is the best practice to design such an API?

Surabhi

0 4 5,944
4 REPLIES 4

Not applicable

Hi @Surabhi.gupta, Did you check this https://github.com/apigeecs/smartdocs_service?

You can create models and import an Open API (JSON or YAML) file to a model.

Why not ask your user/who-ever wants to upload a spec to POST the spec and you can use the above APIs in the background?

hi @Maruti Chand,

I think i wasn't clear in my question. I need to write a REST API for users to upload documents to our internal database. The user needs to provide Meta Data (around 15 fields) about the file he is uploading along with binary,

What's the best way to design such Rest API?

Not applicable

You have a couple of options to consider:

  1. Use multipart/form-data to submit meta data and contents in one go.
  2. Use a standard JSON or XML payload requiring the consumer to appropriately encode the data first. As an affordance to the consumer you can support an optional field for the URL (publicly accessible) that resolves to the file to be uploaded in your request definition and allow the backing service implementation to resolve the file.
  3. Break the transaction into two components. The first is the POST which takes the metadata as JSON or XML and returns an entity identifier then a subsequent multipart/form-data PUT which includes the file contents.

Personally I prefer option 2. This does place the onus on the consuming application to encode the binary/file data in a prescribed format. If your consumers are predominantly browser based, then you may need to allow for option 3.

Thanks for replying @Dallen. I am inclined to use option #1. I am passing file's metadata as JSON object as first content and second content is binary.

It seems to be working. But I am not sure how to document it in swagger. The first field shows up as text field in swagger editor as well as in smart doc on developer portal. and I couldn't find a way to describe the schema of JSON object either.

Any solution for that?