Does JSON messages sent over HTTP in response to a URL request make it REST-compliant?
I believe it is not.
But I am not sure on the detailed reason.
If i have a well-organized website,which responds to URL requests with json representation payload - what does it need to do further to comply with RESTful or JAX-RS?
A simple concise explanation will be much appreciated
There is no restriction regarding the payload of messages in REST and using JSON format in HTTP responses isn't enough to make a service RESTful.
To make short (since it's what you asked for ;-)), what is really important in REST is to respect the HTTP operations (GET, POST, ...) are designed for, the concept of resources and their states (idempotence, ...), leverages headers and status codes, ...
The following link could give you hints about the way to implement a RESTful service / Web API:
Designing a Web API - https://templth.wordpress.com/2014/12/15/designing-a-web-api/
Hope it helps you,
Thierry
JSON is a payload and does not play any role in making your Webservice REST-complaint.
Payload could be XML, CSV, plain text etc etc.
The Webservice will be REST-Complaint when it's following REST protocol (set of rules, not network protocol).
There are up to 4 levels where you can make your REST webservice complaint to.
One of the very basic rules to understand is that - Your Request must not be RPC i.e. you MUST not perform any action using a Payload (Typical SOAP) or URL tunnelling e.g. http://www.example.com/product?id=1234&action=delete
In RESTful world you would define one top level URI for the above. e.g. http://www.example.com/product
and then you will call various URLs to perform other actions.
Such as:
POST - create Data
http://www.example.com/product
Body{ here your payload will describe the Product.}
Assuming you rely on server gennerated product id then return type could be Product Id. Which is again should be set as LOCATION parameter of the return header.
PUT - Update Data
http://www.example.com/product/1234
Body{ here your payload will contain the Product details to change.}
GET - Get Data
http://www.example.com/product/1234
DELETE - Delete Data
http://www.example.com/product/1234
Related
I have to implement REST endpoints to update a resource.
I will use the methods PUT and PATCH (the latter used to send a json that has only the attributes to modify).
The payload of the calls will be a json that is parsed by Jackson.
Using custom deserializers and converter,s the parser will create the correct instances of java beans.
I know that usually these endpoints will have in their URL the ID of the resource to update.
For the PATCH endpoint, I would prefer to send the ID of the resource in the json, together with all the other resources.
I can see PROS and CONS.
CONS: the URL looks like something that is updating the collection of resources and not a single resource,
PROS: the json contains all the necessary information and the parser can find the resource in the database and add the information that wasn't sent with the request.
This would simplify the code because the parser will return an object ready to use.
As you pointed out, it would be better to pass the ID in the URL.
One of the main constraint of a REST API is the "Resource identification in requests": it should be possible to easily identify the resource modified looking the call.
It is not enough that the representation passed has the information necessary to identify the resource: it is also important that the identification is easy and does not require the knowlodege of internal details.
I've set up an API in Spring where the client can specify the ids of the objects they want to receive. It returns a JSON list (using the #ResponseBody annotation) of the objects.
But, since the request can be a long list, I've set it up as a POST, where it's received as an object named ProductRequest (using the #RequestBody annotation). This seemingly isn't conformant to the official REST API standard, since posts are official to create new objects, but it seems better to implement it this way since you're not cluttering up the URL with a bunch of ids. Also, I can specify additional parameters customizing the output.
So my question is, can this be considered a valid RESTful design? Post isn't being used to create an object, so it's not strictly conformant to restful. Thoughts?
It is a simple GET request.
#GetMapping(path = "/your-url")
public List<Object> method(#RequestParam(name="ids") List<Long> objectIds) {
}
You can receive your list just as a simple java list.
/api?ids=1,2,3
You can very well do an http POST to "get" the resource(s). There are some very valid examples of doing so,
GraphQL -- All we are doing is sending (POSTing) some Queries in requestbody to "GET" some data in the format that we prefer
Assume that you have to authenticate with a username and password to get a specific data, you will either send it in Header in GET request or you will do a POST to 'GET' a data.
Couldn't that overflow the max allowable for the URL string?
Actually, there is no limitation on the length of a URI. However, practically, you can encounter some.
According to RFC7230 (emphasis mine),
HTTP does not place a predefined limit on the length of a request-line, as described in Section 2.5. A server that receives a method longer than any that it implements SHOULD respond with a 501 (Not Implemented) status code. A server that receives a request-target longer than any URI it wishes to parse MUST respond with a 414 (URI Too Long) status code.
Various ad-hoc limitations on request-line length are found in practice. It is RECOMMENDED that all HTTP senders and recipients support, at a minimum, request-line lengths of 8000 octets.
It clearly suggests that we can't rely on a request-line while we are dealing with your issue.
Can this be considered a valid RESTful design?
Due to the limitation mentioned above, using POST is a valid workaround.
As stated by this Wikipedia article,
The common workaround for these problems is to use POST instead of GET and store the parameters in the request body. The length limits on request bodies are typically much higher than those on URL length.
To completely free you from hesitation, there is a common non-standard header X-Http-Method-Override. It requests a web application to override the method specified in the request with the method given in the header:
X-Http-Method-Override: GET
I am not sure whether Spring handles the header. Though, it has the HiddenHttpMethodFilter filter which seems to do similar work.
I am trying to stick to the Restful design pattern for both JSON and HTML. My issue is the design for creating a new resource (amongst others, but this is the gist of the issue). IE:
JSON – POST to /resource creates a new resource.
JSON – GET to /resource returns a list of resources.
JSON – GET to /resource/{id} returns a resource.
HTML – POST to /resource creates a new resource.
HTML – GET to /resource returns a list of resources.
HTML – GET to /resource/{id} returns a resource.
All good so far – but I need a HTML form to actually create the data to send to the HTML POST. Obviously POST and GET already do things. I could use one of the below to return the HTML form:
HTML – GET to /resource?CREATE
HTML - GET to /resource?action=CREATE
HTML – GET to /resources/CREATE
But they seem like a kludge and not that intuitive.
Any thoughts or ideas?
EDIT - See my answer to my question below. At present this is (I consider) the best option.
I would indeed use something like /resources/create. If you want to allow for non-numeric identifiers, then this will not work. In that case you can identify a resource with a prefix, such as /resources/resource-{id} and then you can still use /resources/create.
I found this blog post really helpful to make URI scheme decisions: http://blog.2partsmagic.com/restful-uri-design/
In fact, you should leverage content negotiation (CONNEG) when you want to handle several formats within RESTful services.
I mean:
Set the Content-Type header to specify the type of sent data
Set the Accept header to specify the type of data you want to receive
The server resources should leverage these hints to make the appropriate data conversion.
In the case of JSON, the content type would be obviously application/json. For HTML form, you should leverage the content type application/x-www-form-urlencoded (or multipart/form-data if you want to upload files as well). See the specification for more details.
Otherwise, you shouldn't use action in URL since it's not really RESTful. The HTTP verb should determine the action to do on the resource. I mean, to create a resource, the POST method should be used. The GET method aims to retrieve the state of a resource.
For more details, you could have a look at this blog post:
Designing a Web API (i.e. RESTful service).
I have an answer. I'll use standard RESTful POST from a HTML page, but when I have no form parameters sent and my accept header is text/html, I'll send a HTML form to the requestor. Keeps RESTful URI design and allows a clean HTML form + process (2 step).
HTML - POST - /resources (with no form attributes) generates a HTML form
HTML - POST - /resources (with form attributes) adds a resource
JSON - POST - /resources (with form attributes) adds a resource
OK, it's not "strictly" RESTful as I'm POSTing but not creating a new resource so in theory I should use a GET for that, but it's the best of a mismatched design.
If anyone can provide a better solution, I'm still all ears :-)
I'd rather add and endpoint called /templates/ that returns a template/form/whatever you need for given action. It also seems that the server should be unaware of such form existence. It can accept or reject a request and it's client job to submit it in an appropriate format.
I guess that you mix processing the view with preparing RESTful endpoints. The backend site should be completely unaware of the fact that some sort of view/form is required. It's client job to prepare such form.
I need to add JSON format parameters to request payload to do a POST request in restful service testing. How can I do that in SOAP UI?
You did not specify which version of SoapUI you are using. In version 4.x of SoapUI, they made the same assumption as what FrAn answered: you generally do not want to include a payload for a GET request. In later versions of SoapUI, they corrected this and you are able to do it.
Once you change the method type to POST, on the individual method call, you will see another panel where you are able to define the body. You can see this in the documentation. You will have to write out the entire body manually.
For REST services, the payload is not part of the WADL - which SoapUI uses internally to store the entire definition. You can create a sample Request in your REST service to make creating test cases easier. You can see this in the documentation.
Lastly, some additional information is available in the API Dojo.
HTTP GET request shouldn't contain payload. While you can do that, insofar as it isn't explicitly precluded by the HTTP specification, I would suggest avoiding it simply because people don't expect things to work that way.
I'm new to REST Web based services and trying to understanding how the contract is created for JSON returned REST services.
From my understanding, any XML based SOAP/REST services will have a WSDL document.
What document is created for JSON based REST Services?
a REST web service doesn't have any auto explanation document like wsdl, you need to know how the webservice works, reading the documentation provided with it. Generally it works with common requests. Assuming that you have a products REST webservice, you could have:
GET /products -> read all products
GET /products/1 -> read the product 1
POST /products -> create a new product
PUT /products/1 -> update product 1
DELETE /products/1 -> delete product 1
but you have to know which parameters you need to send to any request. I hope I was clear...
Every HTTP response has metadata in HTTP headers. One of those HTTP headers is ContentType. The content type identifies a media type which is the contract that the response payload must conform to. The specifications for media types can be found here http://www.iana.org/assignments/media-types/media-types.xhtml
One of the major differences between SOAP and HTTP (as an application protocol) is that SOAP defines the contract at design time, whereas with HTTP the contract is specified in the response message so it can change over time. Therefore it is important for the client to read the content type on each response to know how to process the response.
There is WADL (http://en.wikipedia.org/wiki/Web_Application_Description_Language) although it is not so much used as WSDL for SOAP. REST services written in Java EE automatically generate it as .../application.wadl, PHP suppor is pretty poor as far as I know.
As the others mentioned a web service definition is not necessary for RESTful services, however if you want to create something similar for your API the industry standard is Swagger/OpenAPI, though GraphQL schemas are also becoming a defacto standard too.
There are also a few other options you can also explore (see wikipedia).
Here is a list of the most common options:
swagger.json or openapi.json files in the OpenAPI Spec
GraphQL Schemas with full spec here
Postman Collections which can be published online.
RAML
RSDL