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 6 years ago.
Improve this question
Most REST interfaces I see are described with a simple web page describing the URL, the method, accepted input and returned result. For example the Amazon S3 or the Twitter API documentation.
Human readable is apparently good enough for Amazon or Twitter. However are there any companies describing a REST API in a machine readable format? And if yes, which ones?
WSDL 2.0 claims is capable of describing REST. WADL is explicitly created for describing REST services. Both WSDL 2.0 and WADL seem to have a rather small following atm and it seem to be little return for the effort of creating and maintaining the description documents. By identifying real life examples it is basically possible to validate or negate this assumption.
Do you use WSDL/WADL to describe your services? Do you rely on WSDL/WADL to consume others' services? Does your tool of choice support either one at the moment? Are there any examples of broadly used REST services that can be used that are detailed in a machine readable format?
Yes, you should. You will be able to generate your client code, tests and documentation using a set of tools supporting WADL. Some examples can be found here. Also, I think you should stick with WADL, rather than WSDL 2.0 because it is less verbose and way simpler (IMHO). In fact, in WADL you describe exactly what the user sees on the documentation page, just using WADL XML syntax. BTW, that is why it's so easy to write XSLT-based documentation generators for WADL.
The following is just my personal opinion:
I think WADL is similar to site maps for html pages. Site maps are considered theoretically a good practice, but rarely implemented and even more rarely used by people.
I think the reason is simple - wandering around a site and pushing strategically placed buttons is often significantly more rewarding than browsing a complex map.
REST API methods should not require a formal description. So if API is created thoughtfully it is pretty easy to discover all the resources just by following strategically placed uri links of a 'home' RESTful resource.
There's a chicken/egg phenonenon here. WADL is useless without tools that produce or consume it. The tools are useless unless sites publish WADL. etc.
For me, The Amazon model works fine. Depending on your audience you will get more return on an effort to produce samples, including snips od sample dialogs (what does request1 look like on the wire, same for response 1, then request 2, response 2, etc), and code in vvarious languages that are important to you. If you want to go to a machine-readable definition, you can use XSD if it is an XML message format. Obviously this is not WADL but coupled with your english description, it may provide a little extra utility for developers.
What is the benefit of a machine-readable REST API definition?
The point of REST is for the API to be relatively simple and easy-to-understand. Natural language works well for this.
If you mean "API Type Definitions" when you say "API Definition" then there may be some value in providing metadata. This, however, is only one piece of an API definition.
Having "machine readable" API can easily repeat the API source code, violating the DRY principle.
It's often simpler to write English descriptions of what the REST verbs do and what the URI's are. Send the type's which are marshalled through JSON (or YAML or JAXB) as source code. That's the perfect machine-readable API -- actual working source for the message object class.
The most popular usage of WSDL (and WADL in the same way) is code generation. It sure helps speed up development, but nothing can replace plain old documentation. For humans and not for machines.
Related
I am a ruby on rails developer. For my project i m writing an API calls. Angularjs will consume this API to show data on webpage.
I am good in coding but this is for the first time i will be creating SDS document.. I dont know what to lnclude in my SDS document...
I have searches on the internet about sds and found lotnof articles on it but many of them were very high level difficult to understand document .
what i should write in my SDS document As my rails code is all about API call...?? Plase share the sample document if possible...
Thanks
you should at least include some basic explanations in your SDS, even if the code is simple as you say.
Purpose, scope, used patterns(if any), database specifics, are basic sections this document should have. Sequence diagrams won't hurt too, they are great for explaining actual processes and flow
In REST URIs should be opaque to the client.
But when you build interactive javascript-based web-client for your application you actually have two clients! One for interaction with server and other one for users (actual GUI). Of course you will want to have friendly URIs, good enough to answer the question "where am I now?".
It's easier when a server just respond with HTML so people can just click on links and don't care about structure. Server provides URIs, server receives URIs.
It's easier with desktop client. The same staff. Just a button "show the resource" and user doesn't care what the URI is.
It's complicated with browser clients. There is the address bar. This leads to the fact that low-level part of web-client relies on the URIs structure of a server. Which is not RESTful.
It seems like the space between frontend and backend of the application is too tight for REST.
Does it mean that REST is not a good choice for reactive interactive js-based browser clients?
I think you're a little confused...
First of all, your initial assumption is flawed. URI opacity doesn't mean URIs have to be cryptic. It only means that clients should not rely on URI semantics for interaction. Friendly URIs are not only allowed, they are encouraged for the exact same reason you talk about: it's easier for developers to know what's going on.
Roy Fielding made that clear in the REST mailing list years ago, but it seems like that's a myth that won't go away easily:
REST does not require that a URI be opaque. The only place where the
word opaque occurs in my dissertation is where I complain about the
opaqueness of cookies. In fact, RESTful applications are, at all
times, encouraged to use human-meaningful, hierarchical identifiers in
order to maximize the serendipitous use of the information beyond what
is anticipated by the original application.
Second, you say it's easier when a server just respond with HTML so people can just follow links and don't care about structure. Well, that's exactly what REST is supposed to do. REST is merely a more formal and abstract definition of the architecture style of the web itself. Do some research on REST and HATEOAS.
Finally, to answer your question, whether REST is a good choice for you is not determined by client implementation details like that. You can have js-based clients, no problem, but the need to do that isn't reason enough to worry too much about getting REST right. REST is a good choice if you have projects with long term integration, maintainability and evolution goals. If you need something quick, that won't change a lot, or won't be integrated with a lot of different clients and services, don't worry too much about REST.
Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
We don’t allow questions seeking recommendations for books, tools, software libraries, and more. You can edit the question so it can be answered with facts and citations.
Closed 6 years ago.
Improve this question
OData is used by Netflix and in many of Microsoft's products (servers: CRM, Sharepoint, SQL Server; clients: Excel).
While OData is interesting, it has it's own set of benefits and trade-offs.
I've designed and build a custom search engine for internal use. Many developers are using the search engine for reporting and lists, replacing the reports and custom search/filter functionality in each line of business app with this search engine.
I have a decent system to allow querying/filtering in my search engine. It's all url driven so it's easy to use.
At this point, I want to add a little bit more functionality to the URL "command line". OData is a tempting choice because we use a lot of Microsoft tech already. It also has standard language for filters with Boolean logic, etc.
Are there any other legitimate standards based REST frameworks like OData that I should look at?
I'm not sure I need the full OData stack for what I'm doing. My simple query string based filtering is working very well at this point. Just want to conduct some due diligence so I can make an informed decision.
Thanks.
Edit
What I'm looking for is more of a framework for creating my search API. Lucene/Solr use a url syntax http://lucene.apache.org/solr/tutorial.html as does OData. Lucene/Solr aren't exactly what I'm looking for and are too complex for my scenario. However, they have a well defined url api.
I'm looking for any other well define url-based api examples. I want to see the "prior art" for defining a query/search syntax based on a url and query string parameters.
While some will certainly argue, rolling your own is certainly an option; provided you can release a consumable schema and syntax or API library. Given that you carefully research the current standards landscape and borrow from established (albeit unfitting) implementations, you (and supporters) could be inclined to produce a new or extended standard; perhaps one that solves an unsolved problem.
However, obligatory:
After some research it appears that no, there is not really a good alternative to OData at this point.
I'm saying this based on the features of Odata. Hopefully we'll see an alternative at some point.
Facebook is developing GraphQL. Data can be queried using JSON queries:
{
user(id: 3500401) {
id,
name,
isViewerFriend,
profilePicture(size: 50) {
uri,
width,
height
}
}
}
At the moment it is not usable. According to the Changelog they plan to release it as a kind of specification.
Here is another whitepaper
Google is pushing for GData, which seems feature crippled.
If you are looking for a web compliant search mechanism, I suggest looking at Open Search
I've been struggling with understanding a few points I keep reading regarding RESTful services. I'm hoping someone can help clarify.
1a) There seems to be a general aversion to generated code when talking about RESTful services.
1b) The argument that if you use a WADL to generate a client for a RESTful service, when the service changes - so does your client code.
Why I don't get it: Whether you are referencing a WADL and using generated code or you have manually extracted data from a RESTful response and mapped them to your UI (or whatever you're doing with them) if something changes in the underlying service it seems just as likely that the code will break in both cases. For instance, if the data returned changes from FirstName and LastName to FullName, in both instances you will have to update your code to grab the new field and perhaps handle it differently.
2) The argument that RESTful services don't need a WADL because the return types should be well-known MIME types and you should already know how to handle them.
Why I don't get it: Is the expectation that for every "type" of data a service returns there will be a unique MIME type in existence? If this is the case, does that mean the consumer of the RESTful services is expected to read the RFC to determine the structure of the returned data, how to use each field, etc.?
I've done a lot of reading to try to figure this out for myself so I hope someone can provide concrete examples and real-world scenarios.
REST can be very subtle. I've also done lots of reading on it and every once in a while I went back and read Chapter 5 of Fielding's dissertation, each time finding more insight. It was as clear as mud the first time (all though some things made sense) but only got better once I tried to apply the principles and used the building blocks.
So, based on my current understanding let's give it a go:
Why do RESTafarians not like code generation?
The short answer: If you make use of hypermedia (+links) There is no need.
Context: Explicitly defining a contract (WADL) between client and server does not reduce coupling enough: If you change the server the client breaks and you need to regenerate the code. (IMHO even automating it is just a patch to the underlying coupling issue).
REST helps you to decouple on different levels. Hypermedia discoverability is one of the goods ones to start with. See also the related concept HATEOAS
We let the client “discover” what can be done from the resource we are operating on instead of defining a contract before. We load the resource, check for “named links” and then follow those links or fill in forms (or links to forms) to update the resource. The server acts as a guide to the client via the options it proposes based on state. (Think business process / workflow / behavior). If we use a contract we need to know this "out of band" information and update the contract on change.
If we use hypermedia with links there is no need to have “separate contract”. Everything is included within the hypermedia – why design a separate document? Even URI templates are out of band information but if kept simple can work like Amazon S3.
Yes, we still need a common ground to stand on when transferring representations (hypermedia), so we define your own media types or use widely accepted ones such as Atom or Micro-formats. Thus, with the constraints of basic building blocks (link + forms + data - hypermedia) we reduce coupling by keeping out of band information to a minimum.
As first it seems that going for hypermedia does not change the impact of change :) : But, there are subtle differences. For one, if I have a WADL I need to update another doc and deploy/distribute. Using pure hypermedia there is no impact since it's embedded. (Imagine changes rippling through a complex interweave of systems). As per your example having FirstName + LastName and adding FullName does not really impact the clients, but removing First+Last and replacing with FullName does even in hypermedia.
As a side note: The REST uniform interface (verb constraints - GET, PUT, POST, DELETE + other verbs) decouples implementation from services.
Maybe I'm totally wrong but another possibility might be a “psychological kick back” to code generation: WADL makes one think of the WSDL(contract) part in “traditional web services (WSDL+SOAP)” / RPC which goes against REST. In REST state is transferred via hypermedia and not RPC which are method calls to update state on the server.
Disclaimer: I've not completed the referenced article in detail but I does give some great points.
I have worked on API projects for quite a while.
To answer your first question.
Yes, If the services return values change (Ex: First name and Last name becomes Full Name) your code might break. You will no longer get the first name and last name.
You have to understand that WADL is a Agreement. If it has to change, then the client needs to be notified. To avoid breaking the client code, we release a new version of the API.
The version 1.0 will have First Name and last name without breaking your code. We will release 1.1 version which will have the change to Full name.
So the answer in short, WADL is there to stay. As long as you use that version of the API. Your code will not break. If you want to get full name, then you have to move to the new versions. With lot of code generation plugins in the technology market, generating the code should not be a issue.
To answer your next question of why not WADL and how you get to know the mime types.
WADL is for code generation and serves as a contract. With that you can use JAXB or any mapping framework to convert the JSON string to generated bean objects.
If not WADL, you don't need to inspect every element to determine the type. You can easily do this.
var obj =
jQuery.parseJSON('{"name":"John"}');
alert( obj.name === "John" );
Let me know, If you have any questions.
When providing a web services API (well, let's say SOAP), do you provide a library wrapper along with it to make it "easier" for people to use? Or do you just package up a WSDL and documentation for it and let people figure out what to do with it?
What are people doing usually? I've seen a bunch of examples where the wrapper is provided, but it has always seemed counter-productive to me.
WSDL is easily discoverable (all functions & types as declared), so there is usually no need to offer any package with it, and minimal documentation (apply an XSL to the WDSL and it's usually enough :) ). My theory about the appearance of libraries/wrappers is that it is directly related to security measures / needed authentication & hashes (usually: concatenating some fields with a secret & hash it), about which one simply doesn't want to answer every single question anymore.
Audience matters I think: if you want you run-of-the-mill hobby coder to be able to use your service, providing a package can get you that much more users. If you're more in business to business services, the webservice usually has to be integrated in some larger package and most libraries would be futile.
That being said, I'd say of the webservices I came across: about 60% of the libraries provided were hopeless spaghetti code fit for the bin, 30% were not the code I'd use, but could clear up some questions not answered by the documentation, and only about 10% were fit enough to integrate in a project (or the project small and/or worse enough to be no worse for it).
How you going to support multiple web-service stacks - JAX-WS, AXIS2, CXF etc? My choice - WSDL/XSD. In practice I got service built with JAX-WS and a client with AXIS2. And I don't want to build a client wich you are going to use. I don't even know your preferable web-service stack and your JVM version limitations. For example, I can call web-service from java 1.4 - there are no annotations and not possible to use client lib built with annotations for java 1.5. So WSDL is right way to build ws-client instead of providing generated client library.