I am currently working at a requirement, where we receive files to process from a website including some metadata such as (Name, App_ID, ...).
The metadata structure will always be the same. In order to use a single http post method to post the files to our system we send any metadata as parameter in the request.
I am just not sure whether or not this is accepted following the restful approach, using HTTP.
An example request:
www.example.com/api/v1/some_data/docs?name=someName&App_ID=021540464&...
Is this design allowed? If not any other suggestions to handle this in a single request?
other suggestions to handle this in a single request?
Think about how you would do this on the web.
You would load a web page with an HTML form. The form would have a number of general purpose input controls. One of those would allow the user to specify the file to upload, but others could be used to allow the user to provide additional data about the file.
When the user submits the form, the browser would apply HTML's general purpose form processing rules; the data provided by the user, and the metadata about the form itself (as provided by the server) would be combined to create an HTTP request - the end result of this being a POST request with multipart/form-data and the target-uri of the request being whatever the server specified as the form action.
So all of the information collected from the user, including the file itself, would be in the message-body of the request.
Is it OK to encode (some of) the client provided metadata into the target-uri, rather than putting all of it in the request body? Yes, from the perspective of HTTP -- the hard work comes in trying to design a protocol that a general purpose client can understand.
On the web, for instance, we could possibly do the work with two forms -- the first form collecting the URI data, and producing a get request to the server, asking for the second form. The server can then send back a representation of the second form with all of meta data correctly encoded into the form action URI, presenting the same input controls for specifying the body of the POST request.
But HTML doesn't give us the piece that we need to do the work with one form -- we don't have the vocabulary in HTML form processing to say "put this data in the URI, put that data in the body".
The thing that we would really want is a media type that allows us to use a URI Template to describe the target of the POST request.
If you are using your own bespoke media types (application/prs.marc+json ?), then you can potentially put into your own message processing "this is a template, here's the data you use to fill it in, then use that for a POST Request".
If you aren't trying to do hypermedia at all, well then its even easier - you just document the template, etc in your API documentation, and everybody that is writing a bespoke client to talk to your API can read what to do.