Is it possible to document a response field for a controller that returns a single value?
Example: [GET] /book/count
JSON Response: 1
You can't use the response fields snippet. It expects a structured JSON or XML response. Given that your response is a single, numeric value I don't think you'd gain much from REST Docs documenting it anyway. There's next-to-nothing for it to document and verify.
REST Docs will still automatically produce an HTTP response snippet that you could use. If you want something more, you could write your own Snippet implementation pretty easily.
Related
Fetching data from one post response and reusing it for two other requests using JSON Extractor in Jmeter.
After reusing the response param for the first request the second request can't reuse the response and shows the default value used in JSON Extractor.
The values aren't coming in the second request, however it comes in the first request.
Most probably your placement of the JSON Extractor is incorrect, JMeter PostProcessors obey JMeter Scoping Rules so if you have the JSON Extractor at the same level as other Samplers - it's getting applied to all samplers therefore after 1st request is being executed the variable gets overwritten with the default value.
The solution is to put the JSON Extractor as a child of the request which returns the data you want to extract, something like:
You should put JSON Extractor level under request 1, and not after, in order to get the variable from response 1 only
This is because it's a post processor which is executed after each Sampler (request) in its hierarchy
The rest service which are fetching parameters and JSON extractor should be kept as a child of the web-service from which parameters are fetched. This solved my issue.
I have the following Backend API:
Endpoint
HTTP GET
https://localhost:8443/getSomeParameterInfo
Query Parameter
?inputAsJson
example
{
'url': 'http://semanticstuff.org/blah#Parameter,
'parameters_1': 'value1',
'someArray': [
'http://semanticstuff.org/blah#something1,
'http://semanticstuff.org/blah#something2
],
'someOtherArray': [
'http://....'
]
}
the Final HTTP GET Call is
https://localhost:8443/getSomeParameterInfo?inputAsJson={aboveMentioned JSON}
Due to everchanging requirements for the Backend, the above mentioned JSON Structure keep increasing by addition of new key:value pairs. (This JSON Structure is also a query for a database)
Hinderances
Due to uses of weblinks as values it becomes necessary to use encodeURIComponent function for a successful REST Call. This means, the quotes, forward slashses etc. need to be encoded to get a Reply. This becomes quite tedious when one requires to do tests on standalone basis (using Postman or other REST Clients)
I have not seen a JSON structure passed to an API as mentioned above and hence I wish to confirm about the best practices and/or proper way to use large number of parameters when making such a RESTful call
I usually tend to think that getting something via a POST is a "bad" practice.
However, it sounds like body in GET is not something forbidden but still something not widely implemented in frameworks.
In your case, it will depends on how many attributes you have and the global length or your json.
If you keep on using GET method, then using an "exploded" key-value representation of your JSON should be the way to go.
Exemple:
{ "myKey": "myValue", "childObjKey": {"childObjProp": "childValue}}
could become
?myKey=myValue&childObjKey.childObjProp=childValue
But there are some limits on query parmeters' length which can be implemented in clients and/or servers.
If your number of parameters is huge and values' length are unpredictable (text without length limit for instance), then using POST should be the way to go.
What I know that the HTTP method GET is for fetching/searching data and POST is for create/insert data.
But what if there is a case that I want to search data but the parameters (key-value pairs) are so many or big that there is possibility it will go over the query string limit for the GET method.
In this case, if I use POST for searching data, is it valid in the REST or HTTP specification?
Its perfectly valid in the scenarios where you have lot many number of variable parameters.
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.
I am designing a RESTful API and I would like to know what the most RESTful way is to return details about an operation.
E.g. an operation on a resource occurs when some data is POSTed to a URL. HTTP status codes will indicate either success or failure for the operation. But apart from success/failure I need to indicate some other info to the client, such as an ID number.
So my question is, should the ID number be returned in an XML document in the response content, or should it be returned in some custom HTTP header fields? Which is more in line with the principles of REST? Or am I free to choose.
Returning an entity is a perfectly valid response to an HTTP POST.
You also do not need to return XML you could just use the content type text/plain and simply return a string value.
Using a header would require you to define a new custom header which is not ideal. I would expect clients would have an easier time parsing a response body than extracting the information from a header.
XML document makes the most sense.
If it is a just an ID number, it would save overhead to do it just as an HTTP header. Building a correct XML document just for a single number would add much more overhead to the request.