How to describe Input Parameter in a RESTful Web Service

Question

Hello, Im developeing a RESTful Service in which Processes can be executed and proivde a resulting calculation. For this i have modeled the process itself as a Resource (Example: /processes/translate). I want to execute the process by sending a GET request with appended Input Parameter as Query Parameter (Example: /processes/translate?input1=xxxx&input2=xxxxx).

Each process has different Input Parameter which are defined during the process creation in the backend. My Question is how should i document or describe which inputs are needed to execute a process in machine readable form. For Example in XML.

Until now ive integrated atom:link elements in the Representation. i thought that maybe including XFORM could be a soluttion?

Best Regards Andre

Answer 1

I would not model this with a GET. While it's the easier solution, it's also (IMO) the least RESTful. I would have clients POST a document describing what they want you to translate and your service sends them back a URI where their answer can be found (some translations might take a while).

Example (ommiting a lot of HTTP headers/context)

POST /processes/translate
Content-Type: application/xml
...

<translation-request>
   <input1 type="type1">....</input1>
   <input2 type="type5">....</input2>
</translation-request>

Response:

200 OK
Content-Location: /processes/translate/jobs/1234
.... 

Answer 2

That's always an interesting question. We have a project called RESTx (http://restx.org), with which you can create RESTful web services very easily. You can write custom component code in either Java or Python and then create RESTful resources by sending parameter sets to the server, which are then stored. Each parameter set gets its own URI, though, so you can always just run the code with those parameters by accessing the new parameter set's URI.

Importantly, the entire RESTful API, is automatically created. RESTx examines the component code and then assembles the API description. We decided to describe parameters in a way that is human as well as machine readable. You can see examples of what that looks like in a browser or in plain JSON.

I'm the lead developer on that, so please feel free to contact me about any questions you might have.