I am new to Adobe CQ. I knew it uses Apache Sling framework. Apache Sling is RESTful framework to access a java content repository over http protocol. Can any one tell me with examples on how restful service is being used in CQ?
Thanks
Did you read the documentation already? A good and quick start is the Sling Cheatsheet.
Regarding to CQ and the underlying JCR repository, each resource in the repository is represented as a path. You can access this resource by different means. If we start with the example projects (geometrixx in different characteristics) you can call for example /content/geometrixx/en.html
The extension html will render the resource as a html page whereas the markup is defined in a JSP. But you can also call /content/geometrixx/en.json or /content/geometrixx/en.xml to get a JSON or XML representation of this resource. You can also add selectors: In the JSON example you can call /content/geometrixx/en.5.json to get the hierarchy of this node up until level 5.
I strongly advice to check out the sling documentation and if you still struggle with something ask a more precise question or better search for it as there are already some problems explained.
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.
I want to host restful webservice from CQ5. Basically the intention is to expose all the users present in CQ5 to external systems based on some parameters like modified date, user state etc.
I went through https://chanchal.wordpress.com/2015/01/11/using-jax-rs-and-jersey-to-write-restful-services-in-osgi-apache-felix-adobe-cq5aem/ as I could find only this post online, but as I am a beginner I couldn't implement it. Need guidance in implementing such RESTful webservice in CQ5
CQ5 is based on Apache Sling which is inherently RESTful, so you don't usually need additional libraries. In your case (and unless the users info is already available as Sling resources, I don't remember if that's the case) implementing a Sling ResourceProvider is enough to provide a browseable RESTful representation of those resources. See the Sling docs for more info, they point to a simple PlanetResourceProvider as a minimal example.
Couldn't get the REST webservices working with AEM/CQ5. Even after installing the packages for JAXB for CQ5. It seems like sling overrides the resolving before it goes to the JAXB annotation handler. Due to lack to time had to implement an alternative approach where CQ5 will be timely writing the json data to an shared location as json file and the third party applications will fetch the files from there.
This will however impact the performace as schedulers are to be written and also it's not a recommended approach but still it will work in my scenario.
Thanks all for helping me.
I am trying to create a RESTful web service that accepts JSON arguments and gives out a JSON response.
What I want is to accept HTTP requests made to my URL endpoint.
Something like,
POST /the/endpoint HTTP/1.1
Host: mywebsite.com
{"name":"yourname", "department":"your_department"}
Do a DB read at the backend and give relevant parameters like, say Manager name, salary etc as a JSON object, as the response.
What's the best way to go about it? I was thinking of using Java servlets for this? Is there a better way?
PS - I am just getting started so detailed answers or links to tutorials as to how to implement it would be much appreciated.
Thanks.
Yes you can easily do this with Servlets and some Json Libs for Marshalling /unmarshalling the Json Object to Java Object.
You can make use of Json libs like
Jackson ,
Gson etc
But you must know that REST application doesnt end with just handling the request and response , but it needs to take care of other non-functional requirements like
Authentication
Authorization
Security etc
Building this from a scratch from a Servlet is overkill and waste of time when there are ready made frameworks that these things for you
My favorite is Spring MVC 3.0
Check their project site for more details
Just to show you how easy to set up one in Spring MVC , check this below tutorial
Spring 3 REST Tutorial
Pls rate the post if it helps , Cheers.
If you want to go with Java, I suggest that you take a look at JAX-RS... And since REST is a complex topic, here is a url with tons of informations on it. http://code.google.com/p/implementing-rest/
As a complete beginner, I believe the best way to implement a (nearly) RESTful API without having to read a lot is simply to implement the API just using HTML pages and HTML forms with the back-end processing to handle them.
The rules are:
Use <a> tags to provide links to related resources. (navigation)
Use <form> tags to initiate any kind of processing operation on the server. (actions)
You can then make it properly RESTful by using progressive enhancement to add Javascript AJAX requests that perform PUT, PATCH, and DELETE instead of using POST for those three (of course, keeping POST for creating resources where the client doesn't know the resultant URI).
You can then click around and test the API in a web browser! Tools like Selenium can automate this.
If you need to provide JSON, this can be added after the API has been designed and tested, although libraries exist to process HTML or XHTML responses too, so JSON isn't necessarily required for machine readability.
if you are using php with symfony try:https://github.com/FriendsOfSymfony/FOSRestBundle this lets you create a real REST full servicer very quick.
Vogella made my day very easy when i started Web services with an super example here with eclipse screen shots ..Have a look here.
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.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 5 years ago.
Improve this question
I'm writing a specification for a RESTful API for a new internal web service. It's not hugely long and fairly simple, but even so, it's my first time using strict REST (as opposed to cheating for practical reasons - avoiding PUT and DELETE because they're a pain in PHP, and so on). I was wondering if there were any standard methods or best practices for documenting a REST interface? I want the rest of the team to understand it at a glance, and for anyone that wants to write a client to be able to do so without understanding the underlying code.
Sure, REST APIs should ideally use HATEOAS and be hypertext driven (with heavy use of media types), but also having simple human-friendly documentation for developers to work off of is helpful.
Some specific tools that are helpful for generating documentation like this:
Swagger
An open spec for describing REST APIs [ github ]
Tools for auto-generating
Documentation
Code for your API
Donated to the OpenAPI initiative and renamed OpenAPI in 2015
Mashery
An open source project [ github ]
Tools for generating
Documentation
An exploration interface for your API
Apiary and API Blueprint
Write the API description in a DSL within markdown
Tools for auto-generating
Documentation
Mock server
Seems to be focused on ruby+mac devs
RAML
A spec for describing REST APIs [ github ]
WADL
A spec for writing discoverable API docs with XML
Some discussion comparing WSDL and WADL
APIgee
A commercial product with some documentation features
3scale
A commercial product with some documentation features
miredot
Commercial REST API documentation generator
Java specific
I've been using http://apiary.io, which is pretty nice. You can also export the API documentation to github.
In Roy's post here he states
A REST API should spend almost all of
its descriptive effort in defining the
media type(s) used for representing
resources and driving application
state, or in defining extended
relation names and/or
hypertext-enabled mark-up for existing
standard media types. Any effort spent
describing what methods to use on what
URIs of interest should be entirely
defined within the scope of the
processing rules for a media type
(and, in most cases, already defined
by existing media types).
A good ReST documentation would mean documenting your media type and only your media type.
In a typical scenario, you'd produce a document like so:
The Acme Corp XML formats
Link Discovery
Links to various resources are described in a document that can be found by issuing a GET or HEAD request to the server on a bookmark URI (typically the root of the server, http://www.acme.org), and looking for an HTTP Link header:
Link: <xxx>;rel="http://rel.acme.org/services";type=application/vnd.acme.services+xml
where the rel part is the link relationship, and the xxx is the URI for which the relationship has been established.
Link Relationships
This document defines the following relationship names:
http://rel.acme.org/services
The link relationship describes the list of links that can be navigated.
http://rel.acme.org/customers
The link for which this relationship is used is the list of customers.
Media Types
The application/vnd.acme.services+xml is a document with an xml serialization that describes a list of links an application may want to process.
<links>
<link rel="http://rel.acme.org/customers" href="http://www.acme.org/services/customers" type="application/vnd.acme.customers+xml" />
</link>
The applcation/vnd.acme.customers+xml is a document with an xml serialization that describes customers.
Example documents:
<customers>
<customer firstname="Darth" lastname="Vador" href="http://www.acme.org/services/customers/28" />
</customer>
etc...
The point is to give a way to the developer to follow the links you define. First find the link to the index so they can get the list of things they can navigate to.
Once they discover that document, they discover that they can see a list of customers at a certain Uri, and can do a GET against it.
If they find a customer of interest, they can follow the link defined in /customers/customer/#href and issue a GET to retrieve a representation of that customer.
From there, your media type could embed actions that are available to the user, using more links. You also have the additional option of issuing an OPTIONS request on the resource to know if you can allow deleting the resource, or a PUT if you can save the document back after modification.
So a good documentation doesn't ever:
give static links
give interaction such as "you can issue POST on Customer with this media type and that will mean the move operation". The client should issue a POST against Customer only because your XML document has specified it that way.
The point of all this is to achieve minimum coupling between clients and servers. The client can be very smart in displaying and discovering resources (showing forms and god knows what else), but is totally dumb as to what the actual workflow is: the server decides.
At my company, we've been very happy using WADL, Web Application Description Language. Wikipedia describes it as: "an XML-based file format that provides a machine-readable description of HTTP-based web applications". I find raw WADL easy to write, read, and understand, and it maps directly to RESTful concepts. The official project provides a simple spec, XSD and RELAX NG schemata, and Java tools.
A number of tools and resources exist for working with WADL, including:
wadl_stylesheets, XSLT stylesheets to create HTML documentation from WADL files
Restlet, a Java framework for building RESTful servers and clients, includes a WADL extension
A tip: try including human-readable documentation, such as descriptions, concepts, getting started, usage tips, etc, in the WADL document's doc element by including HTML elements, using the XHTML namespace. It can make a big difference!
You might find rest-tool useful.
It follows a language agnostic approach to write specification, mock implementation and automated unit-testing for RESTful APIs. It also provides a cook-book however it is in a very early stage, but its content is continuously growing.
The services you just described can be immediately used, so it is also good for experimenting.
Initially, we went for static documentation of resources but just had to field too many questions. Eventually, we moved to using Live documentation pages using IO/Docs (actually a fork).
Been working great.
To create understanding/documentation, heavyweight solutions aren't always needed. Examples of (great) heavyweight tools are: IO/Docs / Apigee (although great tools).
For tiny projects that already have a docchain setup (doxygen/phpdoc/phpdoctor/custom/etc) I use the following shellscript to just include the page in the full generated documentation:
https://gist.github.com/4496972
A demo: http://pastie.org/5657190
It just use custom comment-tags in your sourcecode.
It can also be a nice starting point for documenting any sourcecode (language).