• Post Reply Bookmark Topic Watch Topic
  • New Topic
programming forums Java Mobile Certification Databases Caching Books Engineering Micro Controllers OS Languages Paradigms IDEs Build Tools Frameworks Application Servers Open Source This Site Careers Other all forums
this forum made possible by our volunteer staff, including ...
Marshals:
  • Campbell Ritchie
  • Devaka Cooray
  • Knute Snortum
  • Paul Clapham
  • Tim Cooke
Sheriffs:
  • Liutauras Vilda
  • Jeanne Boyarsky
  • Bear Bibeault
Saloon Keepers:
  • Tim Moores
  • Stephan van Hulst
  • Ron McLeod
  • Piet Souris
  • Frits Walraven
Bartenders:
  • Ganesh Patekar
  • Tim Holloway
  • salvin francis

RESTFul web services - is there any standard to describe resources that are targeted by an API ?  RSS feed

 
Bartender
Posts: 1139
38
IBM DB2 Java Netbeans IDE Spring
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
As far as I know, there's no equivalent of a WSDL document for RESTful web services.  With respect to operations, I agree that it's not so necessary to have a formal document to  describe which operations you may invoke on a resource - the HTTP verb that apply on an URL  should be enough.
So, If I know that with a RESTFul web services handles an entity called "Customer",  I will create / update an existing Customer with a POST action while I will delete an existing Customer with a DELETE issued on a certain URL.

But what about the Customer resource itself ? How could I  know how a "Customer" entity is made ? I've heard about Swagger, but I don't think it's a standard like WSDL, despite the fact it looks promising.
Any hint ?



 
Bartender
Posts: 1868
81
Android Chrome IntelliJ IDE Java MySQL Database
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
You may want to look into OData (http://www.odata.org/) which is supported by some of the major database players out there like Oracle, SAP, Microsoft and more

OData.org wrote:OData (Open Data Protocol) is an ISO/IEC approved, OASIS standard that defines a set of best practices for building and consuming RESTful APIs. OData helps you focus on your business logic while building RESTful APIs without having to worry about the various approaches to define request and response headers, status codes, HTTP methods, URL conventions, media types, payload formats, query options, etc. OData also provides guidance for tracking changes, defining functions/actions for reusable procedures, and sending asynchronous/batch requests.

OData RESTful APIs are easy to consume. The OData metadata, a machine-readable description of the data model of the APIs, enables the creation of powerful generic client proxies and tools.


If the database does not support this out of the box you may be able to get a plugin/library for it. I know that there is at least one for MySQL.
There are also client libraries to help your code interpret the OData if your programming environment/language does support OData naively.
 
Claude Moore
Bartender
Posts: 1139
38
IBM DB2 Java Netbeans IDE Spring
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Thanks Pete for your quick answer !
Well, I've heard mixed opinions about OData, and I played myself with it a bit with Olingo implementation.  It's really powerful, but it gave me the impression that it's Microsoft's (or SAP's ?) reinterpretation of REST services, just like if they felt that REST wasn't enough and they needed to do "rest their own way".
This doesn't imply that OData isn't a better way to work with RESTFul web services, of course, it's just mine impression.
Moreover, at least for me, it's to much database oriented... I mean, at least for Java any decent example I've seen was JPA related, while I'm looking for a general way to consume entities (with or without JPA).
 
Pete Letkeman
Bartender
Posts: 1868
81
Android Chrome IntelliJ IDE Java MySQL Database
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Yes, OData is all about the data. Looking at the board members https://www.oasis-open.org/committees/membership.php?wg_abbrev=odata it looks like it's mainly being steered by Microsoft, IBM, RedHat, and SAP.

However this is an open standard, in much the same way the HTML or XML is an open standard and it appears to use REST as a basis and redefines or refines some parts.
One of the problems in today's age is that there are too many standards so companies use what works for them at the moment. I think that until everyone agrees on a few standards this problem will continue.

Many programs and processes today are driven by databases in some way and from your initial post I suspected that you were talking about databases.
Sorry if I misinterpreted your initial post.

 
Saloon Keeper
Posts: 5475
143
Android Firefox Browser Mac OS X Safari Tomcat Server VI Editor
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
You may want to check out WADL (spec at W3C), which is supported by Jersey, the JAX-RS reference implementation. It does for REST WS sort of what WSDL does for SOAP.
 
Pete Letkeman
Bartender
Posts: 1868
81
Android Chrome IntelliJ IDE Java MySQL Database
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Here is a listing of some standards for RESTful API Description Languages
https://en.wikipedia.org/wiki/Overview_of_RESTful_API_Description_Languages

In that listing you will find WADL which was mentioned by Tim in the previous post.

I'm not too sure if there is any one standard that everyone follows and if there is I'm not too sure what it is.
WADL does look like maybe it could be the winner, but then again there are many different clients out there as well.
It's not like the web browser wars, of the late 90s to today, where there are only a handful of web browsers.
 
Claude Moore
Bartender
Posts: 1139
38
IBM DB2 Java Netbeans IDE Spring
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator

Pete Letkeman wrote:
Many programs and processes today are driven by databases in some way and from your initial post I suspected that you were talking about databases.


That's true, nowadays there's a great hype on exposing database record directly via REST. But to keep generality, I would not follow this approach. I  prefer to develop a service which is in turn responsible for acquiring data and expose them via services, with or without JPA.
About OData: of course it's not a problem if it's a REST approach powered by Microsoft or other vendors like SAP.  As far as I read anyway it doesn't seem to be very spread among Java developers. For example Spring Boot it's all about RestTemplate, Wildfly microprofile is RestEasy oriented and so on.
And to be honest, Apache Olingo implementation looks like a bit cumbersome. I've read the tutorials, a lot of boilerplate code is required to work with it.

Despite these personal thoughts, no matter the approach you choose it doesn't seem to exist a straightforward way to derive an entity structure from a REST endpoint. Of course, one could execute a GET on a REST service like http://someurl/entity/description and get JSON format of all properties the required entity is made of,but i wonder if this may be a correct approach.



 
Saloon Keeper
Posts: 2566
323
Android Angular Framework Eclipse IDE Java Linux MySQL Database Redhat TypeScript
  • Likes 2
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
The approach I have used in the past was to create metadata resources, which not only described the resource's attributes and associated types, but also information which would be useful for user interfaces such as a CLI or browser-based UI such as a display name, help text, or if the attribute was read-only or not.

Using Java Annotations, I specify the various metadata attributes for the resource on a per-field basis.  In the class below, the metadata information is specified using a @Metadata annotation.

When the client GETs a resource, I add a HTTP Link header with a relationship attribute of metadata, which the client can retrieve if requires the metadata for the resource.  I also include HTTP Links for operations permitted for the particular resource such as the ability to update or delete the resource.  This information could have been included in the body, but I prefer to only provide the information if the client specifically asks for it.

The metadata information is created at request time, primarily by inspecting the to @Metadata annotation for the entity for the resource using Java Reflection.


I use a similar Annotation/Reflection based scheme to create the navigation links, so that the client can discover the what types of resources are available in the resource tree.  If the client wants to learn what resources are related to configuration, it would start with GETing /api/profile/Test2/config, see what HTTP Links are returned with a nav relationship, then GET URIs, and so on.  For example, this would be the series of transactions to traverse from config to the appnet static route resource:

   /api/profile/Test2/config
   /api/profile/Test2/config/epc
   /api/profile/Test2/config/epc/pdn
   /api/profile/Test2/config/epc/pdn/Default_PDN
   /api/profile/Test2/config/epc/pdn/Default_PDN/static-route
   /api/profile/Test2/config/epc/pdn/Default_PDN/static-route/appnet

 
Claude Moore
Bartender
Posts: 1139
38
IBM DB2 Java Netbeans IDE Spring
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Ron, thanks a lot for your detailed (and excellent) solution. I found it very interesting; looks a lot like HATEOS with  self-describing services.

 
Don't get me started about those stupid light bulbs.
  • Post Reply Bookmark Topic Watch Topic
  • New Topic
Boost this thread!