I have retrieved the component details using
.com/ccm/resource/itemOid/com.ibm.team.scm.Component/_C8OiATcYEeORAOTpOLW3QQ/?_mediaType=text/xml
then retrieved baseline from above output "" using
.com/ccm/resource/itemOid/com.ibm.team.scm.Baseline/_C8hc_DcYEeORAOTpOLW3QQ/?_mediaType=text/xml";
Now I want to retrieve history from above output "" so that I can get the list of all changesets along with the UUIDs...
Can anyone please help me out for this, Im really stuck at this since long time.
Thanks in advance
Firstly, URLs of that pattern are not part of Jazz's OSLC interface.
The OSLC interfaces are only part of the Jazz products' REST interfaces - they have product-specific (non-standardized) REST interfaces too, in contrast to the standardized (but less specific) OSLC interfaces.
The way to tell the difference is, if you get the XML representation of the response to a URL, then if it doesn't contain a namespace whose URI includes "open-services.net" then it isn't part of the OSLC interface.
RTC doesn't support either the OSLC Software Configuration Management specification nor the later OSLC Configuration Management work and therefore I do not believe it is possible to achieve this using its OSLC interfaces.
(Sources: jazz.net RTC tickets Finish/continue OSLC configuration management support and OSLC SCM catalog entry has wrong URL for oslc_disc:services).
I know this doesn't answer your question as to how to get that information. I do not know if the information is available via the non-OSLC REST API (which you are already looking at). But perhaps this information might help you exclude misleading information (anything about OSLC in your search.)
Also, if you want this to be properly supported in the RTC OSLC API, try commenting on the ticket Finish/continue OSLC configuration management support stating your desire for this to be implemented.
Disclosure/disclaimer: I am an IBM employee, but do not work on the development of Jazz products. My postings on this site are my own and don't necessarily represent IBM's positions, strategies or opinions.
Related
Lets say I have a REST API where developers can publish offerings of properties (adress, price, living space) using
POST /offerings
Users can browse these offerings using
GET /offerings?page=0
Now I have a problem. Commercially used properties are handled on a different service (although they do end up on a common database)ยท The easiest way would be a separate endpoint and then redirect it using nginx.
POST /commericalOfferings
But is this still restful design? I was looking through a bunch of definitions for restful design but I can't come up with a clear answer.
Especially since theres no GET for commercialOfferings
So does anyone know if this is still a valid architecture?
is this still restful design?
It's fine.
There is nothing in REST that requires that information have one-and-exactly-one resource.
For example, the "authors' preferred version" of an academic paper is a mapping whose value changes over time, whereas a mapping to "the paper published in the proceedings of conference X" is static. These are two distinct resources, even if they both map to the same value at some point in time. The distinction is necessary so that both resources can be identified and referenced independently. A similar example from software engineering is the separate identification of a version-controlled source code file when referring to the "latest revision", "revision number 1.2.7", or "revision included with the Orange release." -- Fielding, 2000
As always, your basic heuristic for "it is RESTful" is to ask yourself: does it behave like a web site? If it does, then you are good.
It is okay, though I would do something different:
POST /offerings {commercial:true, ...}
GET /offerings?commercial=false&page=0
REST doesn't cover such design decisions, it works on a higher abstraction level. It just says that you must follow standards like HTTP, URI, etc. to build a uniform interface, something similar to OOP interfaces just on an inter-application communication level not on an inter-object communication level. Having nice URI-s like the upper is not a REST constraint either, nice URIs are just an unofficial recommendation, not a standard to follow. https://en.wikipedia.org/wiki/Clean_URL In REST there is a constraint called HATEOAS, which means you send hyperlinks in your responses and the client follows these hyperlinks - like you follow them by browsing a web page - instead of having hardcoded URI templates or building the URIs themselves, this is why from client perspective the URI structure does not matter at all. HATEOAS is part of the uniform interface constraint. And every REST constraint is mandatory except code-on-demand. https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm From service perspective the URI structure matters, it is easier to configure the router if you follow the nice URI recommendation.
I'm trying to figure out what the latest best practice is when it comes to REST APIs and finding an elegant way to "tell" the client what the response will look like. I'm no web expert. But I just recently joined a new team and I've noticed that in the client code, they have hardcoded URI to APIs... and anytime the schema of the return data changes, they have to patch their client code.
Trying to find a way to make things more dynamic by:
introducing patterns to "discover" API servers.
looking into HATEOAS.
More than anything else though, what I'm trying improve is having to change the client code each time the logic on the server changes as far as the body of a GET response.
I've been reading this:
https://www.programmableweb.com/news/rest-api-design-put-type-content-type/2011/11/18
And in particular, the following comments stood out to me: (under the WRML heading)
this media type communicates, directly to clients, distinct and
complementary bits of information regarding the content of a message.
The Web Resource Modeling Language (WRML, www.wrml.org) provides this
"pluggable" media type to give rich web applications direct access to
structural information and format serialization code. The media type's
self-descriptive and pluggable design reduces the need for information
to be communicated out-of-band and then hard-coded by client
developers
Questions
is WRML still a thing? this book that i'm reading is from 2011... and I'm assuming a lot has changed since then.
Can I cheaply build my own inhouse solution where we use the Content-Type or some other header to provide the clients with schema information?
can you point me to an example / sample code where someone is using custom values in Content-Type or other Headers to accomplish something similar?
Or if you have any other suggestions I'm all ears.
Thank you.
I don't know much about WRML, but I would look into:
HATEOAS formats like HAL/HAL Forms and Siren, which are self-describing.
JSON-Schema to describe responses and requests (and yes they can be linked from HATEOAS responses).
If you don't want to go the hypermedia route, OpenAPI and RAML
I've been developing Ketting for the last 5 years and HATEOAS has been nothing short of magic lately as all the tools have been falling into place.
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.
For a SaaS startup I'm involved in, I am building both a RESTful web API and a couple of client apps on different platforms that consume it. I think I've got the API figured out, but now I'm turning to the clients. As I've been reading about REST, I see that a key part of REST is discovery, but there seems to be a lot of debate between two different interpretations of what discovery really means:
Developer discovery: The developer hard-codes copious amounts of API details into the client, such as resource URI's, query parameters, supported HTTP methods, and other details that they've discovered through browsing the docs and experimenting with the API's responses. This type of discovery IMHO necessitates cool linkage and the API versioning question, and leads to hard coupling of the client code to the API. Not much better than if using a well-documented collection of RPC's it seems.
Runtime discovery - The client app itself is able to figure out everything it needs with little or no out-of-band information (presumably, only a knowledge of the media types the API deals with.) Links can be hot. But to make the API very efficient, a lot of link templating for query parameters seems to be needed, which makes out-of-band info creep back in. There are possibly other difficulties I haven't thought of yet since I haven't gotten to that point in development. But I do like the idea of loose coupling.
Runtime discovery seems to be the holy grail of REST, but I'm seeing precious little discussion about how to implement such a client. Almost all REST sources I've found seem to assume Developer discovery. Anyone know of some Runtime discovery resources? Best practices? Examples or libraries with real code? I'm working in PHP (Zend Framework) for one client. Objective-C (iOS) for the other.
Is Runtime discovery a realistic goal, given the present set of tools and knowledge in the developer community? I can write my client to treat all of the URI's in an opaque manner, but how to do this most efficiently is a question, especially over low-bandwidth connections. Anyway, URI's are only part of the equation. What about link templating in the Runtime context? How about communicating what methods are supported, aside from making a lot of OPTIONS requests?
This is definitely a tough nut to crack. At Google, we've implemented our Discovery Service that all our new APIs are built against. The TL;DR version is we generate a JSON Schema-like spec that our clients can parse - many of them dynamically.
That results means easier SDK upgrades for the developer and easy/better maintenance for us.
By no means the perfect solution, but many of our devs seem to like.
See link for more details (and make sure to watch the vid.)
Fascinating. What you are describing is basically the HATEOAS principle. What is HATEOAS you ask? Read this: http://en.wikipedia.org/wiki/HATEOAS
In layman's terms, HATEOAS means link following. This approach decouples your client from specific URL's and gives you the flexibility to change your API without breaking anyone.
You did your home work and you got to the heart of it: runtime discovery is holy grail. Don't chase it.
UDDI tells a poignant story of runtime discovery: http://en.wikipedia.org/wiki/Universal_Description_Discovery_and_Integration
One of the requirements that should be satisfied before you can call an API 'RESTful' is that it should be possible to write a generic client application on top of that API. With the generic client, a user should be able to access all the API's functionality. A generic client is a client application that does not assume that any resource has a specific structure beyond the structure that is defined by the media type. For example, a web browser is a generic client that knows how to interpret HTML, including HTML forms etc.
Now, suppose we have a HTTP/JSON API for a web shop and we want to build a HTML/CSS/JavaScript client that gives our customers an excellent user experience. Would it be a realistic option to let that client be a generic client application? No. We want to provide a specific look-and-feel for every specific data element and every specific application state. We don't want to include all knowledge about these presentation-specifics in the API, on the contrary, the client should define the look and feel and the API should only carry the data. This implies that the client has hard-coded coupling of specific resource elements to specific layouts and user interactions.
Is this the end of HATEOAS and thus the end of REST? Yes and no.
Yes, because if we hard-code knowledge about the API into the client, we loose the benefit of HATEOAS: server-side changes may break the client.
No, for two reasons:
Being "RESTful" is a property of the API, not of the client. As long as it is possible, in theory, to build a generic client that offers all capabilities of the API, the API can be called RESTful. The fact that clients don't obey the rules, is not the API's fault. The fact that a generic client would have a lousy user experience is not an issue. Why is it important to know that it is possible to have a generic client, if we don't actually have that generic client? This brings me to the second reason:
A RESTful API offers clients the option to choose how generic they want to be, i.e. how resilient to server-side changes they want to be. Clients which need to provide a great user experience may still be resilient to URI changes, to changes in default values and more. Clients doing batch jobs without user interaction may be resilient to other kinds of changes.
If you are interested in practical examples, checkout my JAREST paper. The last section is about HATEOAS. You will see that with JAREST, even highly interactive and visually attractive clients can be quite resilient to server-side changes, though not 100%.
I think the important point about HATEOAS is not that it is some holy grail client-side, but that it isolates the client from URI changes - it is assumed you are using known (or developer discovered custom) Link Relations that will allow the system to know which link for an object is the editable form. The important point is to use a media type that is hypermedia aware (e.g. HTML, XHTML, etc).
You write:
To make the API very efficient, a lot of link templating for query parameters seems to be needed, which makes out-of-band info creep back in.
If that link template is supplied in the previous request, then there is no out-of-band information. For example a HTML search form uses link templating (/search?q=%#) to generate a URL (/search?q=hateoas), but nothing is known by the client (the web browser) other than how to use HTML forms and GET.
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).