I want to build a RESTFUL API.
I have a resource with task plans.
The client should request the server to run task such as benchmarking on one of the task plan metrics.
which request should be used. POST or GET?
and what should be the uri?
/api/plans/<id>/run or /api/plans/run/<id> ?
I will go for a POST and since is an action on a specific plan, the url should be plans/id?action=run.
run is not a sub collection of a plan so query param must be used in this case
GET requests are used for reading/getting data. POST requests are for creating data.
If the user just needs to see the results of a benchmark run, I would use a GET request that returns the results of the benchmark method for the plan.
For retrieving a single record, the URL convention is /things/:id, so I would recommend api/plans/:id/run. I also recommend renaming run to something more descriptive, like benchmark or metrics.
Related
In J.meter I need to test multiple web-services in single scenario like, after successful execution of service one it will gives session-Id and this session id will take by other services and check it and complete the scenario as per business logic?
It is classic question regarding "correlation" in JMeter. Correlation stands for the process of extracting dynamic data from previous response and passing it to the next request.
Add a JSON Extractor as a child of the first request and define a JSON Path query to extract the session-Id value and and store it into a Jmeter Variable.
Use the aforementioned JMeter Variable as the session-Id for the subsequent requests.
See API Testing With JMeter and the JSON Extractor article for comprehensive instructions.
I am designing a RESTful API for tests and test runs metadata. I have two resources: Test and TestRun. Under the hood they have a one-to-one relationship in the database.
First I create a Test resource by sending a POST to api/v1/test.
Then I have to start this test. I do this by sending a POST to api/v1/test/{id}/run, which creates a TestRun resource that relates to that Test resource.
Then I can also stop the test by sending a POST to api/v1/test/{id}/finish, which modifies the corresponding TestRun resource (sets some fields, like finish_time, result etc.).
The user of the API will never have GET access to TestRun resources and will only access them through their related Test resources.
While it looks like this design is quite straightforward for the API user, I doubt this is also as straightforward for a developer. Is this design I came up with good enough? Does it violate any REST principles or best practices? I would appreciate any input on this.
An extended design description of the whole API: https://gist.github.com/Ch00k/27724e29ec1bf044ebbfdabef9e842d5
Your API will not allow access to the testrun, so a testrun seems not to be a REST Resource. In fact your URLs are a mix of REST, as far as the test is concerned, and RPC, especially the /run and /finish paths.
RPC is not REST, so I would rework this a little bit:
Use only one type of resource, the test, at api/v1/test/{id}.
A test has state that can be retrievd using a GET request to api/v1/test/{id}:
status: stopped, started, finished, ...
finish_time
result
...
The state of a test is changed using a PATCH request to api/v1/test/{id} with a JSON body containing the new state: {"status": "started"} to start the test, etc. This replaces the RPC calls.
I am trying to design a RESTful api for a service that accepts a bunch of parameters and generates a large result. This is my first RESTful project. One tricky part is that the server needs some time (up to a few minutes) to generate the result. My current thought is to use POST to send in all the parameters. The server response can be a job id.
I can then retrieve the result using GET /result/{job_id}. The problem is that the result is not available for the first few minutes. Maybe I can return the resource unavailable at the beginning and the result once it is available. But this feels odd and add some odd logic in the client.
An alternative is to retrieve the job status GET /job_status/{job_id}, where the result might be running/error/done, similar to the http status code, where done status also comes with a result_id. Then I can retrieve it with GET /result/{result_id}.
Either case has some problem with what I have read about GET. In both cases, GET result is not fixed and not cacheable at the beginning while the job is still running. On the other hand, I read somewhere that it is OK to do things like GET /currentWhether or Get /currentTime, which are similar to at least my second approach. So my questions are:
Which one is better? Why?
Should I use GET for such situation?
Or neither one is OK? What would you do?
Thank you very much.
Should I use GET?
For long running operations, here is an approach which tells setting expire or max-age headers to your response properly. Here is the example Best practice for implementing long-running searches with REST
But I recommend The RESTy Long-op Protocol for your case.
Your solution will be more robust and more client friendly.
I would like to record the various GET requests to my API in a table and use that table as part of the calculation of what to return for future GET requests.
Perhaps the easiest test example would be a GET function that returns the number of GET requests in the last hour.
The REST protocol says that GET requests should only have data returns.
Do I need to POST the request and then GET the results of the same request?
You can easily achieve that with nodejs
You should have the requests saved in a json file or database for example and have another service that returns this saved data.
Take a look at expressjs
Best luck
We have a REST API which, for certain operations, we provide the option of asynchronous requests. For async requests, the service will return immediately with a token which can be used to query for completion, while for synchronous requests, the response will not be returned until the operation completes.
The current design for this looks something like this:
URL: PUT /api/orders/1234?async=true
Request Body: customerName=My Company&city=Dallas
Intuitively, it seems wrong to mix query and form params like this, however the query param (async) is providing options to the service call and not an attribute of the resource. That was the primary reason we did not include it in the request body.
Does this approach seem like a good design, or is there a better more "REST-y" way to accomplish the same?
The Prefer header is designed to do exactly what you are trying to do. See the spec.
An URL like this
POST /api/orders/1234?async=true
is not RESTful. Why POST? This looks like RPC over HTTP.
What are your resources? If there is some computation involved, model the computation as resources. POST to a collection of compuations to create a new one. Receive a Location header for the result of the computation.
POST /api/orders
custoerName=My Company
city=Dallas
This could return a response like:
201 Created
Location: /api/orders/1234
Then the client could GET the result:
GET /api/orders/1234
And the server would respond:
200 OK
Some result body.
How to make this asynchronouse?
You write:
however the query param (async) is providing options to the service call and not an attribute of the resource
This is plain wrong. Everything that is in the URI is used to identify the resource. REST is not about calling methods with parameters.
I recommend to always use the two-step-approach described above when modeling compuations/transactions/shopping carts as resources. Create it, retrieve it.