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
Related
Just started working on an existing project making use of the Exact Online API.
While I was debugging the project I suddenly only started receiving XML results instead of JSON results from the API. I did not change anything about the endpoints being queried I was just running the existing queries trying to figure some things out.
These are the REST API docs: https://start.exactonline.nl/docs/HlpRestAPIResources.aspx
These are the XML docs: https://support.exactonline.com/community/s/knowledge-base#All-All-DNO-Content-xmlsamplecode
Typical REST API endpoints look like this:
https://start.exactonline.be/api/v1/xxxxxx/salesinvoice/SalesInvoices
Typical XML endpoints look like this:
https://start.exactonline.be/docs/XMLDownload.aspx
I also did not change any settings. I only have access to the tokens and api. I don't have access to the account.
This is an example of an endpoint and query where I previously received JSON but am now receiving XML:
https://start.exactonline.be/api/v1/xxxxxx/salesinvoice/SalesInvoices?$filter=InvoiceID eq guid'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx'&$select=InvoiceID
I tried this manually with Postman and also using the existing code from the project.
Is there some setting I am unaware of? Am i querying the wrong way? Maybe there have been some changes to the API I am unaware of that aren't listed in the release notes?
Please provide the request header Accept in your HTTP request that specifies what content format you prefer to receive: application/json. The default of Exact Online APIs is XML (but seldom to never used).
I have been working Rest and json using spring framework.
I have got couple of doubts.
1)Is http transferring data in the form of json can be called Rest.I know http is protocol and Rest is architectural style?
2)Can any application (url) that accepts data in the form of json(sent from any client) called Rest?
2)why soap protocal is using http under the hood?
ReST is an architectural style which is completely independent of either HTTP or JSON. ReST really only talks about modelling a domain as a set of 'resources'. Any resource has a unique identifier which distinguishes it from other resources. Clients interact with resources using a common protocol and resources are created / modified / deleted through manipulating their representations.
HTTP and JSON are both aspects of specific implementations of a ReSTful architecture. HTTP is a good transport mechanism for ReSTful applications, providing a common API in the form of HTTP's set of verbs - GET, PUT, POST, DELETE. JSON is a good document transfer format and so is often used to implement the 'representation' aspect of ReST, but ReSTful applications can use other document formats if they choose - you can find ReSTful applications which use XML, JPEG, AVI, MP3, ...
Neither HTTP nor JSON is specifically ReSTful and its entirely possible to find HTTP applications using JSON which are not ReSTful at all. Similarly, not every ReSTful application will use JSON or HTTP (although I've never seen a real application in the wild which doesn't use HTTP/HTTPS).
Rest is not all about JSON, you have also the verbs GET, POST, PUT, DELETE and the http code for your answers which are involved.
If you post JSON for every action then it's not restful
In REST everything is a resource.
HTTP is an application layer. It's has nothing really with REST concept. You see a webpage via http and this is not REST at all. So SOAP can also use http.
HTTP is not bind to REST but REST is bind to HTTP
As stated in other comments, RESTful is an architecture, but not a language or coding paradigm.
RESTful:
Something anti-REST would be JSON-RPC (https://github.com/ethereum/wiki/wiki/JSON-RPC). The Framework is a Remote Procedure Call Lib. JSON-RPC would definitely not be RESTful since the RPC layer maps urls to functions (i.e. verbs) rather than particular resources (i.e. nouns). So rather than POSTing to some resource, you are calling a method, yet JSON as the format to serialize the data. There are tradeoffs to each. It just so happens RESTful APIs are very common for public ones as many believe documentation can be clearer to outsiders.
JSON:
On the other hand, one could develop a RESTful architecture and not use JSON. There are many serialization libs, each with tradeoffs such as compression and schema-less vs something closer to type safety. Examples besides JSON would include MessagePack and Google's ProtoBufs. Of coarse, you could even use XML, although uncommon with RESTful APIs. JSON is used a lot in public APIs since pretty much any language can do JSON serialization with low 3rd party over head (i.e. not importing specific libs)
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
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.
Let's say I have a northwind database and I use ADO.NET Entity Data Model which I automatically generate from the tables in database. Then I add a new WCF data service that inherits from DataService. When I start the web application, that runs the service I can request data like this:
http://machine/Northwind.svc/Orders
This will return all orders from order table in atom/xml format. The problem is I do not want XML. I want JSON. I think I tried all kinds of settings (web.config) and attributes in my application, but I still get XML. No matter what. I can only get JSON, when I use fiddler and change the request header to accept JSON.
I do not like the concept of content negotiation. I want always to return data in JSON format. How can I achieve that?
Keep in mind that I did not create any model objects, they are automatically created based on database tables and relationships.
Well - content negotiation comes with HTTP. In any case, you could intercept the incoming request and add/overwrite the Accept header to always specify the JSON. There's a sample how to support JSONP which uses a similar trick, I think you should be able to modify it to always return JSON as well. http://archive.msdn.microsoft.com/DataServicesJSONP.
The behavior you criticize is defined by specification of OData protocol. OData defaults to Atom and client can control media type of the representation either by Accept HTTP header or by $format parameter in query string (but I'm not sure if WCF Data services already support this).