I need to formally specify a resource model for RESTful web services and I'm considering XML Schema as a specification language. Ideally, this resource model would promote HATEOAS style client development. Some questions:
1) Is XML Schema the best option to formally specify web resources?
2) Should each resource be identified as a custom media type?
3) Is it possible to define the set of link relations for a resource as part of its schema specification?
Thanks,
Cameron.
We are using this
http://stateless.co/hal_specification.html
Yes you can define using XML Schema but you no need to re-invent the wheel. WADL is the one you are looking for. From wikipedia
The Web Application Description Language (WADL) is a machine-readable
XML description of HTTP-based web applications (typically REST web
services).1 WADL models the resources provided by a service and the
relationships between them.1 WADL is intended to simplify the reuse
of web services that are based on the existing HTTP architecture of
the Web.1 It is platform and language independent and aims to
promote reuse of applications beyond the basic use in a web browser.
Do you need WADL?
Related
I need to understand the concept of Apache Sling in AEM. AEM docs says Apache Sling can be described as a RESTful web framework and Apache Sling is RESTful framework to access a java content repository over http protocol.
I used sling api to access the JCR node/properties. I really dont know where restful is used here. Can anyone please tell how Apache Sling is working as a RESTful web framework in CQ/AEM?
The way I understand it, calling a framework RESTful is a bit of a stretch. A framework can be used to build a RESTful application if it allows you to follow the defining constraints of REST. At the same time, it's possible to violate them regardless of the framework. Therefore, no matter how "RESTful" your tools are, you can end up with an application that has nothing to do with REST.
In case of Sling, you can easily create a Servlet, specify that it should use the GET method and have it modify the state of the repository, violating the semantics of the underlying HTTP protocol.
I think what they mean in the Adobe documentation that you referred to is that the default servlets will behave in a way consistent with HTTP, the way Thomas explained in his answer.
However, being consistent with the underlying protocol does not seem enough to call an API RESTful. For instance, I don't really see how Sling (considered in isolation) uses HATEOAS (Hypertext as the Engine of Application State). You need to drive the application state using hypermedia. It makes more sense to me if we consider Sling together with CRXDE, which provides hypermedia controls for resource manipulation.
As for AEM itself, I saw a presentation earlier this year by none other than Roy Fielding himself about REST in AEM and the point he makes is that AEM is RESTful in the sense that it can be used like a website.
It's navigable
it uses hypertext (interpreted by the browser) as the engine of application state
manipulates resources through the exchange of representations
access methods (as defined by the underlying protocol, HTTP in this case) have the same semantics for all resources.
etc.
It's effectively a website you can use for content management (and more). It can be used by a client (a browser) simply by going to the welcome page and following the hyperlinks, interpreting code retrieved on demand with no need for out-of-band communication (as in reading documentation, building URLs by hand and the like)
Please mind that this answer is my own interpretation of the information I found in AEM and Sling documentation and Roy Fielding's posts and presentations and that it's in no way endorsed or approved by Adobe or Roy Fielding himself ;)
Did you read the documentation of Apache Sling? Or what exactly is your question?
Anyway, Sling was developed for CQ together with JCR. Both were then submitted to Apache (Jackrabbit as the reference implementation of JCR).
Sling is RESTful as it doesn't use sessions (except while authoring) to provide the content that is stored in JCR. It uses the main HTTP protocols, mainly GET and POST, but also PUT and DELETE can be used. You can use so called selectors and extensions to give different views on the same content. Most commonly HTML, JSON and XML.
What is basic difference between restful and restless, i've been reading a few articles people seem to use them interchangeably.
REST stands for REpresentational State Transfer and goes a little something like this:
We have a bunch of uniquely addressable 'entities' that we want made available via a web application. Those entities each have some identifier and can be accessed in various formats. REST defines a bunch of stuff about what GET, POST, etc mean for these purposes.
the basic idea with REST is that you can attach a bunch of 'renderers' to different entities so that they can be available in different formats easily using the same HTTP verbs and url formats.
For more clarification on what RESTful means and how it is used google rails. Rails is a RESTful framework so there's loads of good information available in its docs and associated blog posts. Worth a read even if you arent keen to use the framework. For example: http://www.sitepoint.com/restful-rails-part-i/
RESTless means not restful. If you have a web app that does not adhere to RESTful principles then it is not RESTful
'RESTless' is a term not often used.
You can define 'RESTless' as any system that is not RESTful. For that it is enough to not have one characteristic that is required for a RESTful system.
Most systems are RESTless by this definition because they don't implement HATEOAS.
Any model which don't identify resource and the action associated with is restless. restless is not any term but a slang term to represent all other services that doesn't abide with the above definition. In restful model resource is identified by URL (NOUN) and the actions(VERBS) by the predefined methods in HTTP protocols i.e. GET, POST, PUT, DELETE etc.
Here are roughly summarized the key differences between RESTful and RESTless web services (it does not have to be strictly valid):
1. Protocol
RESTful services use REST architectural style,
RESTless services use SOAP protocol.
2. Business logic / Functionality
RESTful services use URL to expose business logic,
RESTless services use the service interface to expose business logic.
3. Security
RESTful inherits security from the underlying transport protocols,
RESTless defines its own security layer, thus it is considered as more secure.
4. Data format
RESTful supports various data formats such as HTML, JSON, text, etc,
RESTless supports XML format.
5. Flexibility
RESTful is easier and flexible,
RESTless is not as easy and flexible.
6. Bandwidth
RESTful services consume less bandwidth and resource,
RESTless services consume more bandwidth and resources.
I have developed a small RESTful web service example using MyEclipse. I want to create a client for those WS using WSDL. How do I create a WSDL for the above web service using MyEclipse? Please help.
Take a look at this resource. It describes using WSDL 2.0 to describe a REST interface:
http://www.ibm.com/developerworks/webservices/library/ws-restwsdl/#describerestservice
WSDL ? for a REST web service ? i'd suggest you read this book for a better understanding of REST http://oreilly.com/catalog/9780596529260
You don't need WSDL (nor WADL AFAIC) documentation in rest could be plain text for developers, schemas (xsd, rdfs...etc depending on the content types you use) sitemaps for example, a lot of links and post/put templates for example ( to mimic forms in html)
I have been reading about REST and SOAP, and understand why implementing REST can be beneficial over using a SOAP protocol. However, I still don't understand why there isn't the "WSDL" equivalent in the REST world. I have seen posts saying there is "no need" for the WSDL or that it would be redundant In the REST world, but I don't understand why. Isn't it always useful to programmatically bind to a definition and create proxy classes instead of manually coding? I don't mean to get into a philosophical debate, just looking for the reason there is no WSDL in REST, or why it is not needed. Thanks.
The Web Application Description Language (WADL) is basically the equivalent to WSDL for RESTful services but there's been an ongoing controversy whether something like this is needed at all.
Joe Gregorio has written a nice article about that topic which is worth a read.
WSDL describes service endpoints. REST clients should not be coupled to server endpoints (i.e. should not be aware of in URLs in advance). REST clients are coupled on the media-types that are transfered between the client and server.
It may make sense to auto generate classes on the client to wrap around the returned media-types. However, as soon as you start to create proxy classes around the service interactions you start to obscure the HTTP interactions and risk degenerating back towards a RPC model.
RSDL aims to turn rest like a hypermedia, in other words, it has more information than a service descriptor like WSDL or WADL. For example, it has the information about navigation, like hypertext and hyperlinks.
For example, given a current resource, you have a set os links to another resources related.
However, i didn't find Rest Clients that supports this format or Rest Server Solutions with a feature to auto generate it.
I think there is a long way for a conclusion about it. See the HTML long story and W3C vs Browsers lol.
For more details about Rest like Hypermedia look it: http://en.wikipedia.org/wiki/HATEOAS
Note : Roy Fielding has been criticizing these tendencies in Rest Apis without the hypermidia approach: http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven
My Conclusion : Now a Days, WADL is more common that Rest and Integration Frameworks like Camel CXF already supports WADL ( generate and consume ), because it is similar to WSDL, therefore most easy to understand in this migration process ( SOAP to REST ).
Let's see the next chapters ;)
Isn't it always useful to programmatically bind to a definition and
create proxy classes instead of manually coding?
Agree wholeheartedly, this is why I use Swagger.io
Swagger is a powerful open source framework backed by a large
ecosystem of tools that helps you design, build, document, and consume
your RESTful APIs.
So basically I use Swagger to describe my models, endpoints, etc, and then I use other tools like swagger-codegen to generate the proxy classes instead of manually coding it.
See also: RAML
There is an RSDL (restful service description language) which is equivalent to WSDL. The URL below describes its practice http://en.wikipedia.org/wiki/HATEOAS and http://en.wikipedia.org/wiki/RSDL.
The problem is that we have lots of tool to generate code from wsdl to java, or reverse.
But I didn't find any tool to generate code from RSDL.
WSDL is extensible to allow description of endpoints and their messages regardless of what message formats or network protocols are used to communicate
However, REST uses the network protocol by using HTTP verbs and the URI to represent an objects state.
WSDLs tell you at this place, if you send this message, you'll perform this action and get this format back as a result.
In REST, if I wanted to create a new profile I would use the verb POST with a JSON body or http server variables describing my profile to the URL /profile
POST should return a server-side generated ID, using the status code 201 CREATED and the header Location: *new_profile_id* (for example 12345)
I can then perform updates changing the state of /profile/12345 using the HTTP verb POST, say to change my email addresss or phone number. Obviously changing the state of the remote object.
GET would return the current status of the /profile/12345
PUT is usually used for client-side generated ID
DELETE, obvious
HEAD, gets the status without returning the body.
With REST it should be self-documenting through a well designed API and thus easier to use.
This is a great article on REST. It really help me understand it too.
WSDL 2.0 specification has added support for REST web services too. Best of both worlds scenario. Problem is WSDL 2.0 is not widely supported by most tools out there yet. WSDL 2.0 is W3C recommended, WSDL1.1 is not W3C recommended but widely supported by tools and developers.
Ref:
http://www.ibm.com/developerworks/library/ws-restwsdl/
The Web Application Description Language (WADL) is an XML vocabulary used to describe RESTful web services.
As with WSDL, a generic client can load a WADL file and be immediately equipped to access the full functionality of the corresponding web service.
Since RESTful services have simpler interfaces, WADL is not nearly as necessary to these services as WSDL is to RPC-style SOAP services.
To describe RESTful we can say that every resource has its own URI. Using HTTP GET, POST, PUT and DELETE, we can operate on these resources. All resources are representational. Whoever wants to use our resources can do so via a browser or REST client.
That's the main idea of a RESTful architecture. This architecture allows services on the internet. So why does this architecture need WADL? What does WADL offer that standard HTTP does not? Why does WADL need to exist?
The purpose of WADL is to define a contract. Contract specifies how one party can call another.
When you create a web application from scratch, you don't need contract and WADL.
When you integrate your system with the other system and you can communicate clearly with their development team, you don't need contract and WADL (because you can make a phone call to make things clear).
However when you integrate a complex enterprise system with several others complex enterprise systems maintained by several different companies (or federal institutions), then believe me you want to have a communication contract defined as strictly as possible. Then you need WADL or Open Specification. Need it badly.
People with weak enterprise background tend to see entire IT as a collection of separated web applications developed independently. But enterprise reality is sometimes tough. Sometimes you can't even call or write to the people developing the application you have to integrate with. Sometimes you communicate with a legacy application that is no longer maintained--it just runs and you need to figure out how to communicate with it properly. In such conditions you need a contract because it saves your ass.
Actually client generation is the minor feature of the contract definition. It's just a toy. Contract enforces bad communicators to communicate integration rules clearly. This is the main reason to use WADL or Open Specification or whatever.
Using WADL implies that you just might be gracious enough to actually define the data / documents you are passing back and forth. Say you are passing some XML fragments, they might actually be part of a defined schema.
Whether or not you use the DL to generate code is not very important to me. What matters, in my subjective opinion, is that it is important to have a formal agreement on interfaces between business partners. Even if what is passed is obvious, it helps to identify who has to fix what later if somebody changes the previous interface.
Data format is just as much a part of an interface as verb names.
WADL appeals to people coming from the SOAP world where it is common to use a code generator to create client side code based on the WSDL. I don't think that mechanism is useful in REST as it creates client code that is coupled to server endpoints.
I believe that if you properly define your media-types and use hypermedia within those media-types, then it is not necessary to have WADL. The description of the available end-points is contained within the media-type definitions themselves. And if you are now saying to yourself, but application/xml doesn't contain any information about available hyperlinks, then I say BINGO. That's why I don't think application/xml and application/json are appropriate media-types for REST. I'm not saying don't use XML or JSON, just don't use the generic media type name.
The other appeal of WADL is for the purpose of documenting REST services. Unfortunately, it leads developers down the wrong path as WADL attempts to document server-side end points. Documenting a REST services should focus primarily on the media-types. A client developer should be able to write a REST client without knowing any url other than the root url.
WADL allows you to generate code, tests and documentation. Actually there are few very useful tools utilizing WADL, you can see some examples here. The problem with the "pure" REST, as described in Fielding's dissertation, is writing clients supporting Hypermedia (imagine writing Java Swing-based client application for example). With WADL this task is completely automated, and it's a huge advantage in my view. Testing becomes a way easier too.
Before I give my explanation, let me say that most pure REST extremists will deride it to the ends of the earth. I don't agree with them, as i'd rather get something done, but just so you know.
WADL is a description of a web service API, a little like WSDL is for SOAP type web services, that is designed to be more in tune with RESTful interfaces (something WSDL is poor at).
It's primary usage in my experience is to allow you to generate client code that can call the service (handy if it's a very large API, which literally saves hours of work). It also serves the purpose of documenting a REST-like interface.
REST specifies nothing about WADL.
When you want to expose the REST services ,the best way is to generate WADL and share with consumer(similar to WSDL in SOAP based web services).WADL is used to describe service all in on place.
WADL is not necessary to use. But, If you are working with complex existing application and you want to implement REST service call by replacing the EJB/SOAP service call, Then it is very safe and good practice that you use WADL. By using WADL generate client side java stubs you will be in sync with the service.
You can generate client side java stub using WADL file with help of wadl2java maven plugin.